diff --git a/man/ostree-prepare-root.xml b/man/ostree-prepare-root.xml
index 70371b7bc5..a944f87b54 100644
--- a/man/ostree-prepare-root.xml
+++ b/man/ostree-prepare-root.xml
@@ -120,20 +120,25 @@ License along with this library. If not, see .
root.transient
A boolean value; the default is false.
- If this is set to true, then the / filesystem will be a writable overlayfs,
- with the upper directory being a hidden directory (in the underlying system root filesystem) that will persist across reboots by default.
- However, changes will be discarded on OS updates!
+ Setting this flag to true requires composefs (See composefs.enabled).
+ When enabled, the root mount point / will be an overlayfs whose contents will be stored
+ in a tmpfs, and hence discarded on OS upgrade or reboot.
- Enabling this option can be very useful for cases such as packages (dpkg/rpm/etc) that write content into /opt,
- particularly where they expect the target to be writable at runtime. To make that work, ensure that your /opt
- directory is *not* a symlink to /var/opt, but is just an empty directory.
-
-
- Note the /usr mount point remains read-only by default. This option is independent of etc.transient and sysroot.readonly;
+ This option is independent of etc.transient and sysroot.readonly;
it is supported for example to have root.transient=true but etc.transient=false in which case changes to /etc continue
to persist across updates, with the default OSTree 3-way merge applied.
-
+ Also related to persistence it is important to emphasize that /sysroot (the physical root filesystem) is still persistent
+ by default; in-place OS upgrades can be applied.
+
+
+ Enabling this option can make it significantly easier to adopt an image-based model in some circumstances.
+ For example, if you have a configuration management system that is inspecting machine-specific state and
+ e.g. dynamically installing packages or applying configuration, it can more easily be adapted to
+ run on each boot, while still shifting a portion (or ideally most) image configuration to build time
+ as part of the base image/commit.
+
+
composefs.enabled