btrfs-filesystem(8)
===================

NAME
----
btrfs-filesystem - control btrfs filesystem

SYNOPSIS
--------
*btrfs filesystem* <subcommand> <args>

DESCRIPTION
-----------
*btrfs filesystem* is used to do the filesystem level control jobs, including
all the regular filesystem operations like setting/getting label,
resizing, defragment.

SUBCOMMAND
----------
*df* [options] <path>::
Show space usage information for a mount point.
+
`Options`
+
-b|--raw::::
raw numbers in bytes, without the 'B' suffix
-h|--human-readable::::
print human friendly numbers, base 1024, this is the default
-H::::
print human friendly numbers, base 1000
--iec::::
select the 1024 base for the following options, according to the IEC standard
--si::::
select the 1000 base for the following options, according to the SI standard
-k|--kbytes::::
show sizes in KiB, or kB with --si
-m|--mbytes::::
show sizes in MiB, or MB with --si
-g|--gbytes::::
show sizes in GiB, or GB with --si
-t|--tbytes::::
show sizes in TiB, or TB with --si
+
If conflicting options are passed, the last one takes precedence.

*defragment* [options] <file>|<dir> [<file>|<dir>...]::
Defragment file data and/or directory metadata *online*.
+
If '-r' is passed, files in dir will be defragmented recursively.
The start position and the number of bytes to defragment can be specified by
start and len using '-s' and '-l' options below.
Extents bigger than value given by '-t' will be skipped, otherwise this value
is used as a target extent size, but is only advisory and may not be reached
if the free space is too fragmented.
Use 0 to take the kernel default, which is 256kB but may change in the future.
You can also turn on compression in defragment operations.
+
`Options`
+
-v::::
be verbose
-c[<algo>]::::
compress file contents while defragmenting. Optional argument selects the compression
algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no
compression.
-r::::
defragment files recursively in given directories
-f::::
flush data for each file before going to the next file. This will limit the amount
of dirty data to current file, otherwise the amount cumulates from several files
and may increase system load.
-s <start>[kKmMgGtTpPeE]::::
defragment only from byte <start> onward
-l <len>[kKmMgGtTpPeE]::::
defragment only up to <len> bytes
-t <size>[kKmMgGtTpPeE]::::
target extent size, do not touch extents bigger than <size>
+
For <start>, <len>, <size> it is possible to append
units designator: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
+
WARNING: 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 `cp --reflink`.

*label* [<dev>|<mountpoint>] [<newlabel>]::
Show or update the label of a filesystem.
+
[<device>|<mountpoint>] is used to identify the filesystem.
If a newlabel optional argument is passed, the label is changed.
+
NOTE: the maximum allowable length shall be less than 256 chars

// Some wording are extracted by the resize2fs man page
*resize* [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>::
Resize a mounted filesystem identified by directory <path>. A particular device
can be resized by specifying a <devid>.
+
If <path> is a file containing a btrfs image then resize does not work as
expected and does not resize the image. This would resize the underlying
filesystem instead.
+
The devid can be found with *btrfs filesystem show* and
defaults to 1 if not specified.
The <size> parameter specifies the new size of the filesystem.
If the prefix + or - is present the size is increased or decreased
by the quantity <size>.
If no units are specified, the unit of the <size> parameter defaults to
bytes. Optionally, the size parameter may be suffixed by one of the following
units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
KiB, MiB, GiB, TiB, PiB, or EiB, respectively. Case does not matter.
+
If \'max' is passed, the filesystem will occupy all available space on the
device devid.
+
The resize command does not 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.  This can done using
`fdisk`(8) or `parted`(8) to delete the existing partition and recreate
it with the new desired size.  When recreating the partition make sure to use
the same starting disk cylinder as before.

*show* [options] [<path>|<uuid>|<device>|<label>]::
Show the btrfs filesystem with some additional info.
+
If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
information of all the btrfs filesystem both mounted and unmounted.
+
`Options`
+
-m|--mounted::::
probe btrfs kernel to list mounted btrfs filesystems(s)
-d|--all-devices::::
scan all devices under /dev, otherwise the devices list is extracted from the
/proc/partitions file.
--raw::::
raw numbers in bytes, without the 'B' suffix
--human-readable::::
print human friendly numbers, base 1024, this is the default
--iec::::
select the 1024 base for the following options, according to the IEC standard
--si::::
select the 1000 base for the following options, according to the SI standard
--kbytes::::
show sizes in KiB, or kB with --si
--mbytes::::
show sizes in MiB, or MB with --si
--gbytes::::
show sizes in GiB, or GB with --si
--tbytes::::
show sizes in TiB, or TB with --si

*sync* <path>::
Force a sync for the filesystem identified by <path>.

*usage* [options] <path> [<path>...]::
Show detailed information about internal filesystem usage.
+
`Options`
+
-b|--raw::::
raw numbers in bytes, without the 'B' suffix
-h|--human-readable::::
print human friendly numbers, base 1024, this is the default
-H::::
print human friendly numbers, base 1000
--iec::::
select the 1024 base for the following options, according to the IEC standard
--si::::
select the 1000 base for the following options, according to the SI standard
-k|--kbytes::::
show sizes in KiB, or kB with --si
-m|--mbytes::::
show sizes in MiB, or MB with --si
-g|--gbytes::::
show sizes in GiB, or GB with --si
-t|--tbytes::::
show sizes in TiB, or TB with --si
-T::::
show data in tabular format
+
If conflicting options are passed, the last one takes precedence.

EXIT STATUS
-----------
*btrfs filesystem* returns a zero exit 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),
