Documentation/btrfs-subvolume.asciidoc

   1 btrfs-subvolume(8)
   2 ==================
   3
   4 NAME
   5 ----
   6 btrfs-subvolume - manage btrfs subvolumes
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs subvolume* <subcommand> [<args>]
  11
  12 DESCRIPTION
  13 -----------
  14 *btrfs subvolume* is used to create/delete/list/show btrfs subvolumes and
  15 snapshots.
  16
  17 SUBVOLUME AND SNAPSHOT
  18 ----------------------
  19
  20 A subvolume is a part of filesystem with its own and independent
  21 file/directory hierarchy. Subvolumes can share file extents. A snapshot is
  22 also subvolume, but with a given initial content of the original subvolume.
  23
  24 NOTE: A subvolume in btrfs is not like an LVM logical volume, which is
  25 block-level snapshot while btrfs subvolumes are file extent-based.
  26
  27 A subvolume looks like a normal directory, with some additional operations
  28 described below. Subvolumes can be renamed or moved, nesting subvolumes is not
  29 restricted but has some implications regarding snapshotting.
  30
  31 A subvolume in btrfs can be accessed in two ways:
  32
  33 * like any other directory that is accessible to the user
  34 * like a separately mounted filesystem (options 'subvol' or 'subvolid')
  35
  36 In the latter case the parent directory is not visible and accessible. This is
  37 similar to a bind mount, and in fact the subvolume mount does exactly that.
  38
  39 A freshly created filesystem is also a subvolume, called 'top-level',
  40 internally has an id 5. This subvolume cannot be removed or replaced by another
  41 subvolume. This is also the subvolume that will be mounted by default, unless
  42 the default subvolume has been changed (see subcommand 'set-default').
  43
  44 A snapshot is a subvolume like any other, with given initial content. By
  45 default, snapshots are created read-write. File modifications in a snapshot
  46 do not affect the files in the original subvolume.
  47
  48 SUBCOMMAND
  49 -----------
  50 *create* [-i <qgroupid>] [<dest>/]<name>::
  51 Create a subvolume <name> in <dest>.
  52 +
  53 If <dest> is not given, subvolume <name> will be created in the current
  54 directory.
  55 +
  56 `Options`
  57 +
  58 -i <qgroupid>::::
  59 Add the newly created subvolume to a qgroup. This option can be given multiple
  60 times.
  61
  62 *delete* [options] <subvolume> [<subvolume>...]::
  63 Delete the subvolume(s) from the filesystem.
  64 +
  65 If <subvolume> is not a subvolume, btrfs returns an error but continues if
  66 there are more arguments to process.
  67 +
  68 The corresponding directory is removed instantly but the data blocks are
  69 removed later.  The deletion does not involve full commit by default due to
  70 performance reasons (as a consequence, the subvolume may appear again after a
  71 crash).  Use one of the '--commit' options to wait until the operation is safely
  72 stored on the media.
  73 +
  74 `Options`
  75 +
  76 -c|--commit-after::::
  77 wait for transaction commit at the end of the operation
  78 +
  79 -C|--commit-each::::
  80 wait for transaction commit after deleting each subvolume
  81
  82 *find-new* <subvolume> <last_gen>::
  83 List the recently modified files in a subvolume, after <last_gen> ID.
  84
  85 *get-default* <path>::
  86 Get the default subvolume of the filesystem <path>.
  87 +
  88 The output format is similar to *subvolume list* command.
  89
  90 *list* [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>::
  91 List the subvolumes present in the filesystem <path>.
  92 +
  93 For every subvolume the following information is shown by default. +
  94 ID <ID> top level <ID> path <path> +
  95 where path is the relative path of the subvolume to the top level subvolume.
  96 The subvolume's ID may be used by the subvolume set-default command,
  97 or at mount time via the subvolid= option.
  98 If `-p` is given, then parent <ID> is added to the output between ID
  99 and top level. The parent's ID may be used at mount time via the
 100 `subvolrootid=` option.
 101 +
 102 `Options`
 103 +
 104 -p::::
 105 print parent ID.
 106 -a::::
 107 print all the subvolumes in the filesystem and distinguish between
 108 absolute and relative path with respect to the given <path>.
 109 -c::::
 110 print the ogeneration of the subvolume, aliases: ogen or origin generation.
 111 -g::::
 112 print the generation of the subvolume.
 113 -o::::
 114 print only subvolumes below specified <path>.
 115 -u::::
 116 print the UUID of the subvolume.
 117 -q::::
 118 print the parent uuid of subvolumes (and snapshots).
 119 -R::::
 120 print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
 121 -t::::
 122 print the result as a table.
 123 -s::::
 124 only snapshot subvolumes in the filesystem will be listed.
 125 -r::::
 126 only readonly subvolumes in the filesystem will be listed.
 127 -G [+|-]<value>::::
 128 list subvolumes in the filesystem that its generation is
 129 >=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is
 130 neither \'+' nor \'-', it means = value.
 131 -C [+|-]<value>::::
 132 list subvolumes in the filesystem that its ogeneration is
 133 >=, \<= or = value. The usage is the same to '-G' option.
 134 --sort=rootid,gen,ogen,path::::
 135 list subvolumes in order by specified items.
 136 you can add \'\+' or \'-' in front of each items, \'+' means ascending,
 137 \'-' means descending. The default is ascending.
 138 +
 139 for --sort you can combine some items together by \',', just like
 140 --sort=+ogen,-gen,path,rootid.
 141
 142 *set-default* <id> <path>::
 143 Set the subvolume of the filesystem <path> which is mounted as
 144 default.
 145 +
 146 The subvolume is identified by <id>, which is returned by the *subvolume list*
 147 command.
 148
 149 *show* <path>::
 150 Show information of a given subvolume in the <path>.
 151
 152 *snapshot* [-r] <source> <dest>|[<dest>/]<name>::
 153 Create a writable/readonly snapshot of the subvolume <source> with the
 154 name <name> in the <dest> directory.
 155 +
 156 If only <dest> is given, the subvolume will be named the basename of <source>.
 157 If <source> is not a subvolume, btrfs returns an error.
 158 If '-r' is given, the snapshot will be readonly.
 159
 160 *sync* <path> [subvolid...]::
 161 Wait until given subvolume(s) are completely removed from the filesystem
 162 after deletion. If no subvolume id is given, wait until all current  deletion
 163 requests are completed, but do not wait for subvolumes deleted meanwhile.
 164 The status of subvolume ids is checked periodically.
 165 +
 166 `Options`
 167 +
 168 -s <N>::::
 169 sleep N seconds between checks (default: 1)
 170
 171 EXIT STATUS
 172 -----------
 173 *btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value is
 174 returned in case of failure.
 175
 176 AVAILABILITY
 177 ------------
 178 *btrfs* is part of btrfs-progs.
 179 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 180 further details.
 181
 182 SEE ALSO
 183 --------
 184 `mkfs.btrfs`(8),
 185 `mount`(8),
 186 `btrfs-quota`(8),
 187 `btrfs-qgroup`(8),