summaryrefslogtreecommitdiff
path: root/man/btrfs.8.in
blob: 1ffed135b92ffef2f0d054275df7c67f6bb9c36a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
.TH BTRFS 8 "" "btrfs" "btrfs"
.\"
.\" Man page written by Goffredo Baroncelli <kreijack@inwind.it> (Feb 2010)
.\"
.SH NAME
btrfs \- control a btrfs filesystem
.SH SYNOPSIS
\fBbtrfs\fP \fBsubvolume snapshot\fP\fI <source> [<dest>/]<name>\fP
.PP
\fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume>\fP
.PP
\fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP
.PP
\fBbtrfs\fP \fBsubvolume list\fP\fI <path>\fP
.PP
\fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP
.PP
\fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP
.PP
\fBbtrfs\fP \fBfilesystem resize\fP\fI [+/\-]<size>[gkm]|max <filesystem>\fP
.PP
\fBbtrfs\fP \fBfilesystem defrag\fP\fI [options] <file>|<dir> [<file>|<dir>...]\fP
.PP
\fBbtrfs\fP \fBdevice scan\fP\fI [<device> [<device>..]]\fP
.PP
\fBbtrfs\fP \fBdevice show\fP\fI <dev>|<label> [<dev>|<label>...]\fP
.PP
\fBbtrfs\fP \fBdevice balance\fP\fI <path> \fP
.PP
\fBbtrfs\fP \fBdevice add\fP\fI <dev> [<dev>..] <path> \fP
.PP
\fBbtrfs\fP \fBdevice delete\fP\fI <dev> [<dev>..] <path> \fP]
.PP
\fBbtrfs\fP \fBhelp|\-\-help|\-h \fP\fI\fP
.PP
\fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP
.PP
.SH DESCRIPTION
.B btrfs
is used to control the filesystem and the files and directories stored. It is
the tool to create or destroy a snapshot or a subvolume for the
filesystem, to defrag a file or a directory, flush the data to the disk,
to resize the filesystem, to scan the device.

It is possible to abbreviate the commands unless the commands  are ambiguous.
For example: it is possible to run
.I btrfs sub snaps
instead of
.I btrfs subvolume snapshot.
But
.I btrfs dev s
is not allowed, because
.I dev s
may be interpreted both as
.I device show
and as
.I device scan.
In this case
.I btrfs
returns an error.

If a command is terminated by
.I --help
, the detailed help is showed. If the passed command matches more commands,
detailed help of all the matched commands is showed. For example
.I btrfs dev --help
shows the help of all
.I device*
commands.

.SH COMMANDS
.TP

\fBsubvolume snapshot\fR\fI <source> [<dest>/]<name>\fR
Create a writable snapshot of the subvolume \fI<source>\fR with the name
\fI<name>\fR in the \fI<dest>\fR directory. If \fI<source>\fR is not a
subvolume, \fBbtrfs\fR returns an error.
.TP

\fBsubvolume delete\fR\fI <subvolume>\fR
Delete the subvolume \fI<subvolume>\fR. If \fI<subvolume>\fR is not a
subvolume, \fBbtrfs\fR returns an error.
.TP

\fBsubvolume create\fR\fI [<dest>/]<name>\fR
Create a subvolume in \fI<dest>\fR (or in the current directory if
\fI<dest>\fR is omitted).
.TP

\fBsubvolume list\fR\fI <path>\fR
List the subvolumes present in the filesystem \fI<path>\fR. For every
subvolume is showed the subvolume ID (second column), 
the ID of the \fItop level\fR 
subvolume (fifth column), and the path (seventh column) relative to the
\fItop level\fR subvolume.
These <ID> may be used by the \fBsubvolume set-default\fR command, or at
mount time via the \fIsubvol=\fR option.
.TP

\fBsubvolume set-default\fR\fI <id> <path>\fR
Set the subvolume of the filesystem \fI<path>\fR which is mounted as 
\fIdefault\fR. The subvolume is identified by \fI<id>\fR, which 
is returned by the \fBsubvolume list\fR command.
.TP

\fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...]

Defragment file data and/or directory metadata. To defragment all files in a
directory you have to specify each one on its own or use your shell wildcards.

The start position and the number of bytes to deframention can be specified by \fIstart\fR and \fIlen\fR. Any extent bigger than \fIthresh\fR will be considered already defragged. Use 0 to take the kernel default, and use 1 to say eveery single extent must be rewritten. You can also turn on compression in defragment operations.

\fB-v\fP be verbose

\fB-c\fP compress file contents while defragmenting

\fB-f\fP flush filesystem after defragmenting

\fB-s start\fP defragment only from byte \fIstart\fR onward

\fB-l len\fP defragment only up to \fIlen\fR bytes

\fB-t size\fP defragment only files at least \fIsize\fR bytes big

NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data, don't 
use it if you use snapshots, have de-duplicated your data or made copies with 
\fBcp --reflink\fP.
.TP

\fBdevice scan\fR \fI[<device> [<device>..]]\fR
Scan devices for a btrfs filesystem. If no devices are passed, \fBbtrfs\fR scans
all the block devices.
.TP

\fBfilesystem sync\fR\fI <path> \fR
Force a sync for the filesystem identified by \fI<path>\fR.
.TP

.\"
.\" Some wording are extracted by the resize2fs man page
.\"

\fBfilesystem resize\fR\fI [+/\-]<size>[gkm]|max <path>\fR
Resize a filesystem identified by \fI<path>\fR.
The \fI<size>\fR parameter specifies the new size of the filesystem.
If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased
by the quantity \fI<size>\fR.
If no units are specified, the unit of the \fI<size>\fR parameter defaults to
bytes. Optionally, the size parameter may be suffixed by one of the following
the units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes,
respectively.

If 'max' is passed, the filesystem will occupy all available space on the
volume(s).

The \fBresize\fR command \fBdoes not\fR manipulate the size of underlying
partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
can expand the partition before enlarging the filesystem and shrink the
partition after reducing the size of the filesystem.
.TP

\fBfilesystem show\fR [<uuid>|<label>]\fR
Show the btrfs filesystem with some additional info. If no UUID or label is
passed, \fBbtrfs\fR show info of all the btrfs filesystem.
.TP

\fBdevice balance\fR \fI<path>\fR
Balance the chunks of the filesystem identified by \fI<path>\fR
across the devices.
.TP

\fBdevice add\fR\fI <dev> [<dev>..] <path>\fR
Add device(s) to the filesystem identified by \fI<path>\fR.
.TP

\fBdevice delete\fR\fI <dev> [<dev>..] <path>\fR
Remove device(s) from a filesystem identified by \fI<path>\fR.
.PP

.SH EXIT STATUS
\fBbtrfs\fR returns a zero exist status if it succeeds. Non zero is returned in
case of failure.

.SH AVAILABILITY
.B btrfs
is part of btrfs-progs. Btrfs filesystem is currently under heavy development,
and not suitable for any uses other than benchmarking and review.
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
further details.
.SH SEE ALSO
.BR mkfs.btrfs (8)