btrfs-progs: docs: update dump-tree

Signed-off-by: David Sterba <dsterba@suse.com>

2 files changed, 34 insertions, 25 deletions

diff --git a/Documentation/btrfs-inspect-internal.asciidoc b/Documentation/btrfs-inspect-internal.asciidoc
index bbbbc597..f19522f4 100644
--- a/Documentation/btrfs-inspect-internal.asciidoc
+++ b/Documentation/btrfs-inspect-internal.asciidoc
@@ -20,29 +20,33 @@ requires calls to privileged ioctls.
 SUBCOMMAND
 ----------
 *dump-tree* [options] <device>::
-(needs root privileges)
+(may need root privileges to access the device)
++
+Dump tree structures from a given device in textual form, expand keys to human
+readable equivalents where possible.
+This is useful for analyzing filesystem state or inconsistencies and has
+a positive educational effect on understanding the internal filesystem structure.
 +
-Dump the whole tree of the given device.
-This is useful for analyzing filesystem state or inconsistence and has
-a positive educational effect on understanding the internal structure.
-<device> is the device file where the filesystem is stored.
+NOTE: contains file names, consider that if you're asked to send the dump for
+analysis. Does not contain file data.
 +
 `Options`
 +
--e::::
-Print detailed extents info.
--d::::
-Print info of btrfs device and root tree dirs only.
--r::::
-Print info of roots only.
--R::::
-Print info of roots and root backups.
--u::::
-Print info of UUID tree only.
+-e|--extents::::
+print only extent-related information: extent and device trees
+-d|--device::::
+print only device-related information: tree root, chunk and device trees
+-r|--roots::::
+print only short root node information, ie. the root tree keys
+-R|--backups::::
+same as --roots plus print backup root info, ie. the backup root keys and
+the respective tree root block offset
+-u|--uuid::::
+print only the uuid tree information, empty output if the tree does not exist
 -b <block_num>::::
-Print info of the specified block only.
+print info of the specified block only
 -t <tree_id>::::
-Print only the tree with the specified ID.
+print only the tree with the specified numerical ID
 
 *inode-resolve* [-v] <ino> <path>::
 (needs root privileges)
diff --git a/cmds-inspect-dump-tree.c b/cmds-inspect-dump-tree.c
index 159888c5..f548efa4 100644
--- a/cmds-inspect-dump-tree.c
+++ b/cmds-inspect-dump-tree.c
@@ -108,14 +108,19 @@ static void print_old_roots(struct btrfs_super_block *super)
 
 const char * const cmd_inspect_dump_tree_usage[] = {
 	"btrfs inspect-internal dump-tree [options] device",
-	"Dump structures from a device",
-	"-e|--extents           print detailed extents info",
-	"-d|--device            print info of btrfs device and root tree dir only",
-	"-r|--roots             print info of roots only",
-	"-R|--backups           print info of roots and root backups",
-	"-u|--uuid              print info of uuid tree only",
-	"-b|--block <block_num> print info of the specified block only",
-	"-t|--tree  <tree_id>   print only the tree with the given id",
+	"Dump tree structures from a given device",
+	"Dump tree structures from a given device in textual form, expand keys to human",
+	"readable equivalents where possible.",
+	"Note: contains file names, consider that if you're asked to send the dump",
+	"for analysis.",
+	"",
+	"-e|--extents           print only extent info: extent and device trees",
+	"-d|--device            print only device info: tree root, chunk and device trees",
+	"-r|--roots             print only short root node info",
+	"-R|--backups           same as --roots plus print backup root info",
+	"-u|--uuid              print only the uuid tree",
+	"-b|--block <block_num> print info from the specified block only",
+	"-t|--tree <tree_id>    print only the tree with the given tree_id",
 	NULL
 };