From d2510fdbe2ff1fec3ca806e4928901b137c361c0 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Thu, 4 Mar 2021 17:38:19 +0000
Subject: [PATCH] man: Add docs for apply-live

Let's try to keep up rigor around keeping the man pages up to date.
---
 man/rpm-ostree.xml | 48 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/man/rpm-ostree.xml b/man/rpm-ostree.xml
index 67dd71bf..38bee4fd 100644
--- a/man/rpm-ostree.xml
+++ b/man/rpm-ostree.xml
@@ -656,12 +656,58 @@ Boston, MA 02111-1307, USA.
             This command offers access to experimental features; command line
             stability is not guaranteed.  The available subcommands will be listed
             by invoking <command>rpm-ostree ex</command>.  For example, there is
-            <command>rpm-ostree ex livefs</command> which is an experimental
+            <command>rpm-ostree ex apply-live</command> which is an experimental
             interface for applying changes to the booted deployment.
           </para>
         </listitem>
       </varlistentry>
 
+
+      <varlistentry>
+        <term><command>ex apply-live</command></term>
+
+        <listitem>
+          <para>
+            Experimental feature; subject to change.
+          </para>
+
+          <para>
+            Given a target OSTree commit (defaults to the pending deployment), create a transient
+            <literal>overlayfs</literal> filesystem for <literal>/usr</literal>, and synchronize
+            the changes to the booted filesystem tree.
+          </para>
+
+          <para>
+            <option>--reset</option> to reset the filesystem tree to the booted commit.
+          </para>
+
+          <para>
+            <option>--target</option> may be used to target an arbitrary OSTree commit.  This is an advanced feature, exposed mainly for testing.
+          </para>
+
+          <example>
+            <title>Install postgresql live</title>
+
+            <programlisting>$ rpm-ostree install postgresql-server
+$ rpm-ostree ex apply-live
+$ systemctl start postgresql  # Some setup required
+            </programlisting>
+          </example>
+
+          <para>
+            Currently, this just synchronizes the filesystem; no systemd units are restarted
+            for example.
+          </para>
+
+          <para>
+            A major implicit benefit of the <literal>overlayfs</literal> approach is that
+            if something goes wrong in the middle of a <literal>apply-live</literal> operation,
+            a system reboot will implicitly remove the overlay, restoring the system to 
+            the pristine deployment state.
+          </para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><command>ex initramfs-etc</command></term>