btrfs-subvolume(8) ================== NAME ---- btrfs-subvolume - control btrfs subvolume(s) SYNOPSIS -------- *btrfs subvolume* [] 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 ] []:: Create a subvolume in . + If is not given, subvolume will be created in the currently directory. + `Options` + -i :::: Add the newly created subvolume to a qgroup. This option can be given multiple times. *delete* [options] [...]:: Delete the subvolume(s) from the filesystem. + If 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 [\+|-]] [-C [+|-]] [--sort=rootid,gen,ogen,path] :: List the subvolumes present in the filesystem . + For every subvolume the following information is shown by default. + ID top level 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 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 . -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 . -u:::: print the UUID of the subvolume. -q:::: print the parent uuid of subvolumes (and snapshots). -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 [+|-]:::: list subvolumes in the filesystem that its generation is >=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is neither \'+' nor \'-', it means = value. -C [+|-]:::: 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] |[/]:: Create a writable/readonly snapshot of the subvolume with the name in the directory. + If only is given, the subvolume will be named the basename of . If is not a subvolume, btrfs returns an error. If '-r' is given, the snapshot will be readonly. *get-default* :: Get the default subvolume of the filesystem . + The output format is similar to *subvolume list* command. *set-default* :: Set the subvolume of the filesystem which is mounted as default. + The subvolume is identified by , which is returned by the *subvolume list* command. *find-new* :: List the recently modified files in a subvolume, after ID. *show* :: Show information of a given subvolume in the . 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),