btrfs-progs/Documentation/btrfs-filesystem.asciidoc

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.
Any extent bigger than threshold given by '-t' option, will be considered
already defragged.
Use 0 to take the kernel default.
You can also turn on compression in defragment operations.
+
`Options`
+
-v::::
be verbose
-c::::
compress file contents while defragmenting
-r::::
defragment files recursively
-f::::
flush filesystem after defragmenting
-s <start>[kKmMgGtTpPeE]::::
defragment only from byte <start> onward
-l <len>[kKmMgGtTpPeE]::::
defragment only up to <len> bytes
-t <size>[kKmMgGtTpPeE]::::
defragment only files at least <size> bytes big
+
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* [--mounted|--all-devices|<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.
If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
filesystem(s);
If '--all-devices' is passed, all the devices under /dev are scanned;
otherwise the devices list is extracted from the /proc/partitions file.

*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),