From f7aa7ec6c25be3d42ea434ef8f24bff19827a39e Mon Sep 17 00:00:00 2001
From: Evan Goode <mail@evangoo.de>
Date: Tue, 17 Dec 2024 18:58:32 +0000
Subject: [PATCH] bootc: Document `--transient` and `persistence`

Documents the new `--transient` command-line argument and `persistence`
configuration option. I tried to use a table for listing the valid
options for `persistence`, but RST does not automatically wrap table
cells containing long lines, so a list was much easier.
---
 doc/command_ref.rst |  5 +++++
 doc/conf_ref.rst    | 11 +++++++++++
 2 files changed, 16 insertions(+)

diff --git a/doc/command_ref.rst b/doc/command_ref.rst
index fd4a665503..bffa297c52 100644
--- a/doc/command_ref.rst
+++ b/doc/command_ref.rst
@@ -387,6 +387,11 @@ Options
 ``--showduplicates``
     Show duplicate packages in repositories. Applicable for the list and search commands.
 
+.. _transient_option-label:
+
+``--transient``
+    Applicable only on bootc systems. Perform transactions using a transient overlay which will reset on reboot. See also the :ref:`persistence <persistence-label>` configuration option.
+
 .. _verbose_options-label:
 
 ``-v, --verbose``
diff --git a/doc/conf_ref.rst b/doc/conf_ref.rst
index b7bd4b71f4..5c21125c98 100644
--- a/doc/conf_ref.rst
+++ b/doc/conf_ref.rst
@@ -442,6 +442,17 @@ configuration file by your distribution to override the DNF defaults.
 
     Directory where DNF stores its persistent data between runs. Default is ``"/var/lib/dnf"``.
 
+.. _persistence-label:
+
+``persistence``
+    :ref:`string <string-label>`
+
+    Whether changes should persist on system reboot. Default is ``auto``. Passing :ref:`--transient <transient_option-label>` will override this setting to ``transient``. Valid values are:
+
+    * ``auto``: Changes will persist across reboots, unless the target is a running bootc system and the system is already in an unlocked state (i.e. ``/usr`` is writable).
+    * ``transient``: Changes will reset on reboot. Only applicable on bootc systems. Beware that changes to ``/etc`` and ``/var`` will persist, depending on the configuration of your bootc system. See also https://containers.github.io/bootc/man/bootc-usr-overlay.html.
+    * ``persist``: Changes will persist across reboots.
+
 .. _pluginconfpath-label:
 
 ``pluginconfpath``