I have a cron job which frequently deletes a subvolume and I decided I wanted to silence the output. I remembered there was a -q option and thought I would just quickly glance at the documentation for it to check there wasn't some reason I had not put that in the script when I first wrote it some time ago.
That opened up an Alice-in-Wonderland rabbit hole... the documentation for the common command options in btrfs-progs is not just awful, I ended up very confused about what I was seeing... There are several issues: 1) The man pages do not describe the top-level btrfs command options, or their equivalents at subcommand level. 1a) btrfs.asciidoc makes no mention of -q, --quiet, -v, --verbose or even of the concept of top-level btrfs command options. It just explains how the subcommand structure works. 1b) btrfs-subvolume.asciidoc makes no mention of -q or --quiet. However, it *does* mention -v and --verbose but with the completely cryptic (if you are not a btrfs-progs developer) description "(deprecated) alias for global '-v' option". What global '-v' option is that then as it is not documented in btrfs.asciidoc? And what about '-q'? I haven't looked at the other subcommand pages. 2) The built-in help in btrfs and btrfs-subvolume do not describe the top level command options. 2a) 'btrfs' shows a usage message that shows the -q, --quiet, -v and --verbose options but with no information on them. 'btrfs --help' provides no further information. 'btrfs --help --full' does, but it is almost 800 lines long. 2b) 'btrfs subvolume' doesn't even mention these options in its usage message. Nor does it mention the --help option or the --help --full option as global options or as subcommand options. 'btrfs subvolume --help' provides exactly the same output. 'btrfs subvolume --help --full' does at least mention the options - if anyone can ever guess that it exists. Again, I haven't looked at the other subcommands. 3) The difference between global options and subcommand options is very unfortunate, and very confusing. I *hate* the concept of global options (as implemented) -- in my mental model the 'btrfs' command is really just a prefix to group together various btrfs-related commands and I don't even *think* about ever inserting an option between btrfs and the subcommand. In my mental model, the command is 'btrfs subvolume'. In my mind, if the command was 'btrfs' then the syntax would more naturally be 'btrfs create subvolume' (like 'Siri, call David') instead of 'btrfs subvolume create'. 3a) One particularly unfortunate effect is that 'btrfs subv del -v XXX' works but 'btrfs subv del -q XXX' does not. I consider myself very experienced with btrfs but even after drafting the first version of this email I changed my script to do this and was surprised when it didn't work. 3b) Another confusing effect is that both 'btrfs -v subv del XXX' and 'btrfs subv del -v XXX' work but 'btrfs subv -v del XXX' does not. I think fixing the man page to document the global options is important and I am happy to try to create a suitable patch. Does anyone else feel the other issues should be fixed? Graham
