2010-03-11 21:32:50 +00:00
.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
\fB btrfs\fP \fB subvolume snapshot\fP \fI <source> [<dest>/]<name>\fP
.PP
\fB btrfs\fP \fB subvolume delete\fP \fI <subvolume>\fP
.PP
\fB btrfs\fP \fB subvolume create\fP \fI [<dest>/]<name>\fP
.PP
\fB btrfs\fP \fB subvolume list\fP \fI <path>\fP
.PP
\fB btrfs\fP \fB subvolume set-default\fP \fI <id> <path>\fP
.PP
\fB btrfs\fP \fB filesystem sync\fP \fI <path> \fP
.PP
\fB btrfs\fP \fB filesystem resize\fP \fI [+/\- ]<size>[gkm]|max <filesystem>\fP
.PP
2010-11-18 03:49:56 +00:00
\fB btrfs\fP \fB filesystem defrag\fP \fI [options] <file>|<dir> [<file>|<dir>...]\fP
.PP
2010-03-11 21:32:50 +00:00
\fB btrfs\fP \fB device scan\fP \fI [<device> [<device>..]]\fP
.PP
\fB btrfs\fP \fB device show\fP \fI <dev>|<label> [<dev>|<label>...]\fP
.PP
\fB btrfs\fP \fB device balance\fP \fI <path> \fP
.PP
\fB btrfs\fP \fB device add\fP \fI <dev> [<dev>..] <path> \fP
.PP
\fB btrfs\fP \fB device delete\fP \fI <dev> [<dev>..] <path> \fP ]
.PP
\fB btrfs\fP \fB help|\- \- help|\- h \fP \fI \fP
.PP
2011-01-23 15:31:07 +00:00
\fB btrfs\fP \fB <command> \- \- help \fP \fI \fP
.PP
2010-03-11 21:32:50 +00:00
.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 dev s
is not allowed, because
.I dev s
may be interpreted both as
.I device show
and as
.I device scan.
In this case
.I btrfs
returns an error.
If a command is terminated by
.I --help
2011-01-23 15:31:07 +00:00
, the detailed help is showed. If the passed command matches more commands,
detailed help of all the matched commands is showed. For example
2010-03-11 21:32:50 +00:00
.I btrfs dev --help
shows the help of all
.I device*
2011-01-23 15:31:07 +00:00
commands.
2010-03-11 21:32:50 +00:00
.SH COMMANDS
.TP
\fB subvolume 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, \fB btrfs\fR returns an error.
.TP
\fB subvolume delete\fR \fI <subvolume>\fR
Delete the subvolume \fI <subvolume>\fR . If \fI <subvolume>\fR is not a
subvolume, \fB btrfs\fR returns an error.
.TP
\fB subvolume 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
\fB subvolume 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 \fI top level\fR
subvolume (fifth column), and the path (seventh column) relative to the
\fI top level\fR subvolume.
These <ID> may be used by the \fB subvolume set-default\fR command, or at
mount time via the \fI subvol=\fR option.
.TP
\fB subvolume set-default\fR \fI <id> <path>\fR
Set the subvolume of the filesystem \fI <path>\fR which is mounted as
2011-01-23 15:31:07 +00:00
\fI default\fR . The subvolume is identified by \fI <id>\fR , which
2010-03-11 21:32:50 +00:00
is returned by the \fB subvolume list\fR command.
.TP
2010-11-18 03:49:56 +00:00
\fB filesystem defragment\fP -c[zlib|lzo] [-l \fI len\fR ] [-s \fI start\fR ] [-t \fI size\fR ] -[vf] <\fI file\fR >|<\fI dir\fR > [<\fI file\fR >|<\fI dir\fR >...]
2011-01-23 15:31:07 +00:00
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.
2010-11-18 03:49:56 +00:00
The start position and the number of bytes to deframention can be specified by \fI start\fR and \fI len\fR . Any extent bigger than \fI thresh\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.
2011-01-23 15:31:07 +00:00
\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 \fI start\fR onward
\fB -l len\fP defragment only up to \fI len\fR bytes
\fB -t size\fP defragment only files at least \fI size\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
\fB cp --reflink\fP .
2010-03-11 21:32:50 +00:00
.TP
\fB device scan\fR \fI [<device> [<device>..]]\fR
Scan devices for a btrfs filesystem. If no devices are passed, \fB btrfs\fR scans
all the block devices.
.TP
\fB filesystem 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
. \"
\fB filesystem 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 \fB resize\fR command \fB does 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
\fB filesystem show\fR [<uuid>|<label>]\fR
Show the btrfs filesystem with some additional info. If no UUID or label is
passed, \fB btrfs\fR show info of all the btrfs filesystem.
.TP
\fB device balance\fR \fI <path>\fR
Balance the chunks of the filesystem identified by \fI <path>\fR
across the devices.
.TP
\fB device add\fR \fI <dev> [<dev>..] <path>\fR
Add device(s) to the filesystem identified by \fI <path>\fR .
.TP
\fB device delete\fR \fI <dev> [<dev>..] <path>\fR
Remove device(s) from a filesystem identified by \fI <path>\fR .
.PP
.SH EXIT STATUS
\fB btrfs\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)