Btrfs devel - Feb 2010 - [PATCH 0/2] btrfs: a new tool to manage a btrfs filesystem

Hi all,

enclosed in the next two emails you can find two patches which introduce a new
program called
"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 
- 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 filesystem
                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                            BTRFS(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 directories
       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, to flush
       the dato to the disk, to resize a filesystem, to scan the devive       


OPTIONS
       snapshot|-s <source> [<dest>/]<name>
              Create a writeble snapshot of the subvolume  <source>  with 
the
              name  <name>  in the <dest> directory. If
<source> is not a sub‐
              volume, btrfs returns an error.                                 


       delete|-D <subvolume>
              Delete the subvolume <subvolume>. If <subvolume> is
not  a  sub‐
              volume, btrfs returns an error.                                 


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


       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.                              


       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‐
              ter specifies the new size of the filesystem.  If the  prefix  +
              or  - is present the size is increased or decreased by the quan‐
              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, respectively.

              If  ''max''  is  passed,  the filesystem will
occupe all available
              space on the volume(s).                                         

              The resize command does not manipulate the  size  of  underlying
              partitions.   If  you  wish  to enlarge/reduce a filesystem, you
              must make sure you can expand/reduce the size of  the  partition
              also.                                                           


       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.        


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


       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 returned
       in case of failure.


AVAILABILITY
       btrfs is part of btrfs-progs. Btrfs filesystem is currently under heavy
       development,  and not suitable for any uses other than benchmarking and
       review.  Please refer to the  btrfs  wiki  http://btrfs.wiki.kernel.org
       for further details.

SEE ALSO
       mkfs.btrfs(8)



btrfs                                                                 BTRFS(8)


-- 
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo)
<kreijackATinwind.it>
Key fingerprint = 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

On Fri, Feb 12, 2010 at 11:01 AM, Goffredo Baroncelli
<kreijack@gmail.com> wrote:
> Usage:
>        btrfs delete|-D <subvolume>
>                Delete the subvolume <subvolume>.
>        btrfs defrag|-d <file>|<dir>
[<file>|<dir>...]
>                Defragment a file 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

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--
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

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
--
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

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
--
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

On Sun, Feb 14, 2010 at 7:39 AM, Goffredo Baroncelli <kreijack@gmail.com>
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 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] ...".
>
> 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.
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 := { 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 = ip route
ip ru = ip rule
ip a = ip addr
ip l = 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 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.
>
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

-----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-----

--
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