Unclear `btrfs subvolume snapshot` command

[Stefan Klinger <linux-btrfs@stefan-klinger.de>]

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.            /\/
                                                                \