btrfs subvolume <subcommand> [<args>]
btrfs subvolume is used to create/delete/list/show btrfs subvolumes and snapshots.
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.
A subvolume in btrfs is not like an LVM logical volume, which is block-level snapshot while btrfs subvolumes are file extent-based.
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.
A subvolume in btrfs can be accessed in two ways:
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.
create [-i <qgroupid>] [<dest>/]<name>
If <dest> is not given, subvolume <name> will be created in the current directory.
Options
-i <qgroupid>
delete [options] <[<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid> <path>>
If <subvolume> is not a subvolume, btrfs returns an error but continues if there are more arguments to process.
If --subvolid is used, <path> must point to a btrfs filesystem. See btrfs subvolume list or btrfs inspect-internal rootid how to get the subvolume id.
The corresponding directory is removed instantly but the data blocks are 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.
The default subvolume (see btrfs subvolume set-default) cannot be deleted and returns error (EPERM) and this is logged to the system log. A subvolume that's currently involved in send (see btrfs send) also cannot be deleted until the send is finished. This is also logged in the system log.
Options
-c|--commit-after
-C|--commit-each
-i|--subvolid <subvolid>
-v|--verbose
find-new <subvolume> <last_gen>
get-default <path>
The output format is similar to subvolume list command.
list [options] [-G [+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>
For every subvolume the following information is shown by default:
ID <ID> gen <generation> top level <ID> path <path>
where ID is subvolume's id, gen is an internal counter which is updated every transaction, top level is the same as parent subvolume's id, and 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.
Options
Path filtering
-o
-a
Field selection
-p
-c
-g
-u
-q
-R
Type filtering
-s
-r
-d
Other
-t
Sorting
-G [+|-]<value>
-C [+|-]<value>
--sort=rootid,gen,ogen,path
for --sort you can combine some items together by ',', just like --sort=+ogen,-gen,path,rootid.
set-default [<subvolume>|<id> <path>]
Set the default subvolume for the (mounted) filesystem at <path>. This will hide the top-level subvolume (i.e. the one mounted with subvol=/ or subvolid=5). Takes action on next mount.
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 [options] <path>
/mnt/btrfs/subvolume
Name: subvolume
UUID: 5e076a14-4e42-254d-ac8e-55bebea982d1
Parent UUID: -
Received UUID: -
Creation time: 2018-01-01 12:34:56 +0000
Subvolume ID: 79
Generation: 2844
Gen at creation: 2844
Parent ID: 5
Top level ID: 5
Flags: -
Snapshot(s):
Options
-r|--rootid <ID>
-u|--uuid UUID
snapshot [-r] [-i <qgroupid>] <source> <dest>|[<dest>/]<name>
If only <dest> is given, the subvolume will be named the basename of <source>. If <source> is not a subvolume, btrfs returns an error.
Options
-r
-i <qgroupid>
sync <path> [subvolid...]
Options
-s <N>
Example 1. Deleting a subvolume
If we want to delete a subvolume called foo from a btrfs volume mounted at /mnt/bar we could run the following:
btrfs subvolume delete /mnt/bar/foo
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 m[blue]http://btrfs.wiki.kernel.orgm[] for further details.
mkfs.btrfs(8), mount(8), btrfs-quota(8), btrfs-qgroup(8),