BCACHEFS(8)

💖 BCACHEFS — the manual, but make it a group chat 💖

okay bestie, so you've met bcachefs (it's the command-line tool for the bcachefs filesystem, and it is lowkey iconic) and now you need the actual manual. This is that. Every command, every category, nothing skipped, everything explained like I actually want you to get it. Periodt. 🎀

---

🌸 SYNOPSIS 🌸

bcachefs command [options] [arguments]

That's the whole vibe: you pick a command, you toss it some options, you hand it some arguments. Slay.

---

✨ DESCRIPTION ✨

The bcachefs utility supports all of these subcommands, and every single one of them gets documented in detail below. Buckle in, bestie, there's a lot and it's all here. 🦋

👑 Superblock commands

These are the "before anything else exists" commands. Superblock girlies, rise.

• format — Format one device, or a whole list of devices, with bcachefs data structures. Fresh start energy. ✨
• show-super — Dump superblock information to stdout. Just, like, reading the superblock's diary. 📖
• set-fs-option — Set a filesystem option. Tweak it, bestie.

🌈 Mount commands

• mount — Mount a filesystem. Yeah, that one. The main character.

🩹 Repair commands

• fsck — Check an existing filesystem for errors. It's giving doctor's appointment. 💀

🧚 Commands for managing a running filesystem

For when the filesystem is already up and living its life:

• fs usage — Show disk usage. How much room do we have, fr fr? 📊
• fs top — Show runtime performance information. It's literally top but for your fs.

💅 Commands for managing devices within a running filesystem

Devices coming and going, no drama (hopefully):

• device add — Add a new device to an existing filesystem. Welcome to the family 🫶
• device remove — Remove a device from an existing filesystem. It's not you, it's capacity planning.
• device online — Re-add an existing member to a filesystem. She's back 💖
• device offline — Take a device offline, without removing it. Pause, not delete.
• device evacuate — Migrate data off of a specific device. Empty her out, gently.
• device set-state — Change the state of a device. Vibe check, but make it stateful.
• device resize — Resize filesystem on a device. Grow up 💅
• device resize-journal — Resize journal on a device. The journal also gets to grow.

🎀 Commands for managing subvolumes and snapshots

• subvolume create — Create a new subvolume. Baby subvolume, born today 🐣
• subvolume delete — Delete an existing subvolume. Bye bestie 😭
• subvolume snapshot — Create a snapshot. Freeze frame, iconic ✨

🍓 Commands for managing filesystem data

• data rereplicate — Rereplicate degraded data. Fixing what got sad. 🔥
• data job — Kick off low level data jobs. Get in, we're going low level.

🔐 Commands for encryption

Locked down, keys out, no cap:

• unlock — Unlock an encrypted filesystem prior to running/mounting it. The key moment (literally). 🔑
• set-passphrase — Change passphrase on an existing (unmounted) filesystem. Note: unmounted, bestie.
• remove-passphrase — Remove passphrase on an existing (unmounted) filesystem. Again: unmounted. 🙈

🚚 Commands for migration

• migrate — Migrate an existing filesystem to bcachefs, in place. No copy-paste, just glow-up in position.
• migrate-superblock — Add default superblock, after bcachefs migrate. The little follow-up step.

📁 Commands for operating on files in a bcachefs filesystem

• set-file-option — Set various per file attributes. Yes, per file. So specific. So cute.

🐛 Commands for debugging

For when you're in your detective era:

• dump — Dump filesystem metadata to a qcow2 image. 🖼️
• list — List filesystem metadata in textual form. Words, not images.
• list_journal — List contents of journal. Yes, with the underscore, exactly like that.

🦋 FUSE commands

• fusemount — Mount a filesystem via FUSE.

⭐ Miscellaneous commands

The catch-all bin, and honestly both of these ate:

• version — Display the version of the invoked bcachefs tool.
• completions — Generate shell completions. Tab-tab-tab supremacy 💅

---

okay that's part one!! more parts coming, don't go anywhere bestie 🫶

---

🗂️ Superblock commands 🗂️

ok so this is where the actual ✨doing stuff✨ happens, bestie. buckle up 💖

bcachefs format [options] devices ...

this is the glow-up moment for your disks 💅 it formats one device, or a whole lil squad of them, with bcachefs data structures. you gotta do this before you can create a volume. it's like the primer before the foundation, no cap.

device-specific options have to come BEFORE their corresponding device, like this:

bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb

so yeah, order matters here fr fr 🙈

• --block_size=size — the block size, in bytes (so like, 4k)
• --btree_node_size=size — btree node size, defaults to 256k
• --errors=(continue | ro | panic) — what it does when the filesystem hits an error
• --data_replicas=number — how many copies of your data you want floating around
• --metadata_replicas=number — how many copies of your metadata
• --data_replicas_required=number — the minimum data replicas you need to keep the thing happy
• --metadata_replicas_required=number — same energy, but for metadata
• --encoded_extent_max=size — maximum size of checksummed/compressed extents
• --metadata_checksum=(none | crc32c | crc64 | xxhash) — pick your metadata checksum type (default: crc32c)
• --data_checksum=(none | crc32c | crc64 | xxhash) — pick your data checksum type (default: crc32c)
• --compression=(none | lz4 | gzip | zstd) — set the compression type (default: none)
• --background_compression=(none | lz4 | gzip | zstd) — compression for the background stuff 🫶
• --str_hash=(crc32c | crc64 | siphash) — the hash function for directory entries and xattrs
• --metadata_target=target — which device or label gets the metadata writes
• --foreground_target=target — which device or label gets the foreground writes
• --background_target=target — which device or label data gets moved to in the background
• --promote_target=target — which device or label data gets promoted to on read
• --erasure_code — enable erasure coding (DO NOT USE YET, seriously, do not, it's giving ⚠️)
• --inodes_32bit — keep inode numbers squished into 32 bits
• --shared_inode_numbers — share new inode numbers by CPU id
• --inodes_use_key_cache — use the btree key cache for the inodes btree
• --gc_reserve_percent=percentage — percentage of disk space reserved for copygc
• --gc_reserve_bytes=percentage — amount of disk space reserved for copygc. heads up: this one takes precedence over gc_reserve_percent if it's set 👀
• --root_reserve_percent=percentage — percentage of disk space reserved for the superuser
• --wide_macs — store the full 128bits of cryptographic MACS, instead of 80
• --acl — enable POSIX acls
• --usrquota — enable user quotas
• --grpquota — enable group quotas
• --prjquota — enable project quotas
• --journal_transaction_names — log transaction function names in the journal
• --nocow — nocow mode: writes get done in place when possible. but lowkey, snapshots and reflink will still cause writes to be COW. and this flag implicitly disables data checksumming, compression and encryption 🫠
• --replicas=number — sets both data and metadata replicas at once, slay
• --encrypted — enable whole filesystem encryption (chacha20/poly1305); it'll prompt you for a passphrase
• --no_passphrase — don't encrypt the master encryption key
• -L, --fs_label=label — create the filesystem with the label you specify
• -U, --uuid=uuid — create the filesystem with the uuid you specify
• --superblock_size=size — sets the superblock size

🔧 Device specific options:

these ones are per-device, so remember — they go before the device they belong to 💖

• --discard — enable discard/TRIM support
• --fs_size=size — create the filesystem using size bytes on the device that comes next
• --bucket=size — specifies the bucket size; it's gotta be greater than the btree node size
• --durability=n — data written to this device counts as already having been replicated n times
• -l, --label — disk label
• -f, --force — force the filesystem to be created, even if the device already has a filesystem on it 😳
• -q, --quiet — only print errors
• -v, --verbose — verbose filesystem initialization

---

bcachefs show-super [options] device

dumps superblock info straight to stdout. it's the ✨look at me✨ command, we love a peek behind the curtain 🦋

• -f, --fields=fields — list of sections to print
• -l, --layout — print the superblock layout

---

bcachefs set-fs-option [options] device

ok so this one tweaks your filesystem options after the fact. huge main character energy 👑

• --errors=(continue | ro | panic) — action to take on filesystem error
• --metadata_replicas=number — number of metadata replicas
• --data_replicas=number — number of data replicas
• --metadata_replicas_required=number — minimum metadata replicas required
• --data_replicas_required=number — minimum data replicas required
• --metadata_checksum=(none | crc32c | crc64 | xxhash) — set metadata checksum type (default: crc32c)
• --data_checksum=(none | crc32c | crc64 | xxhash) — set data checksum type (default: crc32c)
• --compression=(none | lz4 | gzip | zstd) — set compression type (default: none)
• --background_compression=(none | lz4 | gzip | zstd) — compression for background writes
• --str_hash=(crc32c | crc64 | siphash) — hash function for directory entries and xattrs
• --metadata_target=target — device or label for metadata writes
• --foreground_target=target — device or label for foreground writes
• --background_target=target — device or label to move data to in the background
• --promote_target=target — device or label to promote data to on read
• --erasure_code — enable erasure coding (DO NOT USE YET 💀)
• --inodes_32bit — constrain inode numbers to 32 bits
• --shared_inode_numbers — shared new inode numbers by CPU id
• --inodes_use_key_cache — use the btree key cache for the inodes btree
• --gc_reserve_percent=percentage — percentage of disk space to reserve for copygc
• --gc_reserve_bytes=percentage — amount of disk space to reserve for copygc. this takes precedence over gc_reserve_percent if it's set ✨
• --root_reserve_percent=percentage — percentage of disk space to reserve for superuser
• --wide_macs — store full 128bits of cryptographic MACS, instead of 80
• --acl — enable POSIX acls
• --usrquota — enable user quotas
• --grpquota — enable group quotas
• --prjquota — enable project quotas
• --degraded — allow mounting in degraded mode
• --very_degraded — allow mounting when data will be missing 😭
• --discard — enable discard/TRIM support
• --verbose — extra debugging information during mount/recovery
• --journal_flush_delay=ms — delay in milliseconds before automatic journal commits
• --journal_flush_disabled — disable journal flush on sync/fsync. if enabled, writes can be lost, but only since the last journal write (default 1 second) 😬
• --journal_reclaim_delay=ms — delay in milliseconds before automatic journal reclaim
• --move_bytes_in_flight=bytes — maximum amount of IO to keep in flight by the move path
• --move_ios_in_flight=number — maximum number of IOs to keep in flight by the move path
• --fsck — run fsck on mount
• --fix_errors=error — fix errors during fsck without asking
• --ratelimit_errors — ratelimit error messages during fsck
• --nochanges — super read only mode: no writes at all will be issued, even if we have to replay the journal
• --norecovery — don't replay the journal
• --journal_transaction_names — log transaction function names in journal
• --noexcl — don't open device in exclusive mode
• --direct_io — use O_DIRECT (userspace only)
• --sb=offset — sector offset of superblock
• --reconstruct_alloc — reconstruct alloc btree
• --version_upgrade=(compatible | incompatible | none) — set superblock to latest version, allowing any new features to be used
• --nocow — nocow mode: writes will be done in place when possible. snapshots and reflink will still cause writes to be COW. this flag implicitly disables data checksumming, compression and encryption 🙈
• --nocow_enabled — enable nocow mode: enables runtime locking in data move path needed if nocow will ever be in use
• --no_data_io — skip submit_bio() for data reads and writes, for performance testing purposes

ngl bestie, a couple of these are straight up "do not touch yet" territory and a couple will quietly turn off your checksumming/compression/encryption. read before you yeet a flag at your disk, iykyk 💜

🏔️ Mount commands

bcachefs mount [options] device mountpoint

Okay bestie, this is THE one. Mounting a filesystem, the main character moment. 💅

The device can be a single device, a colon-separated list of devices, or UUID=<UUID>. The mountpoint is where it's gonna live in your file tree. And here's a lil plot twist — if you don't set a mountpoint, the filesystem doesn't actually get mounted, but everything before the mounting still happens (like, say, asking you for your passphrase). So it's a rehearsal. A dress rehearsal. 🎭

• -o options — mount options as a comma-separated list, fr. The user guide has the complete list, but here are the hits:
  • degraded — allow mounting with data degraded (some copies missing, she's still standing 🫶)
  • verbose — extra debugging info during mount/recovery
  • fsck — run fsck during mount
  • fix_errors — fix errors without asking during fsck
  • read_only — mount in read only mode
  • version_upgrade
• -k, --key-location=(fail | wait | ask) — where the password would be loaded from. Default is ask.
  • fail — don't ask for a password, just fail if the filesystem is encrypted
  • wait — wait for the password to become available before mounting
  • ask — prompt the user for a password
• -c, --colorize=(true | false) — force color on or off. Default: auto-detect TTY.
• -v — be verbose. Can be specified more than once, so go off. 📢

---

🔧 Repair commands

bcachefs fsck [options] devices ...

Check an existing filesystem for errors. The glow-up check-up. ✨

• -p — automatic repair (no questions)
• -n — don't repair, only check for errors
• -y — assume "yes" to all questions
• -f — force checking even if the filesystem is marked clean
• -r, --ratelimit_errors — don't display more than 10 errors of a given type
• -R, --reconstruct_alloc — reconstruct the alloc btree
• -v — be verbose

---

🌀 Commands for managing a running filesystem

bcachefs fs usage [options] [filesystem]

Show disk usage. The "how much room do I have left" vibe check. 📊

• -h, --human-readable — print human readable sizes

---

💾 Commands for managing devices within a running filesystem

bcachefs device add [options] device

Add a device to an existing filesystem. New friend joining the group chat. 🫶

• --fs_size=size — size of filesystem on device
• --bucket=size — set bucket size
• --discard — enable discards
• -l, --label=label — disk label
• -f, --force — use device even if it appears to already be formatted

---

bcachefs device remove [options] device

Remove a device from a filesystem. Bestie is leaving, we're sad. 😭

• -f, --force — force removal, even if some data couldn't be migrated
• -F, --force-metadata — force removal, even if some metadata couldn't be migrated

ngl those two are the "I know what I'm doing" buttons. Read them twice, babes.

---

bcachefs device online device

Re-add a device to a running filesystem. She's back!! 👑

---

bcachefs device offline device

Take a device offline, without removing it. A lil nap, not a goodbye. 💤

• -f, --force — force, if data redundancy will be degraded

---

bcachefs device evacuate device

Move data off of a given device. Everybody out, we're relocating. 🚚

---

bcachefs device set-state [options] new-state device

• new-state = rw | ro | failed | spare
• -f, --force — force, if data redundancy will be degraded
• --force-if-data-lost — force, if data will be lost
• -o, --offline — set state of an offline device

--force-if-data-lost is literally what it says on the tin. Data. Lost. Be so fr with yourself before typing that.

---

bcachefs device resize device [size]

Resize filesystem on a device. ✨glow up✨

---

bcachefs device resize-journal device [size]

Resize journal on a device.

---

📸 Commands for managing subvolumes and snapshots

subvolume create [options] path

Create a new subvolume. New baby subvolume, welcome to the world 🎀

---

subvolume delete [options] path

Delete an existing subvolume.

---

subvolume snapshot [options] source dest

Create a snapshot of source at dest. If source is specified, it must be a subvolume; if it's not specified, the snapshot will be of the subvolume containing dest.

• -r — make snapshot read-only

---

🗂️ Commands for managing filesystem data

bcachefs data rereplicate filesystem

Walks existing data in a filesystem, writing additional copies of any degraded data. She's out here restoring the missing copies, doing the work nobody asked her to do but she showed up anyway. 💪

---

bcachefs data job job filesystem

Kick off a data job and report progress.

job is one of (scrub | rereplicate | migrate | rewrite_old_nodes)

• -b btree — btree to operate on
• -s inode:offset — start position
• -e inode:offset — end position

---

🔐 Commands for encryption

bcachefs unlock device

Unlock an encrypted filesystem prior to running/mounting. Speak the magic word, bestie 🗝️

• -c — check if a device is encrypted
• -k=(session | user | user_session) — keyring to add to (default: user)

---

bcachefs set-passphrase devices ...

Change passphrase on an existing (unmounted) filesystem.

---

bcachefs remove-passphrase devices ...

Remove passphrase on an existing (unmounted) filesystem.

---

🚚 Commands for migration

bcachefs migrate [options] device

Migrate an existing filesystem to bcachefs. The rebrand. The era change. 🦋

• -f fs — root of filesystem to migrate
• --encrypted — enable whole filesystem encryption (chacha20/poly1305)
• --no_passphrase — don't encrypt master encryption key
• -F — force, even if metadata file already exists

---

bcachefs migrate-superblock [options] device

Create default superblock after migrating.

• -d device — device to create superblock for
• -o offset — offset of existing superblock

---

🎯 Commands for operating on files in a bcachefs filesystem

bcachefs set-file-option [options] [files|folders] ...

Set various per-file attributes on files and directories in a bcachefs filesystem. And the cute part — when you apply it to directories, the attributes propagate recursively to all files and subdirectories within. It's giving generational inheritance. 🌸

• --data_replicas=number — number of data replicas
• --data_checksum=(none | crc32c | crc64 | xxhash) — set data checksum type (default: crc32c).
• --compression=(none | lz4 | gzip | zstd) — set compression type (default: none).
• --background_compression=(none | lz4 | gzip | zstd)
• --metadata_target=target — device or label for metadata writes
• --foreground_target=target — device or label for foreground writes
• --background_target=target — device or label to move data to in the background
• --promote_target=target — device or label to promote data to on read
• --erasure_code — enable erasure coding (DO NOT USE YET)

bestie. It literally says DO NOT USE YET. In caps. Respect the caps. 🙈

• --project
• --nocow — nocow mode: writes will be done in place when possible.
• --remove-all — remove all file options from the specified files/directories

To remove specific options, use --option=-

Options can be chained together to perform multiple operations in a single command, for example:

bcachefs set-file-option --remove-all --compression=lz4.
bcachefs set-file-option --compression=- --background_compression=zstd:10 --data_replicas=- file.txt

---

🐛 Commands for debugging

These commands work on offline, unmounted filesystems. Like, filesystem is asleep, but we're still snooping. 🤫

bcachefs dump [options] device

Dump filesystem metadata.

• -o output — required flag: output qcow2 image(s)
• -f, --force — force; overwrite when needed
• --nojournal — don't dump entire journal, just dirty entries

---

bcachefs list [options] devices ...

List filesystem metadata to stdout.

• -b (extents | inodes | dirents | xattrs) — btree to list from. (default: extents)
• -l, --level — btree depth to descend to. (0 == leaves; default: 0)
• -s inode:offset — start position to list from
• -e inode:offset — end position
• -m, --mode (keys | formats | nodes | nodes-ondisk) — (default: keys)
• -f — check (fsck) the filesystem first
• -c, --colorize=(true | false) — force color on/off. Default: auto-detect TTY
• -v — verbose mode

---

bcachefs list_journal [options] devices ...

• -a — read entire journal, not just dirty entries
• -n, --nr-entries=nr — number of journal entries to print, starting from the most recent
• -s, --seq=seq[..seq] — journal entry sequence or range to print (e.g., 123, 100..200, 100.., ..200)
• -t, --transaction-filter=bbpos — filter transactions not updating bbpos
• -k, --key-filter=btree — filter keys not updating btree
• -v, --verbose — verbose mode

---

🪄 FUSE commands

bcachefs fusemount

Mount a filesystem via FUSE. Userspace said "I'll do it myself." 💫

---

🎲 Miscellaneous commands

bcachefs completions shell

Generate shell completions. Quality of life upgrade, we love to see it. ✨

---

bcachefs version

Display the version of the invoked bcachefs tool.

---

🚦 EXIT STATUS

The bcachefs utility exits 0 on success, and >0 if an error occurs. Zero means we ate, anything else means something went sideways. 💀

---

And that's the whole page, bestie!! 🎀 This was the Debian build of the bcachefs(8) manual, dated November 17, 2023 — go forth and mount responsibly. Mwah. 💖