.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 label\fP\fI <dev> [newlabel]\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

\fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP
Show or update the label of a filesystem. \fI<dev>\fR is used to identify the
filesystem. 
If a \fInewlabel\fR optional argument is passed, the label is changed. The
following costraints exist for a label:
.IP
- the maximum allowable lenght shall be less or equal than 256 chars
.IP
- the label shall not  contain the '/' or '\\' characters.

NOTE: Currently there are the following limitations:
.IP
- the filesystem has to be unmounted
.IP
- the filesystem should not have more than one device.
.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)