NAME
----
-btrfs-subvolume - control btrfs subvolume(s)
+btrfs-subvolume - manage btrfs subvolumes
SYNOPSIS
--------
DESCRIPTION
-----------
-*btrfs subvolume* is used to control the filesystem to create/delete/list/show
-subvolumes and snapshots.
+*btrfs subvolume* is used to create/delete/list/show btrfs 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.
+A subvolume is a part of filesystem with its own independent
+file/directory hierarchy. Subvolumes can share file extents. A snapshot is
+also subvolume, but with a given initial content of the original subvolume.
-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.
+NOTE: A subvolume in btrfs is not like an LVM logical volume, which is
+block-level snapshot while btrfs subvolumes are file extent-based.
-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.
+A subvolume looks like a normal directory, with some additional operations
+described below. Subvolumes can be renamed or moved, nesting subvolumes is not
+restricted but has some implications regarding snapshotting.
-Also every btrfs filesystem has a default subvolume as its initially top-level
-subvolume, whose subvolume id is 5. (0 is also acceptable as an alias.)
+A subvolume in btrfs can be accessed in two ways:
-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.
+* like any other directory that is accessible to the user
+* like a separately mounted filesystem (options 'subvol' or 'subvolid')
-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.
+In the latter case the parent directory is not visible and accessible. This is
+similar to a bind mount, and in fact the subvolume mount does exactly that.
+
+A freshly created filesystem is also a subvolume, called 'top-level',
+internally has an id 5. This subvolume cannot be removed or replaced by another
+subvolume. This is also the subvolume that will be mounted by default, unless
+the default subvolume has been changed (see subcommand 'set-default').
+
+A snapshot is a subvolume like any other, with given initial content. By
+default, snapshots are created read-write. File modifications in a snapshot
+do not affect the files in the original subvolume.
SUBCOMMAND
-----------
-*create* [-i <qgroupid>] [<dest>]<name>::
+*create* [-i <qgroupid>] [<dest>/]<name>::
Create a subvolume <name> in <dest>.
+
-If <dest> is not given, subvolume <name> will be created in the currently
+If <dest> is not given, subvolume <name> will be created in the current
directory.
+
`Options`
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.
+removed later in the background. The command returns immediately. See `btrfs
+subvolume sync` how to wait until the subvolume gets completely removed.
++
+The deletion does not involve full transaction 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 device.
+
`Options`
+
wait for transaction commit at the end of the operation
+
-C|--commit-each::::
-wait for transaction commit after delet each subvolume
+wait for transaction commit after deleting each subvolume
*find-new* <subvolume> <last_gen>::
List the recently modified files in a subvolume, after <last_gen> ID.
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.
+>=, \<= 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.
+--sort=+ogen,-gen,path,rootid.
+
+*set-default* [<subvolume>|<id> <path>]::
+Set the default subvolume for the (mounted) filesystem.
-*set-default* <id> <path>::
-Set the subvolume of the filesystem <path> which is mounted as
-default.
+Set the default subvolume for the (mounted) filesystem at <path>. This will hide
+the top-level subvolume (ie. the one mounted with 'subvol=/' or 'subvolid=5').
+Takes action on next mount.
+
-The subvolume is identified by <id>, which is returned by the *subvolume list*
-command.
+There are two ways how to specify the subvolume, by <id> or by the <subvolume>
+path.
+The id can be obtained from *btrfs subvolume list*, *btrfs subvolume show* or
+*btrfs inspect-internal rootid*.
*show* <path>::
Show information of a given subvolume in the <path>.
*snapshot* [-r] <source> <dest>|[<dest>/]<name>::
-Create a writable/readonly snapshot of the subvolume <source> with the
+Create a 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.
++
+`Options`
++
+-r::::
+Make the new snapshot read only.
*sync* <path> [subvolid...]::
-Wait until given subvolume(s) are completely removed from the filesystem
-after deletion. If no subvolume id is given, wait until all current deletion
-requests are completed, but do not wait for subvolumes deleted meanwhile.
-The status of subvolume ids is checked periodically.
+Wait until given subvolume(s) are completely removed from the filesystem after
+deletion. If no subvolume id is given, wait until all current deletion requests
+are completed, but do not wait for subvolumes deleted in the meantime.
+
`Options`
+
SEE ALSO
--------
`mkfs.btrfs`(8),
-`btrfs-subvolume`(8),
+`mount`(8),
`btrfs-quota`(8),
`btrfs-qgroup`(8),
projects / platform / upstream / btrfs-progs.git / blobdiff