btrfs-subvolume
Manage Btrfs subvolumes and snapshots
TLDR
Create a new empty subvolume
List all subvolumes and snapshots in the specified filesystem
Delete a subvolume
Create a read-only snapshot of an existing subvolume
Create a read-write snapshot of an existing subvolume
Show detailed information about a subvolume
SYNOPSIS
btrfs subvolume create [options] path
btrfs subvolume delete [options] path [path...]
btrfs subvolume list [options] path
btrfs subvolume snapshot [options] source_path destination_path
btrfs subvolume show [options] path
PARAMETERS
create
Creates a new empty subvolume at the specified path. Can create read-only subvolumes (`-r` option) or set quota groups (`-q` option).
delete
Deletes one or more specified subvolumes. This action is irreversible. Use with caution. Multiple subvolumes can be deleted in one command.
list
Lists existing subvolumes for the given filesystem path, displaying their ID, generation, and other attributes. Supports various filtering and formatting options.
snapshot
Creates a copy-on-write snapshot of an existing subvolume. Snapshots can be read-write (default) or read-only (`-r` option), and are often used for backups or testing environments.
show
Displays detailed information about a specific subvolume, including its ID, UUID, creation time, and flags.
get-default
Retrieves the ID of the default subvolume for a given filesystem, which is mounted when no specific subvolume is explicitly specified in the mount options.
set-default
Sets the default subvolume for a Btrfs filesystem to a specified subvolume ID. This affects what gets mounted by default for the top-level filesystem.
sync
Waits until all pending subvolume operations (like create or delete) on the filesystem are committed to disk, ensuring data integrity before further actions.
find-new
Lists changed files in a subvolume since a given generation number (`gen`), typically used with incremental `btrfs send` for efficient backups.
DESCRIPTION
The btrfs subvolume command is a crucial utility for managing subvolumes within a Btrfs filesystem. A Btrfs subvolume is an independently mountable filesystem tree, similar to a separate partition but existing within a single Btrfs volume. They are core to Btrfs's advanced features, offering isolation, flexible organization, and enabling efficient snapshotting and incremental backups via `btrfs send/receive`. This command allows users to create new subvolumes, delete existing ones, list them, and create copy-on-write snapshots for data versioning and recovery. Subvolumes appear as regular directories but have distinct filesystem roots, making them incredibly versatile for system organization, containerization, and atomic updates.
CAVEATS
Deleting a subvolume is a permanent operation and cannot be undone. Data stored within a deleted subvolume is unrecoverable. Snapshots are copy-on-write, meaning they initially share data blocks with their parent. This saves space but can make calculating space usage complex. Deleting a subvolume that has active snapshots does not free all its data blocks until those snapshots are also deleted. Nested subvolumes behave differently regarding deletion and snapshotting than flat structures.
ROOT SUBVOLUME (ID 5)
Every Btrfs filesystem has a top-level root subvolume with ID 5. This is the default subvolume that gets mounted if no specific subvolume is specified in the mount command. User-created subvolumes are typically created inside this root or other existing subvolumes.
READ-ONLY VS. READ-WRITE SNAPSHOTS
Snapshots can be created as either read-write (default) or read-only. Read-write snapshots can be modified and used as independent subvolumes for testing or development. Read-only snapshots are immutable and primarily used for reliable backups or as a source for `btrfs send` operations.
NESTED SUBVOLUMES
Subvolumes can be created inside other subvolumes, forming a nested hierarchy. If a parent subvolume is deleted, all its nested subvolumes are also deleted. Snapshots of a parent subvolume do not automatically include its nested subvolumes; each nested subvolume must be snapshotted independently if its state needs to be preserved.
HISTORY
The Btrfs filesystem, and thus its subvolume concept, began development at Oracle in 2007. It was merged into the Linux kernel mainline in version 2.6.29 (2009). The subvolume feature is fundamental to Btrfs's design, enabling its unique capabilities like efficient snapshots and flexible data management. Its usage has grown significantly as Btrfs has matured and gained adoption across various Linux distributions as a modern filesystem.
SEE ALSO
btrfs(8), btrfs-send(8), btrfs-receive(8), btrfs-filesystem(8), mount(8), findmnt(8)