btrfs-filesystem

Show filesystem usage (optionally run as root to show detailed information)

$ btrfs [[f|filesystem]] [[u|usage]] [path/to/btrfs_mount]

$ sudo btrfs [[f|filesystem]] [[sh|show]] [path/to/btrfs_mount]

$ sudo btrfs [[f|filesystem]] [[de|defragment]] [[-v|--verbose]] [path/to/file]

$ sudo btrfs [[f|filesystem]] [[de|defragment]] [[-v|--verbose]] -r [path/to/directory]

$ sudo btrfs [[f|filesystem]] [[sy|sync]] [path/to/btrfs_mount]

$ sudo btrfs [[f|filesystem]] du [[-s|--summarize]] [path/to/directory]

$ sudo btrfs [[f|filesystem]] [[m|mkswapfile]] --size [8g] --uuid [clear|random|time|UUID_value] [path/to/swapfile]

btrfs filesystem <subcommand> [options] [arguments]

show [options] [path|uuid]
    Displays overall Btrfs filesystem usage information, including allocated and free space for data, metadata, and system chunks. Optionally shows information for a specific path or UUID.

df [options] <path>
    Shows Btrfs filesystem space statistics, similar to the traditional df command but with Btrfs-specific details about profiles and usage.

balance [options] <path>
    Rebalances data and metadata block groups across the Btrfs filesystem's devices. This can be used to convert profiles, free up space on specific devices, or reorganize data.

resize [options] <size> <path>
    Resizes a Btrfs filesystem. Can be used to enlarge or shrink the filesystem. size can be a specific value (e.g., '+1G', 'max', '100G').

defragment [options] <file|directory> [...]
    Defragments specified files or directories on a Btrfs filesystem. This helps to improve performance by reducing fragmentation.

The btrfs filesystem group of commands provides utilities for managing the state, space usage, and properties of a Btrfs filesystem. It is a crucial part of the overall btrfs administration toolkit, allowing administrators to monitor disk space allocation, rebalance data and metadata across multiple devices, resize the filesystem, and defragment files.

Unlike traditional filesystems, Btrfs manages space in terms of block groups and profiles (e.g., RAID0, RAID1). The filesystem commands reflect this unique architecture, offering granular control over how data is stored and distributed. Operations within this group range from simple informational queries like displaying disk usage, to more complex and potentially long-running tasks such as balancing data across underlying storage devices or resizing the filesystem to utilize more or less space. These commands are essential for maintaining the health, performance, and flexibility of Btrfs filesystems, especially in multi-device configurations.

Most btrfs filesystem operations require root privileges or equivalent capabilities. Operations like balance can be very I/O intensive and time-consuming, potentially impacting system performance during execution. Shrinking a filesystem with resize requires careful planning and sufficient free space. Always ensure proper backups before performing significant filesystem modifications.

Btrfs allocates space in 'chunks' (typically 1GB for data, 256MB for metadata). The filesystem show and df commands provide insights into how these chunks are used and what 'profiles' (e.g., DUP, RAID1) are active for data and metadata. This differs significantly from traditional block-based filesystems.

The balance command offers various filters and options (e.g., 'usage', 'convert', 'limit') to precisely control which block groups are processed. It can be run incrementally and resumed if interrupted, making it a powerful tool for complex storage reconfigurations or space reclamation.

Btrfs, or 'B-tree file system', was initially developed by Oracle Corporation in 2007. The btrfs filesystem commands emerged as integral components of the main btrfs utility, designed to provide comprehensive management capabilities for the filesystem's unique architecture. As Btrfs matured and gained features like multi-device support, RAID profiles, and copy-on-write snapshots, the filesystem subcommands evolved to manage these complexities. Their development reflects the ongoing effort to make Btrfs a robust and flexible filesystem for Linux, suitable for a wide range of storage needs from desktops to enterprise servers.

btrfs(8), mkfs.btrfs(8), mount(8), df(1), btrfs-balance(8), btrfs-resize(8)