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?


Reply via email to