man: document the new --with switch of systemd-dissect

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>