Unclear `btrfs subvolume snapshot` command

Hi,

I'm using

    # btrfs version
    btrfs-progs v4.16

In btrfs-subvolume(8), I find the description of the snapshot command unclear:

    snapshot [-r] <source> <dest>|[<dest>/]<name>

I find the preference of | is unclear. From the text passage

If only <dest> is given, the subvolume will be named the basename of <source>.

I infer, that <source> must be there even “if only <dest> is given”. Also, it's unclear how the cases

snapshot [-r] <source> <dest>
snapshot [-r] <source> [<dest>/]<name>

are told apart. I assume it's based on whether <dest> is an existing directory. I came to this from the rather unfortunate error message

ERROR: invalid snapshot name '/'

when trying

    # btrfs subvolume snapshot / /foo

where /foo already existed. It took me some time to arrive at the conclusion that btrfs took this as the <source> <dest> case, and tried to make a subdir / under /foo, which is, of course, illegal.

May I suggest the following changes:

* in the manual, change to:

snapshot [-r] <source> <dest>
Create a snapshot of the subvolume <source>.

If <dest> is an existing directory, the snapshot will be named <dest>/<basename of source>. Note that this is illegal if <source> is /.

If <dest> does not exist, it will be created, and this will be the snapshot.

* in btrfs subvolume: Change the error message from

ERROR: invalid snapshot name '/'

to

ERROR: '<dest>' exists, but cannot create snapshot named '/' under it. Specify explicit snapshot name.

IMHO it would be better to replace an existing <dest> with the snapshot, instead of creating one under it. It would solve above problem, and also be more similar to how mount handles a mountpoint.

Thank you,
Stefan

http://stefan-klinger.de                                      o/X
Send plain text messages only, not exceeding 32kB.            /\/
                                                                \