'\" t
.\" Title: btrfs-subvolume
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1
.\" 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\fR [\fI\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\fR] \fI\fR
.RS 4
Create a subvolume
\fI\fR
in
\fI\fR\&.
.sp
If
\fI\fR
is not given, subvolume
\fI\fR
will be created in the currently directory\&.
.sp
\fBOptions\fR
.PP
\-i \fI\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\fR [\fI\fR\&...]
.RS 4
Delete the subvolume(s) from the filesystem\&.
.sp
If
\fI\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\fR] [\-C \fI\fR] [\-\-sort=rootid,gen,ogen,path] \fI\fR
.RS 4
List the subvolumes present in the filesystem
\fI\fR\&.
.sp
For every subvolume the following information is shown by default\&.
ID
\fI\fR
top level
\fI\fR
path
\fI\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\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\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\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\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\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