man: document the new grow-file-system flag

1 files changed, 42 insertions, 18 deletions

diff --git a/docs/DISCOVERABLE_PARTITIONS.md b/docs/DISCOVERABLE_PARTITIONS.md
index c4074702c4..656a516f97 100644
--- a/docs/DISCOVERABLE_PARTITIONS.md
+++ b/docs/DISCOVERABLE_PARTITIONS.md
@@ -94,24 +94,48 @@ localized.
 
 ## Partition Flags
 
-For the root, `/usr/`, server data, home, variable data, temporary data and swap
-partitions, the partition flag bit 63 ("*no-auto*") may be used to turn off
-auto-discovery for the specific partition.  If set, the partition will not be
-automatically mounted or enabled.
-
-For the root, `/usr/`, server data, home, variable data and temporary data
-partitions, the partition flag bit 60 ("*read-only*") may be used to mark a
-partition for read-only mounts only.  If set, the partition will be mounted
-read-only instead of read-write. Note that the variable data partition and the
-temporary data partition will generally not be able to serve their purpose if
-marked read-only, since by their very definition they are supposed to be
-mutable. (The home and server data partitions are generally assumed to be
-mutable as well, but the requirement for them is not equally strong.) Because
-of that, while the read-only flag is defined and supported, it's almost never a
-good idea to actually use it for these partitions.
-
-Note that these two flag definitions happen to map nicely to the ones used by
-Microsoft Basic Data Partitions.
+This specification defines three GPT partition flags that may be set for the
+partition types defined above:
+
+1. For the root, `/usr/`, Verity, home, server data, variable data, temporary data,
+   swap and extended boot loader partitions, the partition flag bit 63
+   ("*no-auto*") may be used to turn off auto-discovery for the specific
+   partition.  If set, the partition will not be automatically mounted or
+   enabled.
+
+2. For the root, `/usr/`, Verity, home, server data, variable data, temporary
+   data and extended boot loader partitions, the partition flag bit 60
+   ("*read-only*") may be used to mark a partition for read-only mounts only.
+   If set, the partition will be mounted read-only instead of read-write. Note
+   that the variable data partition and the temporary data partition will
+   generally not be able to serve their purpose if marked read-only, since by
+   their very definition they are supposed to be mutable. (The home and server
+   data partitions are generally assumed to be mutable as well, but the
+   requirement for them is not equally strong.) Because of that, while the
+   read-only flag is defined and supported, it's almost never a good idea to
+   actually use it for these partitions. Also note that Verity partitions are
+   by their semantics always read-only. The flag is hence of little effect for
+   them, and it is recommended to set it unconditionally for the Verity
+   partition types.
+
+3. For the root, `/usr/`, home, server data, variable data, temporary data and
+   extended boot loader partitions, the partition flag bit 59
+   ("*grow-file-system*") may be used to mark a partition for automatic growing
+   of the contained file system to the size of the partition when
+   mounted. Tools that automatically mount disk image with a GPT partition
+   table are suggested to implicitly grow the contained file system to the
+   partition size they are contained in. This flag is without effect on
+   partitions marked read-only.
+
+Note that the first two flag definitions happen to map nicely to the ones used
+by Microsoft Basic Data Partitions.
+
+All three of these flags generally affect only auto-discovery and automatic
+mounting of disk images. If partitions marked with these flags are mounted
+using low-level commands like
+[mount(8)](https://man7.org/linux/man-pages/man2/mount.8.html) or directly with
+[mount(2)](https://man7.org/linux/man-pages/man2/mount.2.html), they typically
+have no effect.
 
 ## Suggested Mode of Operation