btrfs-progs: -q/--quiet not accepted for "btrfs subvolume" subcommands

btrfs-progs: -q/--quiet not accepted for "btrfs subvolume" subcommands

[Roman Mamedov]

Hello,

# btrfs --version
btrfs-progs v6.6.3

# btrfs sub create --help
usage: btrfs subvolume create [options] [<dest>/]<name> [[<dest2>/]<name2> ...]

    Create subvolume(s)

    Create subvolume(s) at specified destination.  If <dest> is not given
    subvolume <name> will be created in the current directory. Options apply
    to all created subvolumes.

    -i <qgroupid>             add the newly created subvolume(s) to a qgroup. This option can be given multiple times.
    -p|--parents              create any missing parent directories for each argument (like mkdir -p) 
    
    Global options:
    -q|--quiet                print only errors 

# btrfs sub create -q test
btrfs subvolume create: invalid option 'q'
Try 'btrfs subvolume create --help' for more information

# btrfs sub create --quiet test
btrfs subvolume create: unrecognized option '--quiet'
Try 'btrfs subvolume create --help' for more information

Same for "snapshot". Maybe also some or all others, did not check further.

This is the case also on btrfs-progs versions 5.10 and 6.2.

-- 
With respect,
Roman

Re: btrfs-progs: -q/--quiet not accepted for "btrfs subvolume" subcommands

[David Sterba]

On Tue, Dec 17, 2024 at 07:56:49PM +0500, Roman Mamedov wrote:
> Hello,
> 
> # btrfs --version
> btrfs-progs v6.6.3
> 
> # btrfs sub create --help
> usage: btrfs subvolume create [options] [<dest>/]<name> [[<dest2>/]<name2> ...]
> 
>     Create subvolume(s)
> 
>     Create subvolume(s) at specified destination.  If <dest> is not given
>     subvolume <name> will be created in the current directory. Options apply
>     to all created subvolumes.
> 
>     -i <qgroupid>             add the newly created subvolume(s) to a qgroup. This option can be given multiple times.
>     -p|--parents              create any missing parent directories for each argument (like mkdir -p) 
>     
>     Global options:
>     -q|--quiet                print only errors 
> 
> # btrfs sub create -q test
> btrfs subvolume create: invalid option 'q'
> Try 'btrfs subvolume create --help' for more information
> 
> # btrfs sub create --quiet test
> btrfs subvolume create: unrecognized option '--quiet'
> Try 'btrfs subvolume create --help' for more information
> 
> Same for "snapshot". Maybe also some or all others, did not check further.
> 
> This is the case also on btrfs-progs versions 5.10 and 6.2.

The global options -q/-v and others are supposed to be right after the
'btrfs' term, like

  $ btrfs -q subvolume create test

This is mentioned at the top of 'btrfs --help' but maybe it needs to be
made more visible or repeated at the end of the help too.

Re: btrfs-progs: -q/--quiet not accepted for "btrfs subvolume" subcommands

[Roman Mamedov]

On Wed, 19 Mar 2025 23:12:56 +0100
David Sterba <dsterba@suse.cz> wrote:

> On Tue, Dec 17, 2024 at 07:56:49PM +0500, Roman Mamedov wrote:
> > Hello,
> > 
> > # btrfs --version
> > btrfs-progs v6.6.3
> > 
> > # btrfs sub create --help
> > usage: btrfs subvolume create [options] [<dest>/]<name> [[<dest2>/]<name2> ...]

^ This line appears to instruct that there's one place to put all the options;
so if you're looking into a documentation fix, I would suggest modifying that.
Like,

> > usage: btrfs [global-options] subvolume create [local-options] [<dest>/]<name> [[<dest2>/]<name2> ...]

But this looks messy. So IMO the ideal would be to just not require the
separation and accept global options also after the subcommand name.

> >     Create subvolume(s)
> > 
> >     Create subvolume(s) at specified destination.  If <dest> is not given
> >     subvolume <name> will be created in the current directory. Options apply
> >     to all created subvolumes.
> > 
> >     -i <qgroupid>             add the newly created subvolume(s) to a qgroup. This option can be given multiple times.
> >     -p|--parents              create any missing parent directories for each argument (like mkdir -p) 
> >     
> >     Global options:
> >     -q|--quiet                print only errors 
> > 
> > # btrfs sub create -q test
> > btrfs subvolume create: invalid option 'q'
> > Try 'btrfs subvolume create --help' for more information
> > 
> > # btrfs sub create --quiet test
> > btrfs subvolume create: unrecognized option '--quiet'
> > Try 'btrfs subvolume create --help' for more information
> > 
> > Same for "snapshot". Maybe also some or all others, did not check further.
> > 
> > This is the case also on btrfs-progs versions 5.10 and 6.2.
> 
> The global options -q/-v and others are supposed to be right after the
> 'btrfs' term, like
> 
>   $ btrfs -q subvolume create test
> 
> This is mentioned at the top of 'btrfs --help' but maybe it needs to be
> made more visible or repeated at the end of the help too.
> 


-- 
With respect,
Roman

Re: btrfs-progs: -q/--quiet not accepted for "btrfs subvolume" subcommands

[David Sterba]

On Thu, Mar 20, 2025 at 03:46:13AM +0500, Roman Mamedov wrote:
> On Wed, 19 Mar 2025 23:12:56 +0100
> David Sterba <dsterba@suse.cz> wrote:
> 
> > On Tue, Dec 17, 2024 at 07:56:49PM +0500, Roman Mamedov wrote:
> > > Hello,
> > > 
> > > # btrfs --version
> > > btrfs-progs v6.6.3
> > > 
> > > # btrfs sub create --help
> > > usage: btrfs subvolume create [options] [<dest>/]<name> [[<dest2>/]<name2> ...]
> 
> ^ This line appears to instruct that there's one place to put all the options;
> so if you're looking into a documentation fix, I would suggest modifying that.

That is certainly one option to improve it. The pattern I'm following is
from git that thas the multi level subcommand structure, global and
command-specific options. If you check 'man git' there are options that
are affect e.g. pager or editor, but none of these options is mentioned
in 'git-log' manual page and the help text also omits the global
options. "git log [<options>] [<revision-range>] [[--] <path>...]"

> Like,
> 
> > > usage: btrfs [global-options] subvolume create [local-options] [<dest>/]<name> [[<dest2>/]<name2> ...]
> 
> But this looks messy. So IMO the ideal would be to just not require the
> separation and accept global options also after the subcommand name.

I see the rationale here and the goal of the command line interface is
to provide convenices, while currently forcing the global options to be
only after the 'btrfs' term is still a bit uncommon.

As long as the option names don't clash with the command options it
would be possible to extend the semantics of the current "global" to
global in the sense of "anywhere the options can appear".

The original motivation was to unify the options to one place but based
on the feedback and my own experience I think the current split is not a
good pattern. Implementing the new semantics will need a review of all
the commands if there are potential clashes but overall I agree it would
be a usability improvement in the end.