btrfs-subvolume

Create a new empty subvolume

$ sudo btrfs subvolume create [path/to/new_subvolume]

$ sudo btrfs subvolume list [path/to/btrfs_filesystem]

$ sudo btrfs subvolume delete [path/to/subvolume]

$ sudo btrfs subvolume snapshot -r [path/to/source_subvolume] [path/to/target]

$ sudo btrfs subvolume snapshot [path/to/source_subvolume] [path/to/target]

$ sudo btrfs subvolume show [path/to/subvolume]

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

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.

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.

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.

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.

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.

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.

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.

btrfs(8), btrfs-send(8), btrfs-receive(8), btrfs-filesystem(8), mount(8), findmnt(8)