btrfs-progs/Documentation/btrfs-subvolume.txt

btrfs-subvolume(8)
==================

NAME
----
btrfs-subvolume - control btrfs subvolume(s)

SYNOPSIS
--------
*btrfs subvolume* <subcommand> [<args>]

DESCRIPTION
-----------
*btrfs subvolume* is used to control the filesystem to create/delete/list/show
subvolumes and snapshots.

SUBVOLUME AND SNAPSHOT
----------------------
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.

A subvolume in btrfs can be accessed in two ways.

1. 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.

2. Separate mounted filesystem +
When `mount`(8) using 'subvol' or 'subvolid' mount option, one can access
files/directories/subvolumes inside it, but nothing in parent subvolumes.

Also every btrfs filesystem has a default subvolume as its initially top-level
subvolume, whose subvolume id is 5(FS_TREE).

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.

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.

SUBCOMMAND
-----------
*create* [-i <qgroupid>] [<dest>]<name>::
Create a subvolume <name> in <dest>.
+
If <dest> is not given, subvolume <name> will be created in the currently
directory.
+
`Options`
+
-i <qgroupid>::::
Add the newly created subvolume to a qgroup. This option can be given multiple
times.

*delete* [options] <subvolume> [<subvolume>...]::
Delete the subvolume(s) from the filesystem.
+
If <subvolume> is not a subvolume, btrfs returns an error but continues if
there are more arguments to process.
+
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 '--commit' options to wait until the operation is safely
stored on the media.
+
`Options`
+
-c|--commit-after::::
wait for transaction commit at the end of the operation
+
-C|--commit-each::::
wait for transaction commit after delet each subvolume

*list* [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>::
List the subvolumes present in the filesystem <path>.
+
For every subvolume the following information is shown by default. +
ID <ID> top level <ID> path <path> +
where path is the relative path of the subvolume to the top level subvolume.
The subvolume's ID may be used by the subvolume set-default command,
or at mount time via the subvolid= option.
If `-p` is given, then parent <ID> is added to the output between ID
and top level. The parent's ID may be used at mount time via the
`subvolrootid=` option.
+
`Options`
+
-p::::
print parent ID.
-a::::
print all the subvolumes in the filesystem and distinguish between
absolute and relative path with respect to the given <path>.
-c::::
print the ogeneration of the subvolume, aliases: ogen or origin generation.
-g::::
print the generation of the subvolume.
-o::::
print only subvolumes bellow specified <path>.
-u::::
print the UUID of the subvolume.
-q::::
print the parent uuid of subvolumes (and snapshots).
-R::::
print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
-t::::
print the result as a table.
-s::::
only snapshot subvolumes in the filesystem will be listed.
-r::::
only readonly subvolumes in the filesystem will be listed.
-G [+|-]<value>::::
list subvolumes in the filesystem that its generation is
>=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is
neither \'+' nor \'-', it means = value.
-C [+|-]<value>::::
list subvolumes in the filesystem that its ogeneration is
>=, \<= or = value. The usage is the same to '-g' option.
--sort=rootid,gen,ogen,path::::
list subvolumes in order by specified items.
you can add \'\+' or \'-' in front of each items, \'+' means ascending,
\'-' means descending. The default is ascending.
+
for --sort you can combine some items together by \',', just like
-sort=+ogen,-gen,path,rootid.

*snapshot* [-r] <source> <dest>|[<dest>/]<name>::
Create a writable/readonly snapshot of the subvolume <source> with the
name <name> in the <dest> directory.
+
If only <dest> is given, the subvolume will be named the basename of <source>.
If <source> is not a subvolume, btrfs returns an error.
If '-r' is given, the snapshot will be readonly.

*get-default* <path>::
Get the default subvolume of the filesystem <path>.
+
The output format is similar to *subvolume list* command.

*set-default* <id> <path>::
Set the subvolume of the filesystem <path> which is mounted as
default.
+
The subvolume is identified by <id>, which is returned by the *subvolume list*
command.

*find-new* <subvolume> <last_gen>::
List the recently modified files in a subvolume, after <last_gen> ID.

*show* <path>::
Show information of a given subvolume in the <path>.

EXIT STATUS
-----------
*btrfs subvolume* returns a zero exist status if it succeeds. Non zero is
returned in case of failure.

AVAILABILITY
------------
*btrfs* is part of btrfs-progs.
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
further details.

SEE ALSO
--------
`mkfs.btrfs`(8),
`btrfs-subvolume`(8),
`btrfs-quota`(8),
`btrfs-qgroup`(8),