From 1a06ce16b20c642fba7aa1e2c4ea0ad71bd3605b Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 8 Nov 2022 17:36:46 +0100
Subject: [PATCH] man: document the new --with switch of systemd-dissect

---
 man/systemd-dissect.xml | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml
index 955909ff914..f857ecacc7c 100644
--- a/man/systemd-dissect.xml
+++ b/man/systemd-dissect.xml
@@ -34,6 +34,9 @@
     <cmdsynopsis>
       <command>systemd-dissect <arg choice="opt" rep="repeat">OPTIONS</arg> <option>--list</option> <arg choice="plain"><replaceable>IMAGE</replaceable></arg></command>
     </cmdsynopsis>
+    <cmdsynopsis>
+      <command>systemd-dissect <arg choice="opt" rep="repeat">OPTIONS</arg> <option>--with</option> <arg choice="plain"><replaceable>IMAGE</replaceable></arg> <arg choice="opt" rep="repeat"><replaceable>COMMAND</replaceable></arg></command>
+    </cmdsynopsis>
     <cmdsynopsis>
       <command>systemd-dissect <arg choice="opt" rep="repeat">OPTIONS</arg> <option>--copy-from</option> <arg choice="plain"><replaceable>IMAGE</replaceable></arg> <arg choice="plain"><replaceable>PATH</replaceable></arg> <arg choice="opt"><replaceable>TARGET</replaceable></arg></command>
     </cmdsynopsis>
@@ -160,6 +163,19 @@
         standard output.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--with</option></term>
+
+        <listitem><para>Runs the specified command with the specified OS image mounted. This will mount the
+        image to a temporary directory, switch the current working directory to it, and invoke the specified
+        command line as child process. Once the process ends it will unmount the image again, and remove the
+        temporary directory. If no command is specified a shell is invoked. The image is mounted writable,
+        use <option>--read-only</option> to switch to read-only operation. The invoked process will have the
+        <varname>$SYSTEMD_DISSECT_ROOT</varname> environment variable set, containing the absolute path name
+        of the temporary mount point, i.e. the same directory that is set as the current working
+        directory.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>--copy-from</option></term>
         <term><option>-x</option></term>
@@ -294,14 +310,24 @@
       <xi:include href="standard-options.xml" xpointer="no-legend" />
       <xi:include href="standard-options.xml" xpointer="json" />
     </variablelist>
-
   </refsect1>
 
   <refsect1>
     <title>Exit status</title>
 
-    <para>On success, 0 is returned, a non-zero failure code
-    otherwise.</para>
+    <para>On success, 0 is returned, a non-zero failure code otherwise. If the <option>--with</option>
+    command is used the exit status of the invoked command is propagated.</para>
+  </refsect1>
+
+
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Generate a tarball from an OS disk image</title>
+
+      <programlisting>$ systemd-dissect --with foo.raw tar cz . > foo.tar.gz</programlisting>
+    </example>
   </refsect1>
 
   <refsect1>
-- 
2.47.3