btrfs-progs

Overview

btrfs-progs provides the user-space tools for working with Btrfs filesystems on Linux. It is the utility set that administrators and developers use to create, inspect, check, repair, and manage Btrfs volumes, subvolumes, snapshots, and related filesystem metadata. The package exists in the distribution so systems with Btrfs support have the standard command-line tools needed for day-to-day administration and troubleshooting.

Purpose and typical use cases

Typical use cases include:

• creating or formatting a Btrfs filesystem
• inspecting filesystem and subvolume state
• running maintenance and consistency checks
• managing snapshots, balance operations, device information, and other filesystem administration tasks
• using the documented command-line tools and man pages as the reference interface for automation and recovery work

Typical users are:

• system administrators
• storage and platform engineers
• developers working with Btrfs-aware tooling
• CI/CD or image-build maintainers that validate filesystem-related workflows
• users who administer Btrfs volumes directly from the command line

Upstream project

Upstream documentation describes Btrfs as a Linux copy-on-write filesystem focused on advanced features, fault tolerance, repair, and easier administration. The btrfs-progs project is the userspace companion for that filesystem. Its documentation and command-line reference material are maintained alongside the project, and upstream development is tracked in the project repository and documentation set. NiceOS maintainers should verify upstream packaging and documentation sources when making update decisions.

Dist-git repository contents

This dist-git repository contains the packaging material for btrfs-progs, not the full upstream source tree.

Expected top-level areas include:

• SPECS/ — RPM spec files and packaging logic
• SOURCES/ — source manifests and related metadata used to track the external upstream sources
• METADATA/ — repository metadata used by the packaging workflow
• SBOM/ — software bill of materials material, when present for the package workflow

The repository is meant to describe how NiceOS builds the package, how sources are referenced, and what metadata accompanies the build.

Source storage and integrity policy

Large upstream source archives are intentionally not stored in this Git repository. Instead, source integrity is tracked through manifest files in SOURCES/.

For maintainers, this means:

• the repository should contain the metadata needed to identify and verify upstream sources
• large tarballs or archives belong outside the Git history
• any source refresh should update the manifest files and related packaging metadata together
• if the package workflow uses additional integrity or provenance data, maintainers should verify the exact repository conventions before relying on them

NiceOS maintenance notes

Before updating the package, NiceOS maintainers should check:

• whether the upstream project changed any command syntax, defaults, or file layout that matters to packaging
• whether the spec file still matches the upstream build system and install paths
• whether the source manifest in SOURCES/ needs regeneration because upstream sources changed
• whether any SBOM or metadata files need to be refreshed to reflect the new source set
• whether patches still apply cleanly, and whether any can be dropped or need adjustment
• whether documentation, man pages, shell completions, or auxiliary files moved upstream
• whether the update changes behavior in ways that matter for administration or automated workflows

Risks to consider:

• filesystem utilities can affect real data, so maintainer verification should be careful and reproducible
• packaging changes may alter available subcommands, options, or install locations
• upstream documentation may not cover every distribution-specific packaging choice

Build and verification checklist

A practical RPM maintainer checklist:

• confirm that the spec file still builds against the intended branch
• verify that the external sources referenced in SOURCES/ are current and complete
• check that any patches still apply and are still needed
• build the SRPM and binary RPMs in a clean environment
• run the package test suite or smoke tests if the build system provides them
• confirm that the installed files, man pages, and completions are where the spec expects them
• inspect generated metadata and SBOM outputs if the package workflow produces them
• verify that the package does not accidentally ship the upstream archive inside Git or in the wrong build artifact
• review the changelog and packaging diff for unintended behavior changes

References

• Btrfs documentation
• Linux kernel Btrfs documentation
• btrfs-progs upstream repository
• Btrfs wiki

Russian documentation

See README_RU.md for the Russian version of this document.

Dist-git repository notes

• Package repository: rpms/btrfs-progs
• NiceOS branch: niceos-5.2
• This README is intentionally stable and does not include EVR, source archive checksums or lock hashes.