RepoMirrors/btrfs-progs
1
0
Fork 0
mirror of https://github.com/kdave/btrfs-progs synced 2025-01-28 08:22:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
87d3875d4e
btrfs-progs/man/btrfs.8.in
Goffredo Baroncelli 87d3875d4e 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.git

(or you can browse the changes at
http://cassiopea.homelinux.net/git/btrfs-progs-unstable.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(-)

 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

Signed-off-by: Chris Mason <chris.mason@oracle.com>
2011-10-25 09:18:31 -04:00

197 lines
6.6 KiB
Groff
Raw Blame History

.TH BTRFS 8 "" "btrfs" "btrfs"
.\"
.\" Man page written by Goffredo Baroncelli <kreijack@inwind.it> (Feb 2010)
.\"
.SH NAME
btrfs \- control a btrfs filesystem
.SH SYNOPSIS
\fBbtrfs\fP \fBsubvolume snapshot\fP\fI <source> [<dest>/]<name>\fP
.PP
\fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume>\fP
.PP
\fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
.PP
\fBbtrfs\fP \fBsubvolume list\fP\fI <path>\fP
.PP
\fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\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 \fBfilesystem defrag\fP\fI [options] <file>|<dir> [<file>|<dir>...]\fP
.PP
\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 \fBdevice scan\fP\fI [<device>...]\fP
.PP
\fBbtrfs\fP \fBdevice show\fP\fI [<device>|<uuid>|<label>]\fP
.PP
\fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path> \fP
.PP
\fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...] <path> \fP]
.PP
\fBbtrfs\fP \fBhelp|\-\-help|\-h \fP\fI\fP
.PP
\fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP
.PP
.SH DESCRIPTION
.B btrfs
is used to control the filesystem and the files and directories stored. It is
the tool to create or destroy a snapshot or a subvolume for the
filesystem, to defrag a file or a directory, flush the data to the disk,
to resize the filesystem, to scan the device.
It is possible to abbreviate the commands unless the commands are ambiguous.
For example: it is possible to run
.I btrfs sub snaps
instead of
.I btrfs subvolume snapshot.
But
.I btrfs file s
is not allowed, because
.I file s
may be interpreted both as
.I filesystem show
and as
.I filesystem sync.
In this case
.I btrfs
returnsfilesystem sync
If a command is terminated by
.I --help
, the detailed help is showed. If the passed command matches more commands,
detailed help of all the matched commands is showed. For example
.I btrfs dev --help
shows the help of all
.I device*
commands.
.SH COMMANDS
.TP
\fBsubvolume snapshot\fR\fI <source> [<dest>/]<name>\fR
Create a writable snapshot of the subvolume \fI<source>\fR with the name
\fI<name>\fR in the \fI<dest>\fR directory. If \fI<source>\fR is not a
subvolume, \fBbtrfs\fR returns an error.
.TP
\fBsubvolume delete\fR\fI <subvolume>\fR
Delete the subvolume \fI<subvolume>\fR. If \fI<subvolume>\fR is not a
subvolume, \fBbtrfs\fR returns an error.
.TP
\fBsubvolume create\fR\fI [<dest>/]<name>\fR
Create a subvolume in \fI<dest>\fR (or in the current directory if
\fI<dest>\fR is omitted).
.TP
\fBsubvolume list\fR\fI <path>\fR
List the subvolumes present in the filesystem \fI<path>\fR. For every
subvolume is showed the subvolume ID (second column),
the ID of the \fItop level\fR
subvolume (fifth column), and the path (seventh column) relative to the
\fItop level\fR subvolume.
These <ID> may be used by the \fBsubvolume set-default\fR command, or at
mount time via the \fIsubvol=\fR option.
.TP
\fBsubvolume set-default\fR\fI <id> <path>\fR
Set the subvolume of the filesystem \fI<path>\fR which is mounted as
\fIdefault\fR. The subvolume is identified by \fI<id>\fR, which
is returned by the \fBsubvolume list\fR command.
.TP
\fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...]
Defragment file data and/or directory metadata. To defragment all files in a
directory you have to specify each one on its own or use your shell wildcards.
The start position and the number of bytes to deframention can be specified by \fIstart\fR and \fIlen\fR. Any extent bigger than \fIthresh\fR will be considered already defragged. Use 0 to take the kernel default, and use 1 to say eveery single extent must be rewritten. You can also turn on compression in defragment operations.
\fB-v\fP be verbose
\fB-c\fP compress file contents while defragmenting
\fB-f\fP flush filesystem after defragmenting
\fB-s start\fP defragment only from byte \fIstart\fR onward
\fB-l len\fP defragment only up to \fIlen\fR bytes
\fB-t size\fP defragment only files at least \fIsize\fR bytes big
NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data, don't
use it if you use snapshots, have de-duplicated your data or made copies with
\fBcp --reflink\fP.
\fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR
List the recently modified files in a subvolume, after \fI<last_gen>\fR ID.
.TP
\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
\fBfilesystem sync\fR\fI <path> \fR
Force a sync for the filesystem identified by \fI<path>\fR.
.TP
.\"
.\" Some wording are extracted by the resize2fs man page
.\"
\fBfilesystem resize\fR\fI [+/\-]<size>[gkm]|max <path>\fR
Resize a filesystem identified by \fI<path>\fR.
The \fI<size>\fR parameter specifies the new size of the filesystem.
If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased
by the quantity \fI<size>\fR.
If no units are specified, the unit of the \fI<size>\fR parameter defaults to
bytes. 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 occupy all available space on the
volume(s).
The \fBresize\fR command \fBdoes not\fR manipulate the size of underlying
partition. If you wish to enlarge/reduce a filesystem, you must make sure you
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.
.TP
\fBdevice 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
Add device(s) to the filesystem identified by \fI<path>\fR.
.TP
\fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
Remove device(s) from a filesystem identified by \fI<path>\fR.
.PP
.SH EXIT STATUS
\fBbtrfs\fR returns a zero exist status if it succeeds. Non zero is returned in
case of failure.
.SH AVAILABILITY
.B 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.
.SH SEE ALSO
.BR mkfs.btrfs (8)
Reference in New Issue View Git Blame Copy Permalink