.Dd November 17, 2023
.Dt BCACHEFS 8 SMM
.Os
.Sh NAME
.Nm bcachefs
.Nd manage bcachefs filesystems/devices
.Sh SYNOPSIS
.Nm
.Ar command
.Op Ar options
.Op Ar arguments
.Sh DESCRIPTION
The
.Nm
utility supports the following subcommands,
which are documented in detail below:
.Ss Superblock commands
.Bl -tag -width 18n -compact
.It Ic format
Format one or a list of devices with bcachefs data structures.
.It Ic show-super
Dump superblock information to stdout.
.It Ic set-fs-option
Set a filesystem option
.El
.Ss Mount commands
.Bl -tag -width 18n -compact
.It Ic mount
Mount a filesystem.
.El
.Ss Repair commands
.Bl -tag -width 18n -compact
.It Ic fsck
Check an existing filesystem for errors.
.El
.Ss Commands for managing a running filesystem
.Bl -tag -width 18n -compact
.It Ic fs usage
Show disk usage
.It Ic fs top
Show runtime performance information
.El
.Ss Commands for managing devices within a running filesystem
.Bl -tag -width 22n -compact
.It Ic device add
Add a new device to an existing filesystem
.It Ic device remove
Remove a device from an existing filesystem
.It Ic device online
Re-add an existing member to a filesystem
.It Ic device offline
Take a device offline, without removing it
.It Ic device evacuate
Migrate data off of a specific device
.It Ic device set-state
Set a device state
.It Ic device resize
Resize filesystem on a device
.It Ic device resize-journal
Resize journal on a device
.El
.Ss Commands for managing subvolumes and snapshots
.Bl -tag -width 18n -compact
.It Ic subvolume create
Create a new subvolume
.It Ic subvolume delete
Delete an existing subvolume
.It Ic subvolume snapshot
Create a snapshot
.It Ic subvolume list
List subvolumes
.It Ic subvolume list-snapshots
List snapshots and their disk usage
.El
.Ss Commands for managing filesystem data
.Bl -tag -width 18n -compact
.It Ic reconcile
Query or wait for background data reconciliation
.It Ic scrub
Verify data checksums
.El
.Ss Commands for encryption
.Bl -tag -width 18n -compact
.It Ic unlock
Unlock an encrypted filesystem prior to running/mounting
.It Ic set-passphrase
Change passphrase on an existing (unmounted) filesystem
.It Ic remove-passphrase
Remove passphrase on an existing (unmounted) filesystem
.El
.Ss Commands for migration
.Bl -tag -width 18n -compact
.It Ic migrate
Migrate an existing filesystem to bcachefs, in place
.It Ic migrate-superblock
Add default superblock, after bcachefs migrate
.El
.Ss Commands for operating on files in a bcachefs filesystem
.Bl -tag -width 18n -compact
.It Ic set-file-option
Set various per file attributes
.El
.Ss Commands for debugging
.Bl -tag -width 18n -compact
.It Ic dump
Dump filesystem metadata to a qcow2 image
.It Ic list
List filesystem metadata in textual form
.It Ic list_journal
List contents of journal
.El
.Ss FUSE commands
.Bl -tag -width 18n -compact
.It Ic fusemount Mount a filesystem via FUSE
.El
.Ss Miscellaneous commands
.Bl -tag -width 18n -compact
.It Ic version
Display the version of the invoked bcachefs tool
.It Ic completions
Generate shell completions
.El
.Sh Superblock commands
.Bl -tag -width Ds
.It Nm Ic format Oo Ar options Oc Ar devices\ ...
Format one or a list of devices with bcachefs data structures.
You need to do this before you create a volume.
.Pp
Device specific options must come before corresponding devices, e.g.
.Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
.Bl -tag -width Ds
.It Fl -block_size Ns = Ns Ar size
block size, in bytes (e.g. 4k)
.It Fl -btree_node_size Ns = Ns Ar size
Btree node size, default 256k
.It Fl -errors Ns = Ns ( Cm continue | ro | panic )
Action to take on filesystem error
.It Fl -data_replicas Ns = Ns Ar number
Number of data replicas.
With erasure coding enabled, this is currently capped at
.Ar 3
.Pq RAID6 .
.It Fl -metadata_replicas Ns = Ns Ar number
Number of metadata replicas
.It Fl -encoded_extent_max Ns = Ns Ar size
Maximum size of checksummed/compressed extents
.It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
Set metadata checksum type (default:
.Cm crc32c ) .
.It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
Set data checksum type (default:
.Cm crc32c ) .
.It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
Set compression type (default:
.Cm none ) .
.It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )

.It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash )
Hash function for directory entries and xattrs
.It Fl -metadata_target Ns = Ns Ar target
Device or label for metadata writes
.It Fl -foreground_target Ns = Ns Ar target
Device or label for foreground writes
.It Fl -background_target Ns = Ns Ar target
Device or label to move data to in the background
.It Fl -promote_target Ns = Ns Ar target
Device or label to promote data to on read
.It Fl -erasure_code
Enable erasure coding (RAID5/6; data replicas are capped at 3)
.It Fl -inodes_32bit
Constrain inode numbers to 32 bits
.It Fl -shared_inode_numbers
Shared new inode numbers by CPU id
.It Fl -inodes_use_key_cache
Use the btree key cache for the inodes btree
.It Fl -gc_reserve_percent Ns = Ns Ar percentage
Percentage of disk space to reserve for copygc
.It Fl -gc_reserve_bytes Ns = Ns Ar percentage
Amount of disk space to reserve for copygc
.sp
This takes precedence over
.Cm gc_reserve_percent
if set
.It Fl -root_reserve_percent Ns = Ns Ar percentage
Percentage of disk space to reserve for superuser
.It Fl -wide_macs
Store full 128bits of cryptographic MACS, instead of 80
.It Fl -acl
Enable POSIX acls
.It Fl -usrquota
Enable user quotas
.It Fl -grpquota
Enable group quotas
.It Fl -prjquota
Enable project quotas
.It Fl -journal_transaction_names
Log transaction function names in journal
.It Fl -nocow
Nocow mode: Writes will be done in place when possible.
.sp
Snapshots and reflink will still cause writes to be COW.
.sp
This flag implicitly disables data checksumming, compression and
encryption.
.It Fl -replicas Ns = Ns Ar number
Sets both data and metadata replicas.
.It Fl -encrypted
Enable whole filesystem encryption (chacha20/poly1305);
passphrase will be prompted for.
.It Fl -no_passphrase
Store master encryption key unencrypted in superblock
.It Fl L , Fl -fs_label Ns = Ns Ar label
Create the filesystem with the specified
.Ar label
This is the filesystem label, distinct from per-device labels used for target
selection. On a mounted filesystem it can be changed by tools that issue the
standard Linux
.Dv FS_IOC_SETFSLABEL
ioctl.
.It Fl U , Fl -uuid Ns = Ns Ar uuid
Create the filesystem with the specified
.Ar uuid
.It Fl -superblock_size Ns = Ns Ar size

.El
.Pp
Device specific options:
.Bl -tag -width Ds
.It Fl -discard
Enable discard/TRIM support
.It Fl -fs_size Ns = Ns Ar size
Create the filesystem using
.Ar size
bytes on the subsequent device.
.It Fl -bucket Ns = Ns Ar size
Specifies the bucket size;
must be greater than the btree node size
.It Fl -durability Ns = Ns Ar n
Data written to this device will be considered
to have already been replicated
.Ar n
times
.It Fl l , Fl -label
Disk label
.It Fl f , Fl -force
Force the filesystem to be created,
even if the device already contains a filesystem.
.It Fl q , Fl -quiet
Only print errors
.It Fl v , Fl -verbose
Verbose filesystem initialization
.El
.It Nm Ic show-super Oo Ar options Oc Ar device
Dump superblock information to stdout.
.Bl -tag -width Ds
.It Fl f , Fl -fields Ns = Ns Ar fields
List of sections to print
.It Fl l , Fl -layout
Print superblock layout
.El
.It Nm Ic set-fs-option Oo Ar options Oc Ar device
.Bl -tag -width Ds
.It Fl -errors Ns = Ns ( Cm continue | ro | panic )
Action to take on filesystem error
.It Fl -metadata_replicas Ns = Ns Ar number
Number of metadata replicas
.It Fl -data_replicas Ns = Ns Ar number
Number of data replicas.
With erasure coding enabled, this is currently capped at
.Ar 3
.Pq RAID6 .
.It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
Set metadata checksum type (default:
.Cm crc32c ) .
.It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
Set data checksum type (default:
.Cm crc32c ) .
.It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
Set compression type (default:
.Cm none ) .
.It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )

.It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash )
Hash function for directory entries and xattrs
.It Fl -metadata_target Ns = Ns Ar target
Device or label for metadata writes
.It Fl -foreground_target Ns = Ns Ar target
Device or label for foreground writes
.It Fl -background_target Ns = Ns Ar target
Device or label to move data to in the background
.It Fl -promote_target Ns = Ns Ar target
Device or label to promote data to on read
.It Fl -erasure_code
Enable erasure coding (RAID5/6; data replicas are capped at 3)
.It Fl -inodes_32bit
Constrain inode numbers to 32 bits
.It Fl -shared_inode_numbers
Shared new inode numbers by CPU id
.It Fl -inodes_use_key_cache
Use the btree key cache for the inodes btree
.It Fl -gc_reserve_percent Ns = Ns Ar percentage
Percentage of disk space to reserve for copygc
.It Fl -gc_reserve_bytes Ns = Ns Ar percentage
Amount of disk space to reserve for copygc
.sp
This takes precedence over
.Cm gc_reserve_percent
if set
.It Fl -root_reserve_percent Ns = Ns Ar percentage
Percentage of disk space to reserve for superuser
.It Fl -wide_macs
Store full 128bits of cryptographic MACS, instead of 80
.It Fl -acl
Enable POSIX acls
.It Fl -usrquota
Enable user quotas
.It Fl -grpquota
Enable group quotas
.It Fl -prjquota
Enable project quotas
.It Fl -degraded
Allow mounting in degraded mode
.It Fl -very_degraded
Allow mounting in when data will be missing
.It Fl -discard
Enable discard/TRIM support
.It Fl -verbose
Extra debugging information during mount/recovery
.It Fl -journal_flush_delay Ns = Ns Ar ms
Delay in milliseconds before automatic journal commits
.It Fl -journal_flush_disabled
Disable journal flush on sync/fsync
.sp
If enabled, writes can be lost, but only since the
last journal write (default 1 second)
.It Fl -journal_reclaim_delay Ns = Ns Ar ms
Delay in milliseconds before automatic journal reclaim
.It Fl -move_bytes_in_flight Ns = Ns Ar bytes
Maximum Amount of IO to keep in flight by the move path
.It Fl -move_ios_in_flight Ns = Ns Ar number
Maximum number of IOs to keep in flight by the move path
.It Fl -fsck
Run fsck on mount
.It Fl -fix_errors Ns = Ns Ar error
Fix errors during fsck without asking
.It Fl -ratelimit_errors
Ratelimit error messages during fsck
.It Fl -nochanges
Super read only mode - no writes at all will be issued,
even if we have to replay the journal
.It Fl -norecovery
Don't replay the journal
.It Fl -journal_transaction_names
Log transaction function names in journal
.It Fl -noexcl
Don't open device in exclusive mode
.It Fl -direct_io
Use O_DIRECT (userspace only)
.It Fl -sb Ns = Ns Ar offset
Sector offset of superblock
.It Fl -reconstruct_alloc
Reconstruct alloc btree
.It Fl -version_upgrade Ns = Ns ( Cm compatible | incompatible | none )
Set superblock to latest version, allowing any new features
to be used
.Pp
.Cm compatible
is the default: compatible metadata upgrades may be applied automatically, and
the filesystem may still downgrade those compatible version fields when mounted
by an older kernel. Use
.Cm incompatible
only for an intentional one-way metadata upgrade that may prevent mounting with
older kernels, and use
.Cm none
to avoid optional version upgrades.
.It Fl -nocow
Nocow mode: Writes will be done in place when possible.
.sp
Snapshots and reflink will still cause writes to be COW.
.sp
This flag implicitly disables data checksumming, compression and
encryption.
.It Fl -nocow_enabled
Enable nocow mode: enables runtime locking in data
move path needed if nocow will ever be in use
.It Fl -no_data_io
Skip submit_bio() for data reads and writes,
for performance testing purposes
.El
.El
.Sh Mount commands
.Bl -tag -width Ds
.It Nm Ic mount Oo Ar options Oc Ar device mountpoint
The
.Ic mount Fl t Cm bcachefs
path invokes the installed
.Nm mount.bcachefs
helper; this is the same mount path exposed as
.Nm Ic mount .
.Pp
Mount a filesystem. The
.Ar device
can be a device, a colon-separated list of devices, UUID=<UUID>,
OLD_BLKID_UUID=<UUID>, or LABEL=<label>. Use OLD_BLKID_UUID=<UUID> in fstab
entries when systemd consumes UUID=<UUID> before the bcachefs mount helper can
scan all members. The
.Ar mountpoint
is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted
but all steps preceding mounting the filesystem (e.g. asking for passphrase) will still be performed.
.Pp the options are as follows:
.Bl -tag -width Ds
.It Fl o Ar options
Mount options provided as a comma-separated list. See user guide for complete list.
.Bl -tag -width Ds -compact
.It Cm degraded
Allow mounting with missing devices.
Use
.Cm degraded=yes
to allow normal operation with devices missing, and
.Cm degraded=very
only when writes are allowed to continue even if the requested replica count
cannot be maintained.
.Pp
Use degraded read-write mounts for recovery and maintenance when some
members are temporarily unavailable. Do not mount different subsets of the
same filesystem read-write, or mount one subset read-write and later mount a
different subset read-write before the full filesystem has been assembled and
reconciled. That creates split-brain history: each subset can accept writes
that the other subset never saw, and when the members are later brought back
together there may be no single correct value for conflicting files.
.Pp
When in doubt, mount degraded filesystems read-only until the missing members
are available, or assemble the complete filesystem before allowing writes.
.It Cm verbose
Extra debugging info during mount/recovery
.It Cm fsck
Run fsck during mount
.It Cm fix_errors
Fix errors without asking during fsck
.It Cm read_only
Mount in read only mode
.It Cm version_upgrade
.El
.It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask )
Where the password would be loaded from. (default:
.Cm ask ) .
.Bl -tag -width Ds -compact
.It Cm fail
don't ask for password, fail if filesystem is encrypted.
.It Cm wait
wait for password to become available before mounting.
.It Cm ask
prompt the user for password.
.El
.It Fl c , Fl -colorize Ns = Ns ( Cm true | false )
Force color on/off. Default: auto-detect TTY
.It Fl n , Fl -no-mtab
Do not update
.Pa /etc/mtab .
This is accepted for compatibility with
.Xr mount 8 ;
.Nm
uses the mount syscall directly and does not update
.Pa /etc/mtab .
.It Fl f , Fl -fake
Do everything except the actual mount syscall. Accepted for compatibility with
.Xr mount 8 .
.It Fl s , Fl -sloppy
Ignore unrecognized mount options instead of failing. Accepted for
compatibility with
.Xr mount 8 ;
.Nm
already ignores unrecognized options.
.It Fl v
Be verbose. Can be specified more than once.
.El
.El
.Sh Repair commands
.Bl -tag -width Ds
.It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
Check an existing filesystem for errors.
.Bl -tag -width Ds
.It Fl p
Automatic repair (no questions)
.It Fl n
Don't repair, only check for errors
.It Fl y
Assume "yes" to all questions
.It Fl f
Force checking even if filesystem is marked clean
.It Fl r , Fl -ratelimit_errors
Don't display more than 10 errors of a given type
.It Fl R , Fl -reconstruct_alloc
Reconstruct the alloc btree
.It Fl v
Be verbose
.El
.El
.Sh Commands for managing a running filesystem
.Bl -tag -width Ds
.It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
Show disk usage.
.Bl -tag -width Ds
.It Fl h , Fl -human-readable
Print human readable sizes.
.El
.It Nm Ic fs Ic top Oo Ar options Oc Op Ar filesystem
Show live filesystem performance counters.
When stdout is a terminal, this starts an interactive display.
When stdout is not a terminal, it prints one sample and exits.
.Bl -tag -width Ds
.It Fl h , Fl -human-readable
Print human readable sizes.
.It Fl -once
Print one sample and exit; equivalent to specifying a count of 1.
.It Fl n , Fl -count Ns = Ns Ar count
Print
.Ar count
samples and exit.
A count of 0 keeps the interactive display running.
.It Fl d , Fl -delay Ns = Ns Ar seconds
Delay between samples, in seconds.
.El
.El
.Sh Commands for managing devices within a running filesystem
.Bl -tag -width Ds
.It Nm Ic device Ic add Oo Ar options Oc Ar device
Add a device to an existing filesystem.
.Bl -tag -width Ds
.It Fl -fs_size Ns = Ns Ar size
Size of filesystem on device
.It Fl -bucket Ns = Ns Ar size
Set bucket size
.It Fl -discard
Enable discards
.It Fl l , Fl -label Ns = Ns Ar label
Disk label
.It Fl f , Fl -force
Use device even if it appears to already be formatted
.El
.It Nm Ic device Ic remove Oo Ar options Oc Ar device
Remove a device from a filesystem
.Bl -tag -width Ds
.It Fl f , Fl -force
Force removal, even if some data couldn't be migrated
.It Fl F , Fl -force-metadata
Force removal, even if some metadata couldn't be migrated
.El
.It Nm Ic device Ic online Ar device
Re-add a device to a running filesystem
.It Nm Ic device Ic offline Ar device
Take a device offline, without removing it
.Bl -tag -width Ds
.It Fl f , Fl -force
Force, if data redundancy will be degraded
.El
.It Nm Ic device Ic evacuate Ar device
Move data off of a given device
.It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
.Bl -tag -width Ds
.It Ar  new-state Ns = Ns ( Ar rw | ro | evacuating | spare )
New member state. Use
.Ar rw
to cancel an in-progress evacuation and return the device to normal use.
.It Fl f , Fl -force
Force, if data redundancy will be degraded
.It Fl -force-if-data-lost
Force, if data will be lost
.It Fl o , Fl -offline
Set state of an offline device
.El
.It Nm Ic device Ic resize Ar device Op Ar size
Resize filesystem on a device.
Online shrinking is passed to the mounted filesystem kernel; if that kernel
does not support shrinking, the resize ioctl fails.  Offline shrinking is still
unsupported by the bundled userspace filesystem implementation.
.It Nm Ic device Ic resize-journal Ar device Op Ar size
Resize journal on a device
.El
.Sh Commands for managing subvolumes and snapshots
.Bl -tag -width Ds
.It Ic subvolume create Oo Ar options Oc Ar path
Create a new subvolume
.It Ic subvolume delete Oo Ar options Oc Ar path
Delete an existing subvolume
.Pp
Subvolume roots may be renamed or moved as subvolume roots.
Ordinary files and directories cannot be renamed across subvolume boundaries;
copy or reflink data when reorganizing contents between subvolumes.
.It Ic subvolume snapshot Oo Ar options Oc Ar source dest
Create a snapshot of
.Ar source
at
.Ar dest .
If specified,
.Ar source
must be a subvolume;
if not specified the snapshot will be of the subvolume containing
.Ar dest .
.Bl -tag -width Ds
.It Fl r
Make snapshot read-only
.El
.It Ic subvolume list Oo Ar options Oc Ar target
List subvolumes in a mounted filesystem.
.Bl -tag -width Ds
.It Fl -json
Output machine-readable JSON.
.It Fl t , Fl -tree
Show a hierarchical view.
.It Fl R , Fl -recursive
List subvolumes recursively.
.It Fl s , Fl -snapshots
Include snapshot subvolumes.
.It Fl -readonly
Only show read-only subvolumes.
.It Fl -sort Ns = Ns ( Cm name | size | time )
Sort output.
.El
.It Ic subvolume list-snapshots Oo Ar options Oc Ar target
List snapshots and their disk usage in a mounted filesystem.
.Bl -tag -width Ds
.It Fl f , Fl -flat
Show a flat list instead of the default tree.
.It Fl R , Fl -recursive
List snapshot trees for nested subvolumes too.
.It Fl -json
Output machine-readable JSON, including snapshot IDs and parent relationships.
.It Fl -readonly
Only show read-only snapshots in flat view.
.It Fl -sort Ns = Ns ( Cm name | size | time )
Sort flat output.
.El
.El
.Sh Commands for managing filesystem data
.Bl -tag -width Ds
.It Nm Ic scrub Oo Fl m | Fl -metadata Oc Ar filesystem
Verify checksums and correct errors, if possible.
When scrub finds checksum errors, affected file paths are currently reported in
the kernel log.
.Bl -tag -width Ds
.It Fl m , Fl -metadata
Check metadata only
.El
.It Nm Ic reconcile Ic status Op Fl t Ar type Ns Op , Ns Ar ...
.Op Ar filesystem
Show pending background reconciliation work.
Reconcile restores redundancy after a degraded mount or device replacement;
mounted filesystems also queue reconcile work automatically when degraded
extents are detected.
.Bl -tag -width Ds
.It Fl t , Fl -types Ar type Ns Op , Ns Ar ...
Limit output to the selected reconciliation types.
.El
.It Nm Ic reconcile Ic wait Op Fl t Ar type Ns Op , Ns Ar ...
.Op Ar filesystem
Wait for background reconciliation work to finish.
.Bl -tag -width Ds
.It Fl t , Fl -types Ar type Ns Op , Ns Ar ...
Wait only for the selected reconciliation types.
.El
.El
.Sh Commands for encryption
.Bl -tag -width Ds
.It Nm Ic unlock Ar device
Unlock an encrypted filesystem prior to running/mounting.
.Bl -tag -width Ds
.It Fl c
Check if a device is encrypted
.It Fl k Ns = Ns ( Cm session | user | user_session )
Keyring to add to (default:
.Cm user )
.El
.It Nm Ic set-passphrase Ar devices\ ...
Change passphrase on an existing encrypted (unmounted) filesystem.
This rewraps the existing filesystem encryption key; it does not enable
encryption on a filesystem formatted without
.Fl -encrypted .
.It Nm Ic remove-passphrase Ar devices\ ...
Remove passphrase protection from an existing encrypted (unmounted) filesystem.
This stores the existing filesystem encryption key without passphrase
protection; it does not decrypt existing data or disable filesystem encryption.
.El
.Sh Commands for migration
.Bl -tag -width Ds
.It Nm Ic migrate Oo Ar options Oc Ar device
Migrate an existing filesystem to bcachefs
.Bl -tag -width Ds
.It Fl f Ar fs
Root of filesystem to migrate
.It Fl -encrypted
Enable whole filesystem encryption (chacha20/poly1305)
.It Fl -no_passphrase
Store master encryption key unencrypted in superblock
.It Fl F
Force, even if metadata file already exists
.El
.It Nm Ic migrate-superblock Oo Ar options Oc Ar device
Create default superblock after migrating
.Bl -tag -width Ds
.It Fl d Ar device
Device to create superblock for
.It Fl o Ar offset
Offset of existing superblock
.El
.El
.Sh Commands for operating on files in a bcachefs filesystem
.Bl -tag -width Ds
.It Nm Ic set-file-option Oo Ar options Oc Ar [files|folders]\ ...
Set various per-file attributes on files and directories in a bcachefs filesystem.
When applied to directories, attributes are propagated recursively to all files
and subdirectories within.
Changed options take effect immediately for new writes. For existing data,
background reconcile applies changed IO options asynchronously, for example
rewriting existing extents with a new compression algorithm or replica count.
.Bl -tag -width Ds
.It Fl -data_replicas Ns = Ns Ar number
Number of data replicas.
With erasure coding enabled, this is currently capped at
.Ar 3
.Pq RAID6 .
.It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
Set data checksum type (default:
.Cm crc32c ) .
.It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
Set compression type (default:
.Cm none ) .
.It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )

.It Fl -metadata_target Ns = Ns Ar target
Device or label for metadata writes
.It Fl -foreground_target Ns = Ns Ar target
Device or label for foreground writes
.It Fl -background_target Ns = Ns Ar target
Device or label to move data to in the background
.It Fl -promote_target Ns = Ns Ar target
Device or label to promote data to on read
.It Fl -erasure_code
Enable erasure coding (RAID5/6; data replicas are capped at 3)
.It Fl -project

.It Fl -nocow
Nocow mode: Writes will be done in place when possible.
.It Fl -remove-all
Remove all file options from the specified files/directories
.El
.Pp
To remove specific options, use
.Ar --option=-
.Pp
Options can be chained together to perform multiple operations in a single command, for example:
.Dl bcachefs set-file-option --remove-all --compression=lz4 .
.Dl bcachefs set-file-option --compression=- --background_compression=zstd:10 --data_replicas=- file.txt
.It Nm Ic reflink-option-propagate Oo Fl -set-may-update Oc Ar files Ns ...
Propagate each file's current IO options, including compression, checksum,
replicas, and targets, to its extents. This includes indirect, reflinked
extents where the reflink pointer permits option updates.
.Bl -tag -width Ds
.It Fl -set-may-update
Enable option propagation on old reflink pointers that predate the
may-update-options permission flag. This requires administrative privileges and
is only needed once per affected file.
.El
.El
.Sh Commands for debugging
These commands work on offline, unmounted filesystems.
.Bl -tag -width Ds
.It Nm Ic dump Oo Ar options Oc Ar device
Dump filesystem metadata
.Bl -tag -width Ds
.It Fl o Ar output
Required flag: Output qcow2 image(s)
.It Fl f , Fl -force
Force; overwrite when needed
.It Fl -nojournal
Don't dump entire journal, just dirty entries
.El
.It Nm Ic list Oo Ar options Oc Ar devices\ ...
List filesystem metadata to stdout
.Bl -tag -width Ds
.It Fl b ( Cm extents | inodes | dirents | xattrs )
Btree to list from. (default:
.Cm extents)
.It Fl l , Fl -level
Btree depth to descend to. (
.Cm 0
== leaves; default:
.Cm 0)
.It Fl s Ar inode Ns Cm \&: Ns Ar offset
Start position to list from
.It Fl e Ar inode Ns Cm \&: Ns Ar offset
End position
.It Fl m , Fl -mode ( Cm keys | formats | nodes | nodes-ondisk )
(default:
.Cm keys)
.It Fl f
Check (fsck) the filesystem first
.It Fl c , Fl -colorize Ns = Ns ( Cm true | false )
Force color on/off. Default: auto-detect TTY
.It Fl v
Verbose mode
.El
.It Nm Ic list_journal Oo Ar options Oc Ar devices\ ...
.Bl -tag -width Ds
.It Fl a
Read entire journal, not just dirty entries
.It Fl n , Fl -nr-entries Ns = Ns Ar nr
Number of journal entries to print, starting from the most recent
.It Fl s , Fl -seq Ns = Ns Ar seq Ns Oo Ar ..seq Oc
Journal entry sequence or range to print (e.g., 123, 100..200, 100.., ..200)
.It Fl t , Fl -transaction-filter Ns = Ns Ar bbpos
Filter transactions not updating
.Ar bbpos
.It Fl k , Fl -key-filter Ns = Ns Ar btree
Filter keys not updating
.Ar btree
.It Fl v , Fl -verbose
Verbose mode
.El
.El
.Sh FUSE commands
.Bl -tag -width Ds
.It Nm Ic fusemount
Mount a filesystem via FUSE
.El
.Sh Miscellaneous commands
.Bl -tag -width Ds
.It Nm Ic completions Ar shell
Generate shell completions
.It Nm Ic version
Display the version of the invoked bcachefs tool
.El
.Sh EXIT STATUS
.Ex -std