'\" t
.\"     Title: btrfs-subvolume
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 11/22/2014
.\"    Manual: Btrfs Manual
.\"    Source: Btrfs v3.17
.\"  Language: English
.\"
.TH "BTRFS\-SUBVOLUME" "8" "11/22/2014" "Btrfs v3\&.17" "Btrfs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
btrfs-subvolume \- control btrfs subvolume(s)
.SH "SYNOPSIS"
.sp
\fBbtrfs subvolume\fR \fI<subcommand>\fR [\fI<args>\fR]
.SH "DESCRIPTION"
.sp
\fBbtrfs subvolume\fR is used to control the filesystem to create/delete/list/show subvolumes and snapshots\&.
.SH "SUBVOLUME AND SNAPSHOT"
.sp
A subvolume in btrfs is not like an LVM logical volume, which is quite independent from each other, a btrfs subvolume has its hierarchy and relations between other subvolumes\&.
.sp
A subvolume in btrfs can be accessed in two ways\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
From the parent subvolume

When accessing from the parent subvolume, the subvolume can be used just like a directory\&. It can have child subvolumes and its own files/directories\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Separate mounted filesystem

When
\fBmount\fR(8) using
\fIsubvol\fR
or
\fIsubvolid\fR
mount option, one can access files/directories/subvolumes inside it, but nothing in parent subvolumes\&.
.RE
.sp
Also every btrfs filesystem has a default subvolume as its initially top\-level subvolume, whose subvolume id is 5(FS_TREE)\&.
.sp
A btrfs snapshot is much like a subvolume, but shares its data(and metadata) with other subvolume/snapshot\&. Due to the capabilities of COW, modifications inside a snapshot will only show in a snapshot but not in its source subvolume\&.
.sp
Although in btrfs, subvolumes/snapshots are treated as directories, only subvolume/snapshot can be the source of a snapshot, snapshot can not be made from normal directories\&.
.SH "SUBCOMMAND"
.PP
\fBcreate\fR [\-i \fI<qgroupid>\fR] \fI<name>\fR
.RS 4
Create a subvolume
\fI<name>\fR
in
\fI<dest>\fR\&.
.sp
If
\fI<dest>\fR
is not given, subvolume
\fI<name>\fR
will be created in the currently directory\&.
.sp
\fBOptions\fR
.PP
\-i \fI<qgroupid>\fR
.RS 4
Add the newly created subvolume to a qgroup\&. This option can be given multiple times\&.
.RE
.RE
.PP
\fBdelete\fR [options] \fI<subvolume>\fR [\fI<subvolume>\fR\&...]
.RS 4
Delete the subvolume(s) from the filesystem\&.
.sp
If
\fI<subvolume>\fR
is not a subvolume, btrfs returns an error but continues if there are more arguments to process\&.
.sp
The corresponding directory is removed instantly but the data blocks are removed later\&. The deletion does not involve full commit by default due to performance reasons (as a consequence, the subvolume may appear again after a crash)\&. Use one of the
\fI\-\-commit\fR
options to wait until the operation is safely stored on the media\&.
.sp
\fBOptions\fR
.PP
\-c|\-\-commit\-after
.RS 4
wait for transaction commit at the end of the operation
.RE
.PP
\-C|\-\-commit\-each
.RS 4
wait for transaction commit after delet each subvolume
.RE
.RE
.PP
\fBlist\fR [options] [\-G \fI<value>\fR] [\-C \fI<value>\fR] [\-\-sort=rootid,gen,ogen,path] \fI<path>\fR
.RS 4
List the subvolumes present in the filesystem
\fI<path>\fR\&.
.sp
For every subvolume the following information is shown by default\&.

ID
\fI<ID>\fR
top level
\fI<ID>\fR
path
\fI<path>\fR
where path is the relative path of the subvolume to the top level subvolume\&. The subvolume\(cqs ID may be used by the subvolume set\-default command, or at mount time via the subvolid= option\&. If
\fB\-p\fR
is given, then parent
\fI<ID>\fR
is added to the output between ID and top level\&. The parent\(cqs ID may be used at mount time via the
\fBsubvolrootid=\fR
option\&.
.sp
\fBOptions\fR
.PP
\-p
.RS 4
print parent ID\&.
.RE
.PP
\-a
.RS 4
print all the subvolumes in the filesystem and distinguish between absolute and relative path with respect to the given
\fI<path>\fR\&.
.RE
.PP
\-c
.RS 4
print the ogeneration of the subvolume, aliases: ogen or origin generation\&.
.RE
.PP
\-g
.RS 4
print the generation of the subvolume\&.
.RE
.PP
\-o
.RS 4
print only subvolumes below specified
\fI<path>\fR\&.
.RE
.PP
\-u
.RS 4
print the UUID of the subvolume\&.
.RE
.PP
\-q
.RS 4
print the parent uuid of subvolumes (and snapshots)\&.
.RE
.PP
\-R
.RS 4
print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
.RE
.PP
\-t
.RS 4
print the result as a table\&.
.RE
.PP
\-s
.RS 4
only snapshot subvolumes in the filesystem will be listed\&.
.RE
.PP
\-r
.RS 4
only readonly subvolumes in the filesystem will be listed\&.
.RE
.PP
\-G \fI<value>\fR
.RS 4
list subvolumes in the filesystem that its generation is >=, \*(Aq\(la or = value\&. \*(Aq+\*(Aq means >\*(Aq= value, \*(Aq\-\*(Aq means <= value, If there is neither \*(Aq+\*(Aq nor \*(Aq\-\*(Aq, it means = value\&.
.RE
.PP
\-C \fI<value>\fR
.RS 4
list subvolumes in the filesystem that its ogeneration is >=, <= or = value\&. The usage is the same to
\fI\-g\fR
option\&.
.RE
.PP
\-\-sort=rootid,gen,ogen,path
.RS 4
list subvolumes in order by specified items\&. you can add \*(Aq+\*(Aq or \*(Aq\-\*(Aq in front of each items, \*(Aq+\*(Aq means ascending, \*(Aq\-\*(Aq means descending\&. The default is ascending\&.
.sp
for \-\-sort you can combine some items together by \*(Aq,\*(Aq, just like \-sort=+ogen,\-gen,path,rootid\&.
.RE
.RE
.PP
\fBsnapshot\fR [\-r] \fI<source>\fR \fI<dest>\fR|\fI<name>\fR
.RS 4
Create a writable/readonly snapshot of the subvolume
\fI<source>\fR
with the name
\fI<name>\fR
in the
\fI<dest>\fR
directory\&.
.sp
If only
\fI<dest>\fR
is given, the subvolume will be named the basename of
\fI<source>\fR\&. If
\fI<source>\fR
is not a subvolume, btrfs returns an error\&. If
\fI\-r\fR
is given, the snapshot will be readonly\&.
.RE
.PP
\fBget\-default\fR \fI<path>\fR
.RS 4
Get the default subvolume of the filesystem
\fI<path>\fR\&.
.sp
The output format is similar to
\fBsubvolume list\fR
command\&.
.RE
.PP
\fBset\-default\fR \fI<id>\fR \fI<path>\fR
.RS 4
Set the subvolume of the filesystem
\fI<path>\fR
which is mounted as default\&.
.sp
The subvolume is identified by
\fI<id>\fR, which is returned by the
\fBsubvolume list\fR
command\&.
.RE
.PP
\fBfind\-new\fR \fI<subvolume>\fR \fI<last_gen>\fR
.RS 4
List the recently modified files in a subvolume, after
\fI<last_gen>\fR
ID\&.
.RE
.PP
\fBshow\fR \fI<path>\fR
.RS 4
Show information of a given subvolume in the
\fI<path>\fR\&.
.RE
.PP
\fBsync\fR \fI<path>\fR [subvolid\&...]
.RS 4
Wait until given subvolume(s) are completely removed from the filesystem after deletion\&. If no subvolume id is given, wait until all ongoing deletion requests are complete\&. This may take long if new deleted subvolumes appear during the sleep interval\&.
.sp
\fBOptions\fR
.PP
\-s \fI<N>\fR
.RS 4
sleep N seconds between checks (default: 1)
.RE
.RE
.SH "EXIT STATUS"
.sp
\fBbtrfs subvolume\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&.
.SH "AVAILABILITY"
.sp
\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
.SH "SEE ALSO"
.sp
\fBmkfs\&.btrfs\fR(8), \fBbtrfs\-subvolume\fR(8), \fBbtrfs\-quota\fR(8), \fBbtrfs\-qgroup\fR(8),