path: root/Documentation/btrfs-subvolume.asciidoc
diff options
authorDavid Sterba <>2015-04-14 17:37:23 +0200
committerDavid Sterba <>2015-04-14 17:41:27 +0200
commit7ffccaf0c3b4d4979d7d74bab3d79d9541a6e665 (patch)
tree1d64b306503787588d0d79ab467b95f8c6a83c99 /Documentation/btrfs-subvolume.asciidoc
parent32ca2fa502c0a00a7dc40adbdae2e7b7765e6d63 (diff)
btrfs-progs: Documentaion: rename to .asciidoc
A few minor benefits: * editors set highliting according to the extensions * web access to the git repository (github) renders the .asciidoc files: * we can link to them from the wiki * the files are editable via browser and such editations can be submitted for merge easily Signed-off-by: David Sterba <>
Diffstat (limited to 'Documentation/btrfs-subvolume.asciidoc')
1 files changed, 183 insertions, 0 deletions
diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc
new file mode 100644
index 00000000..3dd5289b
--- /dev/null
+++ b/Documentation/btrfs-subvolume.asciidoc
@@ -0,0 +1,183 @@
+btrfs-subvolume - control btrfs subvolume(s)
+*btrfs subvolume* <subcommand> [<args>]
+*btrfs subvolume* is used to control the filesystem to create/delete/list/show
+subvolumes and snapshots.
+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. (0 is also acceptable as an alias.)
+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.
+*create* [-i <qgroupid>] [<dest>]<name>::
+Create a subvolume <name> in <dest>.
+If <dest> is not given, subvolume <name> will be created in the currently
+-i <qgroupid>::::
+Add the newly created subvolume to a qgroup. This option can be given multiple
+*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.
+wait for transaction commit at the end of the operation
+wait for transaction commit after delet each subvolume
+*find-new* <subvolume> <last_gen>::
+List the recently modified files in a subvolume, after <last_gen> ID.
+*get-default* <path>::
+Get the default subvolume of the filesystem <path>.
+The output format is similar to *subvolume list* command.
+*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.
+print parent ID.
+print all the subvolumes in the filesystem and distinguish between
+absolute and relative path with respect to the given <path>.
+print the ogeneration of the subvolume, aliases: ogen or origin generation.
+print the generation of the subvolume.
+print only subvolumes below specified <path>.
+print the UUID of the subvolume.
+print the parent uuid of subvolumes (and snapshots).
+print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
+print the result as a table.
+only snapshot subvolumes in the filesystem will be listed.
+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.
+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
+*set-default* <id> <path>::
+Set the subvolume of the filesystem <path> which is mounted as
+The subvolume is identified by <id>, which is returned by the *subvolume list*
+*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
+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.
+*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 ongoing deletion
+requests are complete. This may take long if new deleted subvolumes appear
+during the sleep interval.
+-s <N>::::
+sleep N seconds between checks (default: 1)
+*btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value is
+returned in case of failure.
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki for
+further details.