Goffredo Baroncelli
2010-Oct-10 19:04 UTC
[PATCH][btrfs progs] Update/clean up btrfs help and man page V2
Hi all,
enclose you can find a patch which improves the help of the btrfs commands,
updates the INSTALL file and the btrfs (command) man page.
Regarding the help of the btrfs command:
- moved the "subvolume set-default" command in the
"subvolume" commands group
- removed a wrong new line
- small tweak on the basis of Andreas suggestion
Regarding the btrfs command man page:
- renaming the command "device balance" in "filesystem
balance" (thanks to
Andreas Phillipp to highlight that)
- adding the entry "subvolume find-new"
- document the switches of the command "filesystem defrag"
- document the <devid> facility of the command "filesystem
resize"
- small tweak on the basis of Andreas suggestion
Regarding the INSTALL file, which was very old, I removed the reference of the
old btrfsctl utility and changed the examples using the btrfs command.
I removed the old (and now wrong) statement about the inability to delete a
subvolume/snapshot
Chris, you can pull the patch from the branch "help_cleanup" of the
following
repository.
http://cassiopea.homelinux.net/git/btrfs-progs-unstable-all.git
(or you can browse the changes at
http://cassiopea.homelinux.net/git/btrfs-progs-unstable-all.git/?p=btrfs-
progs-unstable-all.git;a=summary)
The patch is very simple: only updates the man page, the INSTALL file and
moves/updates some lines in the help of btrfs command. Comments are welcome.
Regards
G.Baroncelli
INSTALL | 29 ++++++++++++++++++++---------
btrfs.c | 24 ++++++++++++------------
man/btrfs.8.in | 45 +++++++++++++++++++++++++--------------------
3 files changed, 57 insertions(+), 41 deletions(-)
diff --git a/INSTALL b/INSTALL
index 16b45a5..3840148 100644
--- a/INSTALL
+++ b/INSTALL
@@ -22,23 +22,32 @@ in the e2fsprogs sources, and is usually available as
libuuid or
e2fsprogs-devel from various distros.
Building the utilities is just make ; make install. The programs go
-into /usr/local/bin. The commands available are:
+into /usr/local/bin. The mains commands available are:
mkfs.btrfs: create a filesystem
-btrfsctl: control program to create snapshots and subvolumes:
-
+btrfs: control program to create snapshots and subvolumes:
+ # mount a btrfs filesystem
mount /dev/sda2 /mnt
- btrfsctl -s new_subvol_name /mnt
- btrfsctl -s snapshot_of_default /mnt/default
- btrfsctl -s snapshot_of_new_subvol /mnt/new_subvol_name
- btrfsctl -s snapshot_of_a_snapshot /mnt/snapshot_of_new_subvol
+
+ # create a subvolume
+ btrfs subvolume create /mnt/new_subvol_name
+
+ # snapshot of a subvolume
+ btrfs subvolume snapshot /mnt/default /mnt/snapshot_of_default
+ btrfs subvolume snapshot /mnt/snapshot_of_default \
+ /mnt/snapshot_of_a_snapshot
+
+ # list of the subvolumes
ls /mnt
default snapshot_of_a_snapshot snapshot_of_new_subvol
new_subvol_name snapshot_of_default
- Snapshots and subvolumes cannot be deleted right now, but you can
- rm -rf all the files and directories inside them.
+ # removal of a subvolume or a snapshot
+ btrfs subvolume delete /mn/snapshot_of_a_snapshot
+
+ # look a the btrfs man page for further information
+ man btrfs
btrfsck: do a limited check of the FS extent trees.</li>
@@ -46,3 +55,5 @@ debug-tree: print all of the FS metadata in text form.
Example:
debug-tree /dev/sda2 >& big_output_file
+
+
diff --git a/btrfs.c b/btrfs.c
index 46314cf..8b3716a 100644
--- a/btrfs.c
+++ b/btrfs.c
@@ -61,6 +61,11 @@ static struct Command commands[] = {
{ do_subvol_list, 1, "subvolume list", "<path>\n"
"List the snapshot/subvolume of a filesystem."
},
+ { do_set_default_subvol, 2,
+ "subvolume set-default", "<id> <path>\n"
+ "Set the subvolume of the filesystem <path> which will be
mounted\n"
+ "as default."
+ },
{ do_find_newer, 2, "subvolume find-new", "<path>
<last_gen>\n"
"List the recently modified files in a filesystem."
},
@@ -68,11 +73,6 @@ static struct Command commands[] = {
"filesystem defragment", "[-vcf] [-s start] [-l len] [-t
size]
<file>|<dir> [<file>|<dir>...]\n"
"Defragment a file or a directory."
},
- { do_set_default_subvol, 2,
- "subvolume set-default", "<id> <path>\n"
- "Set the subvolume of the filesystem <path> which will be
mounted\n"
- "as default."
- },
{ do_fssync, 1,
"filesystem sync", "<path>\n"
"Force a sync on the filesystem <path>."
@@ -83,29 +83,29 @@ static struct Command commands[] = {
"will occupe all available space on the device."
},
{ do_show_filesystem, 999,
- "filesystem show", "[<uuid>|<label>]\n"
- "Show the info of a btrfs filesystem. If no <uuid> or
<label>\n"
+ "filesystem show",
"[<device>|<uuid>|<label>]\n"
+ "Show the info of a btrfs filesystem. If no argument\n"
"is passed, info of all the btrfs filesystem are shown."
},
{ do_df_filesystem, 1,
"filesystem df", "<path>\n"
- "Show space usage information for a mount point\n."
+ "Show space usage information for a mount point."
},
{ do_balance, 1,
"filesystem balance", "<path>\n"
"Balance the chunks across the device."
},
- { do_scan,
- 999, "device scan", "[<device>
[<device>..]\n"
+ { do_scan, 999,
+ "device scan", "[<device>...]\n"
"Scan all device for or the passed device for a btrfs\n"
"filesystem."
},
{ do_add_volume, -2,
- "device add", "<dev> [<dev>..]
<path>\n"
+ "device add", "<device> [<device>...]
<path>\n"
"Add a device to a filesystem."
},
{ do_remove_volume, -2,
- "device delete", "<dev> [<dev>..]
<path>\n"
+ "device delete", "<device> [<device>...]
<path>\n"
"Remove a device from a filesystem."
},
/* coming soon
diff --git a/man/btrfs.8.in b/man/btrfs.8.in
index 26ef982..5ec1a8d 100644
--- a/man/btrfs.8.in
+++ b/man/btrfs.8.in
@@ -15,21 +15,23 @@ btrfs \- control a btrfs filesystem
.PP
\fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP
.PP
-\fBbtrfs\fP \fBfilesystem defrag\fP\fI <file>|<dir>
[<file>|<dir>...]\fP
+\fBbtrfs\fP \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP
+.PP
+\fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP
+.PP
+\fBbtrfs\fP \fBfilesystem defragment\fP\fI <file>|<dir>
[<file>|<dir>...]\fP
.PP
\fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
.PP
\fBbtrfs\fP \fBfilesystem resize\fP\fI [+/\-]<size>[gkm]|max
<filesystem>\fP
.PP
-\fBbtrfs\fP \fBdevice scan\fP\fI [<device> [<device>..]]\fP
-.PP
-\fBbtrfs\fP \fBdevice show\fP\fI <dev>|<label>
[<dev>|<label>...]\fP
+\fBbtrfs\fP \fBdevice scan\fP\fI [<device>...]\fP
.PP
-\fBbtrfs\fP \fBdevice balance\fP\fI <path> \fP
+\fBbtrfs\fP \fBdevice show\fP\fI [<device>|<uuid>|<label>]\fP
.PP
-\fBbtrfs\fP \fBdevice add\fP\fI <dev> [<dev>..] <path> \fP
+\fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path>
\fP
.PP
-\fBbtrfs\fP \fBdevice delete\fP\fI <dev> [<dev>..] <path>
\fP]
+\fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...]
<path> \fP]
.PP
\fBbtrfs\fP \fBhelp|\-\-help|\-h \fP\fI\fP
@@ -47,17 +49,16 @@ For example: it is possible to run
instead of
.I btrfs subvolume snapshot.
But
-.I btrfs dev s
+.I btrfs file s
is not allowed, because
-.I dev s
+.I file s
may be interpreted both as
-.I device show
+.I filesystem show
and as
-.I device scan.
+.I filesystem sync.
In this case
.I btrfs
-returns an error.
-
+returnsfilesystem sync
If a command is terminated by
.I --help
, the relevant help is showed. If the passed command matches more commands,
@@ -102,11 +103,15 @@ Set the subvolume of the filesystem \fI<path>\fR
which
is mounted as
is returned by the \fBsubvolume list\fR command.
.TP
+\fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
+List the recently modified files in a subvolume, after \fI<last_gen>\fR
ID.
+.TP
+
\fBfilesystem defragment\fP\fI <file>|<dir>
[<file>|<dir>...]\fR
Defragment files and/or directories.
.TP
-\fBdevice scan\fR \fI[<device> [<device>..]]\fR
+\fBdevice scan\fR \fI[<device>...]\fR
Scan devices for a btrfs filesystem. If no devices are passed, \fBbtrfs\fR
scans
all the block devices.
.TP
@@ -138,21 +143,21 @@ can expand the partition before enlarging the filesystem
and shrink the
partition after reducing the size of the filesystem.
.TP
-\fBfilesystem show\fR [<uuid>|<label>]\fR
-Show the btrfs filesystem with some additional info. If no UUID or label is
-passed, \fBbtrfs\fR show info of all the btrfs filesystem.
+\fBfilesystem show\fR [<device>|<uuid>|<label>]\fR
+Show the btrfs filesystem with some additional info. If no argument is
+passed, \fBbtrfs\fR shows info of all the btrfs filesystems.
.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
-\fBdevice add\fR\fI <dev> [<dev>..] <path>\fR
+\fBdevice add\fR\fI <device> [<device>...] <path>\fR
Add device(s) to the filesystem identified by \fI<path>\fR.
.TP
-\fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
+\fBdevice delete\fR\fI <device> [<device>...] <path>\fR
Remove device(s) from a filesystem identified by \fI<path>\fR.
.PP
--
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo)
<kreijack@inwind.it>
Key fingerprint = 4769 7E51 5293 D36C 814E C054 BF04 F161 3DC5 0512