1BTRFS-SUBVOLUME(8) Btrfs Manual BTRFS-SUBVOLUME(8)
2
6 btrfs-subvolume - manage btrfs subvolumes
7
9 btrfs subvolume <subcommand> [<args>]
10
12 btrfs subvolume is used to create/delete/list/show btrfs subvolumes and
13 snapshots.
14
16 A subvolume is a part of filesystem with its own independent
17 file/directory hierarchy. Subvolumes can share file extents. A snapshot
18 is also subvolume, but with a given initial content of the original
19 subvolume.
20 Note
22 A subvolume in btrfs is not like an LVM logical volume, which is
23 block-level snapshot while btrfs subvolumes are file extent-based.
24 A subvolume looks like a normal directory, with some additional
26 operations described below. Subvolumes can be renamed or moved, nesting
27 subvolumes is not restricted but has some implications regarding
28 snapshotting.
29 A subvolume in btrfs can be accessed in two ways:
31 · like any other directory that is accessible to the user
33 · like a separately mounted filesystem (options subvol or subvolid)
35 In the latter case the parent directory is not visible and accessible.
37 This is similar to a bind mount, and in fact the subvolume mount does
38 exactly that.
39 A freshly created filesystem is also a subvolume, called top-level,
41 internally has an id 5. This subvolume cannot be removed or replaced by
42 another subvolume. This is also the subvolume that will be mounted by
43 default, unless the default subvolume has been changed (see subcommand
44 set-default).
45 A snapshot is a subvolume like any other, with given initial content.
47 By default, snapshots are created read-write. File modifications in a
48 snapshot do not affect the files in the original subvolume.
49
51 create [-i <qgroupid>] [<dest>/]<name>
52 Create a subvolume <name> in <dest>.
53 If <dest> is not given, subvolume <name> will be created in the
55 current directory.
56 Options
58 -i <qgroupid>
60 Add the newly created subvolume to a qgroup. This option can be
61 given multiple times.
62 delete [options] <[<subvolume> [<subvolume>...]], delete -i|--subvolid
64 <subvolid> <path>>
65 Delete the subvolume(s) from the filesystem.
66 If <subvolume> is not a subvolume, btrfs returns an error but
68 continues if there are more arguments to process.
69 If --subvolid is used, <path> must point to a btrfs filesystem. See
71 btrfs subvolume list or btrfs inspect-internal rootid how to get
72 the subvolume id.
73 The corresponding directory is removed instantly but the data
75 blocks are removed later in the background. The command returns
76 immediately. See btrfs subvolume sync how to wait until the
77 subvolume gets completely removed.
78 The deletion does not involve full transaction commit by default
80 due to performance reasons. As a consequence, the subvolume may
81 appear again after a crash. Use one of the --commit options to wait
82 until the operation is safely stored on the device.
83 Options
85 -c|--commit-after
87 wait for transaction commit at the end of the operation.
88 -C|--commit-each
90 wait for transaction commit after deleting each subvolume.
91 -v|--verbose
93 verbose output of operations.
94 -i|--subvolid <subvolid>
96 subvolume id to be removed instead of the <path> that should
97 point to the filesystem with the subvolume
98 find-new <subvolume> <last_gen>
100 List the recently modified files in a subvolume, after <last_gen>
101 generation.
102 get-default <path>
104 Get the default subvolume of the filesystem <path>.
105 The output format is similar to subvolume list command.
107 list [options] [-G [+|-]<value>] [-C [+|-]<value>]
109 [--sort=rootid,gen,ogen,path] <path>
110 List the subvolumes present in the filesystem <path>.
111 For every subvolume the following information is shown by default:
113 ID <ID> gen <generation> top level <ID> path <path>
115 where ID is subvolume’s id, gen is an internal counter which is
117 updated every transaction, top level is the same as parent
118 subvolume’s id, and path is the relative path of the subvolume to
119 the top level subvolume. The subvolume’s ID may be used by the
120 subvolume set-default command, or at mount time via the subvolid=
121 option.
122 Options
124 Path filtering
126 -o
128 print only subvolumes below specified <path>.
129 -a
131 print all the subvolumes in the filesystem and distinguish
132 between absolute and relative path with respect to the
133 given <path>.
134 Field selection
136 -p
138 print the parent ID (parent here means the subvolume which
139 contains this subvolume).
140 -c
142 print the ogeneration of the subvolume, aliases: ogen or
143 origin generation.
144 -g
146 print the generation of the subvolume (default).
147 -u
149 print the UUID of the subvolume.
150 -q
152 print the parent UUID of the subvolume (parent here means
153 subvolume of which this subvolume is a snapshot).
154 -R
156 print the UUID of the sent subvolume, where the subvolume
157 is the result of a receive operation.
158 Type filtering
160 -s
162 only snapshot subvolumes in the filesystem will be listed.
163 -r
165 only readonly subvolumes in the filesystem will be listed.
166 -d
168 list deleted subvolumes that are not yet cleaned.
169 Other
171 -t
173 print the result as a table.
174 Sorting
176 By default the subvolumes will be sorted by subvolume ID
177 ascending.
178 -G [+|-]<value>
180 list subvolumes in the filesystem that its generation is
181 >=, ⟨ or = value. '+' means >= value, '-' means <= value,
182 If there is neither '+' nor '-', it means = value.
183 -C [+|-]<value>
185 list subvolumes in the filesystem that its ogeneration is
186 >=, <= or = value. The usage is the same to -G option.
187 --sort=rootid,gen,ogen,path
189 list subvolumes in order by specified items. you can add
190 '+' or '-' in front of each items, '+' means ascending, '-'
191 means descending. The default is ascending.
192 for --sort you can combine some items together by ',', just
194 like --sort=+ogen,-gen,path,rootid.
195 set-default [<subvolume>|<id> <path>]
197 Set the default subvolume for the (mounted) filesystem.
198 Set the default subvolume for the (mounted) filesystem at <path>.
200 This will hide the top-level subvolume (i.e. the one mounted with
201 subvol=/ or subvolid=5). Takes action on next mount.
202 There are two ways how to specify the subvolume, by <id> or by the
204 <subvolume> path. The id can be obtained from btrfs subvolume list,
205 btrfs subvolume show or btrfs inspect-internal rootid.
206 show [options] <path>
208 Show more information about subvolume <path> regarding UUIDs,
209 times, generations, flags and related snapshots.
210 /mnt/btrfs/subvolume
212 Name: subvolume
213 UUID: 5e076a14-4e42-254d-ac8e-55bebea982d1
214 Parent UUID: -
215 Received UUID: -
216 Creation time: 2018-01-01 12:34:56 +0000
217 Subvolume ID: 79
218 Generation: 2844
219 Gen at creation: 2844
220 Parent ID: 5
221 Top level ID: 5
222 Flags: -
223 Snapshot(s):
224 Options
226 -r|--rootid
228 rootid of the subvolume.
229 -u|--uuid
231 UUID of the subvolume.
232 snapshot [-r|-i <qgroupid>] <source> <dest>|[<dest>/]<name>
234 Create a snapshot of the subvolume <source> with the name <name> in
235 the <dest> directory.
236 If only <dest> is given, the subvolume will be named the basename
238 of <source>. If <source> is not a subvolume, btrfs returns an
239 error.
240 Options
242 -r
244 Make the new snapshot read only.
245 -i <qgroupid>
247 Add the newly created subvolume to a qgroup. This option can be
248 given multiple times.
249 sync <path> [subvolid...]
251 Wait until given subvolume(s) are completely removed from the
252 filesystem after deletion. If no subvolume id is given, wait until
253 all current deletion requests are completed, but do not wait for
254 subvolumes deleted in the meantime.
255 Options
257 -s <N>
259 sleep N seconds between checks (default: 1)
260
262 btrfs subvolume returns a zero exit status if it succeeds. A non-zero
263 value is returned in case of failure.
264
266 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
267 http://btrfs.wiki.kernel.org for further details.
268
270 mkfs.btrfs(8), mount(8), btrfs-quota(8), btrfs-qgroup(8),
271Btrfs v5.6 04/05/2020 BTRFS-SUBVOLUME(8)