[PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[Goffredo Baroncelli]

Hi all,

enclosed in the next two emails you can find two patches which introduc=
e a new program called=20
"btrfs". This program has the ambitious to replace the utilities of the=
 btrfs-prog package, like:
- btrfsctl
- btrfs-show
- btrfs-volume
- btrfs

The goals are:
- improve the usability of the tools=20
- add a man page which documents all the commands
- correct the btrfsctl return codes

I put a lot of attentions in order to avoid regression respect the old =
tools.
A clone of my git repository is available at

	http://cassiopea.homelinux.net/git/btrfs-command.git

Comments are welcome.

BR
Goffredo
---

Example of use:

$ ./btrfs
ERROR:  no command passed
Usage:
        btrfs snapshot|-s <source> [<dest>/]<name>
                Create a writeble snapshot of the subvolume
                <source> with the name <name> in the <dest>
                directory.
        btrfs delete|-D <subvolume>
                Delete the subvolume <subvolume>.
        btrfs create|-S [<dest>/]<name>
                Create a subvolume in <dest> (or the current directory =
if not
                passed.
        btrfs defrag|-d <file>|<dir> [<file>|<dir>...]
                Defragment a file or a directory.
        btrfs fssync|-c <path>
                Force a fs sync on the filesystem <path>
        btrfs resize|-r [+/-]<newsize>[gkm]|max <filesystem>
                Resize the file system. If 'max' is passed, the filesys=
tem
                will occupe all available space on the device.
        btrfs scan|-a [<device> [<device>..]
                Scan all device for or the passed device for a
                btrfs filesystem.
        btrfs show|-l <dev>|<label> [<dev>|<label>...]
                Show the btrfs devices
        btrfs balance|-b <path>
                Balance the chunk across the device
        btrfs add-dev|-A <dev> [<dev>..] <path>
                Add a device to a filesystem
        btrfs rem-dev|-R <dev> [<dev>..] <path>
                Remove a device to a filesystem

        btrfs help|--help|-h
                Show the help.
Btrfs v0.19-5-ge9e04d6-dirty


$ man btrfs | cat
BTRFS(8)                             btrfs                            B=
TRFS(8)



NAME
       btrfs - control a btrfs filesystem

SYNOPSIS
       btrfs  snapshot|-s  <source> [<dest>/]<name>

       btrfs  delete|-D  <subvolume>

       btrfs  create|-S  [<dest>/]<name>

       btrfs  defrag|-d  <file>|<dir> [<file>|<dir>...]

       btrfs  fssync|-c  <path>

       btrfs  resize|-r  [+/-]<size>[gkm]|max <filesystem>

       btrfs  scan|-a  [<device> [<device>..]]

       btrfs  show|-l  <dev>|<label> [<dev>|<label>...]

       btrfs  balance|-b  <path>

       btrfs  add-dev|-A  <dev> [<dev>..] <path>

       btrfs  rm-dev|-R  <dev> [<dev>..] <path> ]


       btrfs  help|--help|-h

DESCRIPTION
       btrfs  is  used to control the filesystem and the files and dire=
ctories
       stored. It is the tool to create or destroy a new  snapshot  or =
 a  new
       subvolume for the filesystem, to defrag a file or a directory, t=
o flush
       the dato to the disk, to resize a filesystem, to scan the devive=
      =20


OPTIONS
       snapshot|-s <source> [<dest>/]<name>
              Create a writeble snapshot of the subvolume  <source>  wi=
th  the
              name  <name>  in the <dest> directory. If <source> is not=
 a sub=E2=80=90
              volume, btrfs returns an error.                          =
      =20


       delete|-D <subvolume>
              Delete the subvolume <subvolume>. If <subvolume> is not  =
a  sub=E2=80=90
              volume, btrfs returns an error.                          =
      =20


       create|-S [<dest>/]<name>
              Create  a  subvolume  in  <dest> (or in the current direc=
tory if
              <dest> is not passed).                                   =
      =20


       defrag|-d <file>|<dir> [<file>|<dir>...]
              Defragment files and/or directories.


       scan|-a [<device> [<device>..]]
              Scan devices for a btrfs filesystem. If no devices  are  =
passed,
              btrfs scans all the block devices.                       =
      =20


       fssync|-c <path>
              Force a sync for the filesystem identified by <path>.



       resize|-r [+/-]<size>[gkm]|max <filesystem>
              Resize  a file system indentified by <path>.  The <size> =
parame=E2=80=90
              ter specifies the new size of the filesystem.  If the  pr=
efix  +
              or  - is present the size is increased or decreased by th=
e quan=E2=80=90
              tity <size>.  If no units are specified, the unit of the =
 <size>
              parameter  is  the  byte.  Optionally, the size parameter=
 may be
              suffixed by one of the following  the  units  designators=
:  'K',
              'M', or 'G', kilobytes, megabytes, or gigabytes, respecti=
vely. =20

              If  'max'  is  passed,  the filesystem will occupe all av=
ailable
              space on the volume(s).                                  =
      =20

              The resize command does not manipulate the  size  of  und=
erlying
              partitions.   If  you  wish  to enlarge/reduce a filesyst=
em, you
              must make sure you can expand/reduce the size of  the  pa=
rtition
              also.                                                    =
      =20


       show|-l [<dev>|<label>...]
              Show  the btrfs devices with some additional info. If no =
devices
              or labels are passed, btrfs scans all the block devices. =
      =20


       balance|-b <path>
              Balance the chunk of the filesystem identified by <path> =
 across
              the devices.                                             =
      =20


       add-dev|-A  <dev> [<dev>..] <path>
              Add device(s) to the filesystem identified by <path>.


       rm-dev|-R  <dev> [<dev>..] <path>
              Remove device(s) to the filesystem identified by <path>.

EXIT STATUS
       btrf  returns  a zero exist status if it succeeds. Non zero is r=
eturned
       in case of failure.


AVAILABILITY
       btrfs is part of btrfs-progs. Btrfs filesystem is currently unde=
r heavy
       development,  and not suitable for any uses other than benchmark=
ing and
       review.  Please refer to the  btrfs  wiki  http://btrfs.wiki.ker=
nel.org
       for further details.

SEE ALSO
       mkfs.btrfs(8)



btrfs                                                                 B=
TRFS(8)


--=20
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo) <kreijackATinw=
ind.it>
Key fingerprint =3D 4769 7E51 5293 D36C 814E  C054 BF04 F161 3DC5 0512
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" =
in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[Mike Fedyk]

On Fri, Feb 12, 2010 at 11:01 AM, Goffredo Baroncelli
<kreijack@gmail.com> wrote:
> Usage:
> =C2=A0 =C2=A0 =C2=A0 =C2=A0btrfs delete|-D <subvolume>
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0Delete the sub=
volume <subvolume>.
> =C2=A0 =C2=A0 =C2=A0 =C2=A0btrfs defrag|-d <file>|<dir> [<file>|<dir>=
=2E..]
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0Defragment a f=
ile or a directory.

I think the short options should be removed or else you'll still have
the easy misuses of btrfs -d and btrfs -D.

The best example would be the "ip" command which has commands and
-[a-z] options that do different types of things.  for instance, all
of the short options are applicable to all commands and change the
verbosity or format of the output.
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" =
in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

btrfs-progs: error in manage

[Andreas Philipp]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
 
Hi,

On the man page for the btrfs command balance is listed as a
subcommand under device instead of file system.

Kind Regards,
Andreas

diff --git a/man/btrfs.8.in b/man/btrfs.8.in
index 26ef982..bd73dc0 100644
- --- a/man/btrfs.8.in
+++ b/man/btrfs.8.in
@@ -21,12 +21,12 @@ btrfs \- control a btrfs filesystem
 .PP
 \fBbtrfs\fP \fBfilesystem resize\fP\fI [+/\-]<size>[gkm]|max
<filesystem>\fP
 .PP
+\fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP
+.PP
 \fBbtrfs\fP \fBdevice scan\fP\fI [<device> [<device>..]]\fP
 .PP
 \fBbtrfs\fP \fBdevice show\fP\fI <dev>|<label> [<dev>|<label>...]\fP
 .PP
- -\fBbtrfs\fP \fBdevice balance\fP\fI <path> \fP
- -.PP
 \fBbtrfs\fP \fBdevice add\fP\fI <dev> [<dev>..] <path> \fP
 .PP
 \fBbtrfs\fP \fBdevice delete\fP\fI <dev> [<dev>..] <path> \fP]
@@ -143,7 +143,7 @@ Show the btrfs filesystem with some additional
info. If no UUID or label is
 passed, \fBbtrfs\fR show info of all the btrfs filesystem.
 .TP

- -\fBdevice balance\fR \fI<path>\fR
+\fBfilesystem balance\fR \fI<path>\fR
 Balance the chunks of the filesystem identified by \fI<path>\fR
 across the devices.
 .TP
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
iQIcBAEBAgAGBQJMeqkcAAoJEJIcBJ3+XkgiRmcP/1RlZw+aJeVwAdhXzrYpoEY5
g7YFjH+o8RnC8sXnb35lDQq/uQ0Kk5VWkNOfhN+G9ZCMcEkA9uRP7rgUTc9OjRmL
0rTOytD/PsPCV8nhy5vJ5krO8lzQA9ChX3BOwmVXumfdl1SMSPjaw/Cp/AK3IP3K
6fCTefT7A5tOSFvTa5b4AdNj+mIn60MwF7d8on0J7OJgzhdw4ZIoQNApJ3hnldYE
kUAbfthO4jlvibEWG+wk5FEeGxkTKthZK5y/4R5PdnutWwY9f0XG5WQsJuPS7qB6
Tzz+EtxRSmTwsDJxt8RKr4k8NH+UOlZQg9VcNvdTAJaP6wkrZi39uRL7zH6bIjfh
9D+Fty2zzvMsXVORrdfL35wHKcx1xH491msn5U925ej9OU9j/tV/rYr/wSDMG3AW
GILKKzuT+9Xsgs5cYpG2ENdIeDI1kEoa/ZdYIyxSSEuo9DXb8+BsOces2kr+a1Fl
NSPIm7vQaIxcY09H9sexyEWz1IC2GnKLbMz8AuOkbNEpxbIYcuPgTdnPZrRY7xbW
K//hf3uDxkxxQ44/24hgK9o9DkVDS37nzHN7mtoGTyvDg1o4RksnFwQGZluAfShi
vfBulYqGkH50HWO25t66XholaQ1WSs4MuUb47/wNO5AocbeAezJB3WvZ+I9zLkWS
kZxFmJKvHkHwj34FxxXb
=OxAs
-----END PGP SIGNATURE-----

Re: [PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[Mike Fedyk]

On Sun, Feb 14, 2010 at 7:39 AM, Goffredo Baroncelli <kreijack@gmail.co=
m> wrote:
> Hi all,
>
> On Sunday 14 February 2010, Thomas Kupper wrote:
>> Hi Goffredo,
>>
>> Great work! It is indeed much easier to work with one tool instead w=
ith the
> many of them!
>>
>> > Usage:
>> > =C2=A0 =C2=A0 =C2=A0 =C2=A0 btrfs snapshot|-s <source> [<dest>/]<n=
ame>
>> > =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 Create a w=
riteble snapshot of the subvolume
>> > =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 <source> w=
ith the name <name> in the <dest>
>> > =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 directory.
>> > =C2=A0 =C2=A0 =C2=A0 =C2=A0 btrfs delete|-D <subvolume>
>> > =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 Delete the=
 subvolume <subvolume>.
>>
>>
>> I backup up Mike on the opinion that the short options aren't what I=
 would
> expect. Personally I'd prefer a command line syntax like git, "<comma=
nd>
> <action> [sub-action> <options>|<arguments] ...".
>
> Seriously, you (as also Michel and Mike) raised some concern about th=
e command
> line syntax. The main issues are:
> 1) possible mistaken between the '-d' (delete) command and '-D' (defr=
ag)
> command. It was suggested to remove the short form command.
> 2) some commands are not very auto-explainant
>
> Regarding the point #1, I am against about removing the short command=
 ('-
> s'...). If someone fears to mistake, he has the option to use the log=
 form
> command. But I don't see any reason to force all others peoples to us=
e the
> long form command.

The problem here is maintainability of scripts when people use the
short names.  I will refer to the "ip" command used in linux
networking.

It has these subcommands:
where  OBJECT :=3D { link | addr | addrlabel | route | rule | neigh |
ntable | tunnel |
                   maddr | mroute | monitor | xfrm }

Which are listed here:

ip link
ip addr
ip addrlabel
ip route
ip rule
ip neigh
ip ntable
ip tunnel
ip maddr
ip mroute
ip monitor
ip xfrm

You can shorten them as long as they are not ambiguous:

ip ro =3D ip route
ip ru =3D ip rule
ip a =3D ip addr
ip l =3D ip link

Those are the ones I used most personally.

There are no equivalent short options, and you don't have different
sets of people using different commands in scripts and howtos for
instance.  It builds a common base of knowledge and is easy to type
from memory.

Commands that document themselves are good IMO.

ip route replace default via 1.2.3.4

Replace or set the current default to ip address 1.2.3.4 (the tool
makes sure 1.2.3.4 is reachable by an already existing route and looks
up the layer 2 address for that ip.

It's not "ip -r default -d 1.2.3.4"

Now someone reading a howto or script with that hypothetical command
will have to find out if -r is route or -R is rule.  This is how the
btrfs commands currently look to me.

> If there is an agreement I am open to rename the command "-D/delete" =
in order
> to reduce the conflict. For examples the -D/delete command may be ren=
amed as -
> R/remove. The conflict with the -r/resize command is not a problem be=
cause the
> former requires 1 arguments, the latter two. Another renaming option =
may be -
> E/erase.
>

This just illustrates my point.  Btrfs has a rich feature set and the
short option formats are only going to create more confusion because
some of them will only be usable with a subset of operations and there
will be so many things you can do with btrfs that explicit long
options are needed to make it clear even to yourself what it does 6
months later.

Mike
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" =
in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[Goffredo Baroncelli]

Hi all,

On Sunday 14 February 2010, Thomas Kupper wrote:
> Hi Goffredo,
> 
> Great work! It is indeed much easier to work with one tool instead with the 
many of them!
> 
> > Usage:
> >         btrfs snapshot|-s <source> [<dest>/]<name>
> >                 Create a writeble snapshot of the subvolume
> >                 <source> with the name <name> in the <dest>
> >                 directory.
> >         btrfs delete|-D <subvolume>
> >                 Delete the subvolume <subvolume>.
> 
> 
> I backup up Mike on the opinion that the short options aren't what I would 
expect. Personally I'd prefer a command line syntax like git, "<command> 
<action> [sub-action> <options>|<arguments] ...".

I don't think that git may be used as examples of "good user interface". Sorry 
but I was a fan of bazaar :-)

Seriously, you (as also Michel and Mike) raised some concern about the command 
line syntax. The main issues are:
1) possible mistaken between the '-d' (delete) command and '-D' (defrag) 
command. It was suggested to remove the short form command.
2) some commands are not very auto-explainant

Regarding the point #1, I am against about removing the short command ('-
s'...). If someone fears to mistake, he has the option to use the log form 
command. But I don't see any reason to force all others peoples to use the 
long form command.
If there is an agreement I am open to rename the command "-D/delete" in order 
to reduce the conflict. For examples the -D/delete command may be renamed as -
R/remove. The conflict with the -r/resize command is not a problem because the 
former requires 1 arguments, the latter two. Another renaming option may be -
E/erase.

Regarding the point #2, I don't think that the command in btrfs are so much to 
require a multilevel command (btrfs subvolume delete, btrfs subvolume create 
...). Moreover there is no difference between removing a snapshot and a sub-
volume, both from a implementation POV and from a logical POV.
Again I am open to rename "create" in "subvolume" if it seems more auto-
explainant.

BR
G.Baroncelli

> Example:
> -> deletion of a subvolume : $ btrfs subvolume delete <subvolume>
> -> creation of a snapshot : $ btrfs snapshot create <source [<dest>/] <name>
> Or maybe no <subaction> but actions like "subvolume-delete" and a shortcut 
like "svd", and "snapshot-delete" with a shortcut like "ssd" or "ss-del"
> 
> I think that your current syntax is not that intuitive because it's not 
clear without reading the man page what - for example - '$ btrfs create' does. 
One could think that it creates a btrfs-formated device, or it creates a 
subvolume or a snapshot. The same with delete, I guess you get my idea :)
> I'm aware that the syntax you've chosen is based on how the zfs command is 
working. And that's of course a strong argument for the syntax you've chosen 
:)
> 
> The git approach would IMHO by a good one, maybe even let the user allow a 
.btrfsconfig or .btrfsrc file in which users can define alias (shortcuts). The 
benefit of a git-like syntax is the extensibility : whatever functionality 
gets added to btrfs it will never interfer/confuse with the existing ones. The 
downside (w/o alias) is rather long command lines (which I don't mind because 
I find it harder to remember all the shortcuts).
> 
> 
> Thanks for your work and have a good day,
> Thomas--
> To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 


-- 
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo) <kreijack@inwind.it>
Key fingerprint = 4769 7E51 5293 D36C 814E  C054 BF04 F161 3DC5 0512

Re: [PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[Dipl.-Ing. Michael Niederle]

When creating new commands I always prefer increased readability and
meaningfull names for subcommands and options.

If one often enters commands directly at the command prompt one could use
shell-aliases, if written in scripts long names make the scripts much easier
to understand.

It's great that we now have one single tool! Lot of thanks to Goffredo!

Greatings, Michael

[PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

[Thomas Kupper]

Hi Goffredo,

Great work! It is indeed much easier to work with one tool instead with the many of them!

> Usage:
>         btrfs snapshot|-s <source> [<dest>/]<name>
>                 Create a writeble snapshot of the subvolume
>                 <source> with the name <name> in the <dest>
>                 directory.
>         btrfs delete|-D <subvolume>
>                 Delete the subvolume <subvolume>.


I backup up Mike on the opinion that the short options aren't what I would expect. Personally I'd prefer a command line syntax like git, "<command> <action> [sub-action> <options>|<arguments] ...".

Example:
-> deletion of a subvolume : $ btrfs subvolume delete <subvolume>
-> creation of a snapshot : $ btrfs snapshot create <source [<dest>/] <name>
Or maybe no <subaction> but actions like "subvolume-delete" and a shortcut like "svd", and "snapshot-delete" with a shortcut like "ssd" or "ss-del"

I think that your current syntax is not that intuitive because it's not clear without reading the man page what - for example - '$ btrfs create' does. One could think that it creates a btrfs-formated device, or it creates a subvolume or a snapshot. The same with delete, I guess you get my idea :)
I'm aware that the syntax you've chosen is based on how the zfs command is working. And that's of course a strong argument for the syntax you've chosen :)

The git approach would IMHO by a good one, maybe even let the user allow a .btrfsconfig or .btrfsrc file in which users can define alias (shortcuts). The benefit of a git-like syntax is the extensibility : whatever functionality gets added to btrfs it will never interfer/confuse with the existing ones. The downside (w/o alias) is rather long command lines (which I don't mind because I find it harder to remember all the shortcuts).


Thanks for your work and have a good day,
Thomas