c8h4/btrfs-progs
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

btrfs-progs: docs: use command role for programs or command lines

Browse source 
Replace **bold** or ``quoted`` with :command:`line ...` that is supposed
to be used verbatim.

Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba 2023-04-27 01:48:47 +02:00
parent 405f4c73e8
commit 1afe51d22d
37 changed files with 144 additions and 144 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
Documentation/Common-features.rst
View file

@ -20,12 +20,11 @@ fallocate modes
holes, preallocation or zeroing a range
FIEMAP
an ioctl that enumerates file extents, related tool is ``filefrag``
an ioctl that enumerates file extents, related tool is :command:`filefrag`
filesystem label
another filesystem identification, could be used for mount or for better
recognition, can be set or read by an ioctl or by command ``btrfs
filesystem label``
recognition, can be set or read by an ioctl or by command :command:`btrfs filesystem label`
O_TMPFILE
mode of open() syscall that creates a file with no associated directory
@ -36,8 +35,7 @@ O_TMPFILE
xattr, acl
extended attributes (xattr) is a list of *key=value* pairs associated
with a file, usually storing additional metadata related to security,
access control list in particular (ACL) or properties (``btrfs
property``)
access control list in particular (ACL) or properties (:command:`btrfs property`)
cross-rename
mode of *renameat2* syscall that can atomically swap 2 directory

7
Documentation/Custom-ioctls.rst
View file

@ -6,10 +6,9 @@ call interface to let user applications access the advanced features. They're
low level and the following list gives only an overview of the capabilities or
a command if available:
- reverse lookup, from file offset to inode, as command ``btrfs
inspect-internal logical-resolve``
- reverse lookup, from file offset to inode, as command :command:`btrfs inspect-internal logical-resolve`
- resolve inode number to list of names, as command ``btrfs inspect-internal inode-resolve``
- resolve inode number to list of names, as command :command:`btrfs inspect-internal inode-resolve`
- tree search, given a key range and tree id, lookup and return all b-tree items
found in that range, basically all metadata at your hand but you need to know
@ -17,6 +16,6 @@ a command if available:
filesystem metadata
- informative, about devices, space allocation or the whole filesystem, many of
which is also exported in ``/sys/fs/btrfs``
which is also exported in :file:`/sys/fs/btrfs/`
- query/set a subset of features on a mounted filesystem

4
Documentation/Feature-by-version.rst
View file

@ -282,7 +282,7 @@ features see [[Status]] page.
5.0 - metadata uuid
An optional incompat feature to assign a new filesystem UUID without
overwriting all metadata blocks, stored only in superblock, unlike what
``btrfstune -u``
:command:`btrfstune -u`
5.1 - FORGET_DEV ioctl
Unregister devices previously added by the scan ioctl, same effect as
@ -315,7 +315,7 @@ features see [[Status]] page.
5.7 - faster balance cancel
More cancellation points in balance that will shorten the time to stop
processing once ``btrfs balance cancel`` is called.
processing once :command:`btrfs balance cancel` is called.
5.7 - *removed flag BTRFS_SUBVOL_CREATE_ASYNC*
Remove support of flag BTRFS_SUBVOL_CREATE_ASYNC from subvolume creation ioctl.

6
Documentation/Glossary.rst
View file

@ -14,7 +14,7 @@ allocator
balance
An operation that can be done to a btrfs filesystem, for example
through ``btrfs fi balance /path``. A
through :command:`btrfs fi balance /path`. A
balance passes all data in the filesystem through the *allocator*
again. It is primarily intended to rebalance the data in the filesystem
across the *devices* when a device is added or removed. A balance
@ -247,11 +247,11 @@ RAID-10
performance.
reflink
Parameter to ``cp``, allowing it to take advantage of the
Parameter to :command:`cp`, allowing it to take advantage of the
capabilities of *COW*-capable filesystems. Allows for files to be
copied and modified, with only the modifications taking up additional
storage space. May be considered as *snapshots* on a single file rather
than a *subvolume*. Example: ``cp --reflink file1 file2``
than a *subvolume*. Example: :command:`cp --reflink file1 file2`
relocation
The process of moving block groups within the filesystem while

2
Documentation/Inline-files.rst
View file

@ -12,7 +12,7 @@ It can be completely disabled by mounting with ``max_inline=0``. The upper
limit is either the size of b-tree node or the page size of the host.
An inline file can be identified by enumerating the extents, e.g. by the tool
``filefrag``:
:command:`filefrag`:
.. code-block:: bash

2
Documentation/Subpage.rst
View file

@ -10,7 +10,7 @@ pages, like 64KiB on 64bit ARM or PowerPC. This means filesystems created
with 64KiB sector size cannot be mounted on a system with 4KiB page size.
While with subpage support, systems with 64KiB page size can create (still needs
"-s 4k" option for mkfs.btrfs) and mount filesystems with 4KiB sectorsize,
"-s 4k" option for :command:`mkfs.btrfs`) and mount filesystems with 4KiB sectorsize,
allowing us to push 4KiB sectorsize as default sectorsize for all platforms in the
near future.

2
Documentation/Trim.rst
View file

@ -26,7 +26,7 @@ asynchronous
with the rest of the filesystem activity
manually by fstrim
the tool ``fstrim`` starts a trim operation on the whole filesystem, no
the tool :command:`fstrim` starts a trim operation on the whole filesystem, no
mount options need to be specified, so it's up to the filesystem to
traverse the free space and start the trim, this is suitable for running
it as periodic service

4
Documentation/btrfs-check.rst
View file

@ -14,10 +14,10 @@ and attempt to repair it if requested. It is recommended to unmount the
filesystem prior to running the check, but it is possible to start checking a
mounted filesystem (see *--force*).
By default, **btrfs check** will not modify the device but you can reaffirm that
By default, :command:`btrfs check` will not modify the device but you can reaffirm that
by the option *--readonly*.
**btrfsck** is an alias of **btrfs check** command and is now deprecated.
:command:`btrfsck` is an alias of :command:`btrfs check` command and is now deprecated.
.. warning::
Do not use *--repair* unless you are advised to do so by a developer

2
Documentation/btrfs-device.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
The **btrfs device** command group is used to manage devices of the btrfs filesystems.
The :command:`btrfs device` command group is used to manage devices of the btrfs filesystems.
DEVICE MANAGEMENT
-----------------

21
Documentation/btrfs-filesystem.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfs filesystem** is used to perform several whole filesystem level tasks,
:command:`btrfs filesystem` is used to perform several whole filesystem level tasks,
including all the regular filesystem operations like resizing, space stats,
label setting/getting, and defragmentation. There are other whole filesystem
tasks like scrub or balance that are grouped in separate commands.
@ -26,7 +26,7 @@ df [options] <path>
* device size: *1.9TiB*, one device, no RAID
* filesystem size: *1.9TiB*
* created with: **mkfs.btrfs -d single -m single**
* created with: :command:`mkfs.btrfs -d single -m single`
.. code-block:: none
@ -94,7 +94,7 @@ defragment [options] <file>|<dir> [<file>|<dir>...]
.. warning::
Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as
with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up
the reflinks of COW data (for example files copied with **cp --reflink**,
the reflinks of COW data (for example files copied with :command:`cp --reflink`,
snapshots or de-duplicated data).
This may cause considerable increase of space usage depending on the broken up
reflinks.
@ -146,7 +146,7 @@ du [options] <path> [<path>..]
shared) bytes. We also calculate a 'set shared' value which is
described below.
Each argument to **btrfs filesystem du** will have a *set shared* value
Each argument to :command:`btrfs filesystem du` will have a *set shared* value
calculated for it. We define each *set* as those files found by a
recursive search of an argument (recursion descends to subvolumes but not
mount points). The *set shared* value then is a sum of all shared space
@ -197,8 +197,9 @@ mkswapfile [-s size] file
activated swapfile cannot be balanced.
Swapfile creation can be achieved by standalone commands too. Activation
needs to be done by command ``swapon(8)``. See also command ``btrfs
inspect-internal map-swapfile`` and the :doc:`Swapfile feature<Swapfile>` description.
needs to be done by command ``swapon(8)``. See also command
:command:`btrfs inspect-internal map-swapfile`
and the :doc:`Swapfile feature<Swapfile>` description.
.. note::
The command is a simplified version of 'mkswap', if you want to set
@ -223,7 +224,7 @@ resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>
as expected and does not resize the image. This would resize the underlying
filesystem instead.
The *devid* can be found in the output of **btrfs filesystem show** and
The *devid* can be found in the output of :command:`btrfs filesystem show` and
defaults to 1 if not specified.
The *size* parameter specifies the new size of the filesystem.
If the prefix *+* or *-* is present the size is increased or decreased
@ -291,11 +292,11 @@ show [options] [<path>|<uuid>|<device>|<label>]
sync <path>
Force a sync of the filesystem at *path*, similar to the ``sync(1)`` command. In
addition, it starts cleaning of deleted subvolumes. To wait for the subvolume
deletion to complete use the **btrfs subvolume sync** command.
deletion to complete use the :command:`btrfs subvolume sync` command.
usage [options] <path> [<path>...]
Show detailed information about internal filesystem usage. This is supposed to
replace the **btrfs filesystem df** command in the long run.
replace the :command:`btrfs filesystem df` command in the long run.
The level of detail can differ if the command is run under a regular or the
root user (due to use of restricted ioctl). For both there's a summary section
@ -461,7 +462,7 @@ simply using *max* as size we will achieve that.
.. note::
There are two ways to minimize the filesystem on a given device. The
**btrfs inspect-internal min-dev-size** command, or iteratively shrink in steps.
:command:`btrfs inspect-internal min-dev-size` command, or iteratively shrink in steps.
EXIT STATUS
-----------

2
Documentation/btrfs-image.rst
View file

@ -8,7 +8,7 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfs-image** is used to create an image of a btrfs filesystem.
:command:`btrfs-image` is used to create an image of a btrfs filesystem.
All data will be zeroed, but metadata and the like is preserved.
Mainly used for debugging purposes.

4
Documentation/btrfs-inspect-internal.rst
View file

@ -170,11 +170,11 @@ map-swapfile [options] <file>
Find device-specific physical offset of *file* that can be used for
hibernation. Also verify that the *file* is suitable as a swapfile.
See also command ``btrfs filesystem mkswapfile`` and the
See also command :command:`btrfs filesystem mkswapfile` and the
:doc:`Swapfile feature<Swapfile>` description.
.. note::
Do not use ``filefrag`` or *FIEMAP* ioctl values reported as
Do not use :command:`filefrag` or *FIEMAP* ioctl values reported as
physical, this is different due to internal filesystem mappings.
The hibernation expects offset relative to the physical block device.

30
Documentation/btrfs-man5.rst
View file

@ -44,8 +44,9 @@ at mkfs time only
after mkfs, on an unmounted filesystem
Features that may optimize internal structures or add new structures to support
new functionality, see :doc:`btrfstune(8)<btrfstune>`. The command **btrfs inspect-internal
dump-super /dev/sdx** will dump a superblock, you can map the value of
new functionality, see :doc:`btrfstune(8)<btrfstune>`. The command
:command:`btrfs inspect-internal dump-super /dev/sdx`
will dump a superblock, you can map the value of
*incompat_flags* to the features listed below
after mkfs, on a mounted filesystem
@ -76,13 +77,13 @@ compress_lzo
(since: 2.6.38)
the *lzo* compression has been used on the filesystem, either as a mount option
or via **btrfs filesystem defrag**.
or via :command:`btrfs filesystem defrag`.
compress_zstd
(since: 4.14)
the *zstd* compression has been used on the filesystem, either as a mount option
or via **btrfs filesystem defrag**.
or via :command:`btrfs filesystem defrag`.
default_subvol
(since: 2.6.34)
@ -167,7 +168,7 @@ supported_checksums
supported_sectorsizes
(since: 5.13)
list of values that are accepted as sector sizes (**mkfs.btrfs --sectorsize**) by
list of values that are accepted as sector sizes (:command:`mkfs.btrfs --sectorsize`) by
the running kernel
supported_rescue_options
@ -291,7 +292,7 @@ or (since 5.11) by a convenience command
The control device is not strictly required but the device scanning will not
work and a workaround would need to be used to mount a multi-device filesystem.
The mount option *device* can trigger the device scanning during mount, see
also **btrfs device scan**.
also :command:`btrfs device scan`.
FILESYSTEM WITH MULTIPLE PROFILES
@ -299,7 +300,8 @@ FILESYSTEM WITH MULTIPLE PROFILES
It is possible that a btrfs filesystem contains multiple block group profiles
of the same type. This could happen when a profile conversion using balance
filters is interrupted (see :doc:`btrfs-balance(8)<btrfs-balance>`). Some **btrfs** commands perform
filters is interrupted (see :doc:`btrfs-balance(8)<btrfs-balance>`). Some
:command:`btrfs` commands perform
a test to detect this kind of condition and print a warning like this:
.. code-block:: none
@ -308,7 +310,7 @@ a test to detect this kind of condition and print a warning like this:
WARNING: Data: single, raid1
WARNING: Metadata: single, raid1
The corresponding output of **btrfs filesystem df** might look like:
The corresponding output of :command:`btrfs filesystem df` might look like:
.. code-block:: none
@ -349,9 +351,9 @@ satisfied.
Commands that print the warning were chosen so they're brought to user
attention when the filesystem state is being changed in that regard. This is:
**device add**, **device delete**, **balance cancel**, **balance pause**. Commands
that report space usage: **filesystem df**, **device usage**. The command
**filesystem usage** provides a line in the overall summary:
:command:`device add`, :command:`device delete`, :command:`balance cancel`, :command:`balance pause`. Commands
that report space usage: :command:`filesystem df`, :command:`device usage`. The command
:command:`filesystem usage` provides a line in the overall summary:
.. code-block:: none
@ -396,9 +398,9 @@ Missing/incomplete support
^^^^^^^^^^^^^^^^^^^^^^^^^^
When RAID56 is on the same filesystem with different raid profiles, the space
reporting is inaccurate, e.g. **df**, **btrfs filesystem df** or **btrfs filesystem
usage**. When there's only a one profile per block group type (e.g. RAID5 for data)
the reporting is accurate.
reporting is inaccurate, e.g. :command:`df`, :command:`btrfs filesystem df` or
:command:`btrfs filesystem usage`. When there's only a one profile per block
group type (e.g. RAID5 for data) the reporting is accurate.
When scrub is started on a RAID56 filesystem, it's started on all devices that
degrade the performance. The workaround is to start it on each device

4
Documentation/btrfs-qgroup.rst
View file

@ -12,7 +12,7 @@ DESCRIPTION
**btrfs qgroup** is used to control quota group (qgroup) of a btrfs filesystem.
.. note::
To use qgroup you need to enable quota first using **btrfs quota enable**
To use qgroup you need to enable quota first using :command:`btrfs quota enable`
command.
.. warning::
@ -34,7 +34,7 @@ exclusive limit.
The qgroup identifiers conform to *level/id* where level 0 is reserved to the
qgroups associated with subvolumes. Such qgroups are created automatically.
The qgroup hierarchy is built by commands **create** and **assign**.
The qgroup hierarchy is built by commands :command:`create` and :command:`assign`.
.. note::
If the qgroup of a subvolume is destroyed, quota about the subvolume will

2
Documentation/btrfs-quota.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
The commands under **btrfs quota** are used to affect the global status of quotas
The commands under :command:`btrfs quota` are used to affect the global status of quotas
of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
:doc:`btrfs-qgroup(8)<btrfs-qgroup>`.

8
Documentation/btrfs-receive.rst
View file

@ -14,13 +14,13 @@ DESCRIPTION
-----------
Receive a stream of changes and replicate one or more subvolumes that were
previously generated by **btrfs send**. The received subvolumes are stored to
previously generated by :command:`btrfs send`. The received subvolumes are stored to
*path*, unless *--dump* option is given.
If *--dump* option is specified, **btrfs receive** will only do the validation of
If *--dump* option is specified, :command:`btrfs receive` will only do the validation of
the stream, and print the stream metadata, one operation per line.
**btrfs receive** will fail in the following cases:
:command:`btrfs receive` will fail in the following cases:
1. receiving subvolume already exists
@ -84,7 +84,7 @@ A subvolume is made read-only after the receiving process finishes successfully
BUGS
----
**btrfs receive** sets the subvolume read-only after it completes
:command:`btrfs receive` sets the subvolume read-only after it completes
successfully. However, while the receive is in progress, users who have
write access to files or directories in the receiving *path* can add,
remove, or modify files, in which case the resulting read-only subvolume

2
Documentation/btrfs-replace.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfs replace** is used to replace btrfs managed devices with other device.
:command:`btrfs replace` is used to replace btrfs managed devices with other device.
SUBCOMMAND
----------

8
Documentation/btrfs-rescue.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfs rescue** is used to try to recover a damaged btrfs filesystem.
:command:`btrfs rescue` is used to try to recover a damaged btrfs filesystem.
SUBCOMMAND
----------
@ -28,7 +28,7 @@ chunk-recover [options] <device>
.. note::
Since **chunk-recover** will scan the whole device, it will be very
Since :command:`chunk-recover` will scan the whole device, it will be very
slow especially executed on a large device.
fix-device-size <device>
@ -86,7 +86,7 @@ zero-log <device>
(default commit period) or less if the commit was implied by
other filesystem activity.
One can determine whether **zero-log** is needed according to the kernel
One can determine whether :command:`zero-log` is needed according to the kernel
backtrace:
.. code-block:: none
@ -99,7 +99,7 @@ zero-log <device>
? btree_read_extent_buffer_pages+0x76/0xbc [btrfs]
? open_ctree+0xff6/0x132c [btrfs]
If the errors are like above, then **zero-log** should be used to clear
If the errors are like above, then :command:`zero-log` should be used to clear
the log and the filesystem may be mounted normally again. The keywords to look
for are 'open_ctree' which says that it's during mount and function names
that contain *replay*, *recover* or *log_tree*.

5
Documentation/btrfs-restore.rst
View file

@ -9,12 +9,13 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfs restore** is used to try to salvage files from a damaged filesystem and
:command:`btrfs restore` is used to try to salvage files from a damaged filesystem and
restore them into *path* or just list the subvolume tree roots. The filesystem
image is not modified.
If the filesystem is damaged and cannot be repaired by the other tools
(:doc:`btrfs-check(8)<btrfs-check>` or :doc:`btrfs-rescue(8)<btrfs-rescue>`), **btrfs restore** could be used to
(:doc:`btrfs-check(8)<btrfs-check>` or :doc:`btrfs-rescue(8)<btrfs-rescue>`),
:command:`btrfs restore` could be used to
retrieve file data, as far as the metadata are readable. The checks done by
restore are less strict and the process is usually able to get far enough to
retrieve data from the whole filesystem. This comes at a cost that some data

6
Documentation/btrfs-scrub.rst
View file

@ -19,8 +19,8 @@ cancel <path>|<device>
*device*, cancel it.
If a *device* is specified, the corresponding filesystem is found and
**btrfs scrub cancel** behaves as if it was called on that filesystem.
The progress is saved in the status file so **btrfs scrub resume** can
:command:`btrfs scrub cancel` behaves as if it was called on that filesystem.
The progress is saved in the status file so :command:`btrfs scrub resume` can
continue from the last position.
resume [-BdqrR] <path>|<device>
@ -32,7 +32,7 @@ resume [-BdqrR] <path>|<device>
``Options``
see **scrub start**.
see :command:`scrub start`.
start [-BdrRf] <path>|<device>
Start a scrub on all devices of the mounted filesystem identified by

4
Documentation/btrfs-select-super.rst
View file

@ -20,9 +20,9 @@ The filesystem specified by *device* must not be mounted.
Prior to overwriting the primary superblock, please make sure that the
backup copies are valid!
To dump a superblock use the **btrfs inspect-internal dump-super** command.
To dump a superblock use the :command:`btrfs inspect-internal dump-super` command.
Then run the check (in the non-repair mode) using the command **btrfs check -s**
Then run the check (in the non-repair mode) using the command :command:`btrfs check -s`
where *-s* specifies the superblock copy to use.
Superblock copies exist in the following offsets on the device:

6
Documentation/btrfs-send.rst
View file

@ -10,8 +10,8 @@ DESCRIPTION
-----------
This command will generate a stream of instructions that describe changes
between two subvolume snapshots. The stream can be consumed by the **btrfs
receive** command to replicate the sent snapshot on a different filesystem.
between two subvolume snapshots. The stream can be consumed by the :command:`btrfs receive`
command to replicate the sent snapshot on a different filesystem.
The command operates in two modes: full and incremental.
All snapshots involved in one send command must be read-only, and this status
@ -29,7 +29,7 @@ amount of information that has to be sent to reconstruct the sent snapshot on a
different filesystem.
The *-p <parent>* option can be omitted when *-c <clone-src>* options are
given, in which case **btrfs send** will determine a suitable parent from among
given, in which case :command:`btrfs send` will determine a suitable parent from among
the clone sources.
You must not specify clone sources unless you guarantee that these snapshots

21
Documentation/btrfs-subvolume.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfs subvolume** is used to create/delete/list/show btrfs subvolumes and
:command:`btrfs subvolume` is used to create/delete/list/show btrfs subvolumes and
snapshots.
.. include:: ch-subvolume-intro.rst
@ -67,12 +67,13 @@ delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid>
If *subvolume* is not a subvolume, btrfs returns an error but continues if
there are more arguments to process.
If *--subvolid* is used, *path* must point to a btrfs filesystem. See ``btrfs
subvolume list`` or ``btrfs inspect-internal rootid`` how to get the subvolume id.
If *--subvolid* is used, *path* must point to a btrfs filesystem. See
:command:`btrfs subvolume list` or :command:`btrfs inspect-internal rootid`
how to get the subvolume id.
The corresponding directory is removed instantly but the data blocks are
removed later in the background. The command returns immediately. See ``btrfs
subvolume sync`` how to wait until the subvolume gets completely removed.
removed later in the background. The command returns immediately. See
:command:`btrfs subvolume sync` how to wait until the subvolume gets completely removed.
The deletion does not involve full transaction commit by default due to
performance reasons. As a consequence, the subvolume may appear again after a
@ -82,9 +83,9 @@ delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid>
Deleting subvolume needs sufficient permissions, by default the owner
cannot delete it unless it's enabled by a mount option
*user_subvol_rm_allowed*, or deletion is run as root.
The default subvolume (see ``btrfs subvolume set-default``) cannot be deleted and
The default subvolume (see :command:`btrfs subvolume set-default`) cannot be deleted and
returns error (EPERM) and this is logged to the system log. A subvolume that's
currently involved in send (see ``btrfs send``) also cannot be deleted until the
currently involved in send (see :command:`btrfs send`) also cannot be deleted until the
send is finished. This is also logged in the system log.
``Options``
@ -107,7 +108,7 @@ find-new <subvolume> <last_gen>
get-default <path>
Get the default subvolume of the filesystem *path*.
The output format is similar to **subvolume list** command.
The output format is similar to :command:`subvolume list` command.
list [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>
List the subvolumes present in the filesystem *path*.
@ -191,8 +192,8 @@ set-default [<subvolume>|<id> <path>]
There are two ways how to specify the subvolume, by *id* or by the *subvolume*
path.
The id can be obtained from **btrfs subvolume list**, **btrfs subvolume show** or
**btrfs inspect-internal rootid**.
The id can be obtained from :command:`btrfs subvolume list`,
:command:`btrfs subvolume show` or :command:`btrfs inspect-internal rootid`.
show [options] <path>
Show more information about a subvolume (UUIDs, generations, times, flags,

22
Documentation/btrfs.rst
View file

@ -9,12 +9,12 @@ SYNOPSIS
DESCRIPTION
-----------
The **btrfs** utility is a toolbox for managing btrfs filesystems. There are
The :command:`btrfs` utility is a toolbox for managing btrfs filesystems. There are
command groups to work with subvolumes, devices, for whole filesystem or other
specific actions. See section *COMMANDS*.
There are also standalone tools for some tasks like **btrfs-convert** or
**btrfstune** that were separate historically and/or haven't been merged to the
There are also standalone tools for some tasks like :command:`btrfs-convert` or
:command:`btrfstune` that were separate historically and/or haven't been merged to the
main utility. See section *STANDALONE TOOLS* for more details.
For other topics (mount options, etc) please refer to the separate manual
@ -27,10 +27,10 @@ Any command name can be shortened so long as the shortened form is unambiguous,
however, it is recommended to use full command names in scripts. All command
groups have their manual page named **btrfs-<group>**.
For example: it is possible to run **btrfs sub snaps** instead of
**btrfs subvolume snapshot**.
But **btrfs file s** is not allowed, because **file s** may be interpreted
both as **filesystem show** and as **filesystem sync**.
For example: it is possible to run :command:`btrfs sub snaps` instead of
:command:`btrfs subvolume snapshot`.
But :command:`btrfs file s` is not allowed, because :command:`file s` may be interpreted
both as :command:`filesystem show` and as :command:`filesystem sync`.
If the command name is ambiguous, the list of conflicting options is
printed.
@ -41,8 +41,8 @@ with the suffix `B` appended.
All numbers will be formatted according to the rules of the `C` locale
(ignoring the shell locale, see `locale(7) <https://man7.org/linux/man-pages/man7/locale.7.html>`_).
For an overview of a given command use **btrfs command --help**
or **btrfs [command...] --help --full** to print all available options.
For an overview of a given command use :command:`btrfs command --help`
or :command:`btrfs [command...] --help --full` to print all available options.
There are global options that are passed between *btrfs* and the *group* name
and affect behaviour not specific to the command, e.g. verbosity or the type
@ -139,7 +139,7 @@ proves to be useful, then the standalone tool is declared obsolete and its
functionality is copied to the main tool. Obsolete tools are removed after a
long (years) depreciation period.
Tools that are still in active use without an equivalent in **btrfs**:
Tools that are still in active use without an equivalent in :command:`btrfs`:
btrfs-convert
in-place conversion from ext2/3/4 filesystems to btrfs
@ -153,7 +153,7 @@ btrfs-find-root
For space-constrained environments, it's possible to build a single binary with
functionality of several standalone tools. This is following the concept of
busybox where the file name selects the functionality. This works for symlinks
or hardlinks. The full list can be obtained by **btrfs help --box**.
or hardlinks. The full list can be obtained by :command:`btrfs help --box`.
EXIT STATUS
-----------

2
Documentation/btrfstune.rst
View file

@ -9,7 +9,7 @@ SYNOPSIS
DESCRIPTION
-----------
**btrfstune** can be used to enable, disable, or set various filesystem
:command:`btrfstune` can be used to enable, disable, or set various filesystem
parameters. The filesystem must be unmounted.
The common use case is to enable features that were not enabled at mkfs time.

2
Documentation/ch-balance-filters.rst
View file

@ -25,7 +25,7 @@ usage=<percent>, usage=<range>
devid=<id>
Balances only block groups which have at least one chunk on the given
device. To list devices with ids use **btrfs filesystem show**.
device. To list devices with ids use :command:`btrfs filesystem show`.
drange=<range>
Balance only block groups which overlap with the given byte range on any

6
Documentation/ch-balance-intro.rst
View file

@ -42,13 +42,13 @@ Compatibility
.. note::
The balance subcommand also exists under the **btrfs filesystem** namespace.
The balance subcommand also exists under the :command:`btrfs filesystem` namespace.
This still works for backward compatibility but is deprecated and should not
be used any more.
.. note::
A short syntax **btrfs balance <path>** works due to backward compatibility
but is deprecated and should not be used any more. Use **btrfs balance start**
A short syntax :command:`btrfs balance <path>` works due to backward compatibility
but is deprecated and should not be used any more. Use :command:`btrfs balance start`
command instead.
Performance implications

10
Documentation/ch-convert-intro.rst
View file

@ -1,4 +1,4 @@
The **btrfs-convert** tool can be used to convert existing source filesystem
The :command:`btrfs-convert` tool can be used to convert existing source filesystem
image to a btrfs filesystem in-place. The original filesystem image is
accessible in subvolume named like *ext2_saved* as file *image*.
@ -15,8 +15,8 @@ of help (option *--help*).
.. warning::
If you are going to perform rollback to the original filesystem, you
should not execute **btrfs balance** command on the converted filesystem. This
will change the extent layout and make **btrfs-convert** unable to rollback.
should not execute :command:`btrfs balance` command on the converted filesystem. This
will change the extent layout and make :command:`btrfs-convert` unable to rollback.
The conversion utilizes free space of the original filesystem. The exact
estimate of the required space cannot be foretold. The final btrfs metadata
@ -30,13 +30,13 @@ free space layout.
Due to different constraints, it is only possible to convert filesystems that
have a supported data block size (i.e. the same that would be valid for
**mkfs.btrfs**). This is typically the system page size (4KiB on x86_64
:command:`mkfs.btrfs`). This is typically the system page size (4KiB on x86_64
machines).
**BEFORE YOU START**
The source filesystem must be clean, e.g. no journal to replay or no repairs
needed. The respective **fsck** utility must be run on the source filesystem prior
needed. The respective :command:`fsck` utility must be run on the source filesystem prior
to conversion. Please refer to the manual pages in case you encounter problems.
For ext2/3/4:

19
Documentation/ch-mount-options.rst
View file

@ -15,7 +15,7 @@ options please refer to ``mount(8)`` manual page. The options are sorted alphabe
Mount options are processed in order, only the last occurrence of an option
takes effect and may disable other options due to constraints (see e.g.
*nodatacow* and *compress*). The output of **mount** command shows which options
*nodatacow* and *compress*). The output of :command:`mount` command shows which options
have been applied.
acl, noacl
@ -43,7 +43,7 @@ autodefrag, noautodefrag
Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or
≥ 3.13.4 will break up the reflinks of COW data (for example files
copied with **cp --reflink**, snapshots or de-duplicated data).
copied with :command:`cp --reflink`, snapshots or de-duplicated data).
This may cause considerable increase of space usage depending on the
broken up reflinks.
@ -95,11 +95,11 @@ clear_cache
For free space cache *v1*, this only clears (and, unless *nospace_cache* is
used, rebuilds) the free space cache for block groups that are modified while
the filesystem is mounted with that option. To actually clear an entire free
space cache *v1*, see ``btrfs check --clear-space-cache v1``.
space cache *v1*, see :command:`btrfs check --clear-space-cache v1`.
For free space cache *v2*, this clears the entire free space cache.
To do so without requiring to mounting the filesystem, see
``btrfs check --clear-space-cache v2``.
:command:`btrfs check --clear-space-cache v2`.
See also: *space_cache*.
@ -218,7 +218,7 @@ discard, discard=sync, discard=async, nodiscard
negligible compared to the previous mode and it's supposed to be the preferred
mode if needed.
If it is not necessary to immediately discard freed blocks, then the ``fstrim``
If it is not necessary to immediately discard freed blocks, then the :command:`fstrim`
tool can be used to discard all free blocks in a batch. Scheduling a TRIM
during a period of low system activity will prevent latent interference with
the performance of other operations. Also, a device may ignore the TRIM command
@ -341,8 +341,8 @@ skip_balance
(since: 3.3, default: off)
Skip automatic resume of an interrupted balance operation. The operation can
later be resumed with **btrfs balance resume**, or the paused state can be
removed with **btrfs balance cancel**. The default behaviour is to resume an
later be resumed with :command:`btrfs balance resume`, or the paused state can be
removed with :command:`btrfs balance cancel`. The default behaviour is to resume an
interrupted balance immediately after a volume is mounted.
space_cache, space_cache=<version>, nospace_cache
@ -409,7 +409,7 @@ subvol=<path>
subvolid=<subvolid>
Mount subvolume specified by a *subvolid* number rather than the toplevel
subvolume. You can use **btrfs subvolume list** of **btrfs subvolume show** to see
subvolume. You can use :command:`btrfs subvolume list` of :command:`btrfs subvolume show` to see
subvolume ID numbers.
This mount option overrides the default subvolume set for the given filesystem.
@ -483,8 +483,7 @@ inode_cache, noinode_cache
.. note::
The functionality has been removed in 5.11, any stale data created by
previous use of the *inode_cache* option can be removed by **btrfs check
--clear-ino-cache**.
previous use of the *inode_cache* option can be removed by :command:`btrfs check --clear-ino-cache`.
NOTES ON GENERIC MOUNT OPTIONS

2
Documentation/ch-quota-intro.rst
View file

@ -51,7 +51,7 @@ level 3. For level 0, the leading '0/' can be omitted.
Qgroups of level 0 get created automatically when a subvolume/snapshot gets
created. The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
is the qgroup for the root subvolume.
For the ``btrfs qgroup`` command, the path to the subvolume can also be used
For the :command:`btrfs qgroup` command, the path to the subvolume can also be used
instead of *0/ID*. For all higher levels, the ID can be chosen freely.
Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy

5
Documentation/ch-scrub-intro.rst
View file

@ -7,7 +7,7 @@ the damaged one is repaired. All copies of the replicated profiles are validated
structural damage in the filesystem. It really only checks checksums of data
and tree blocks, it doesn't ensure the content of tree blocks is valid and
consistent. There's some validation performed when metadata blocks are read
from disk but it's not extensive and cannot substitute full *btrfs check*
from disk but it's not extensive and cannot substitute full :command:`btrfs check`
run.
The user is supposed to run it manually or via a periodic system service. The
@ -24,5 +24,4 @@ same directory.) The status file is updated every 5 seconds. A resumed scrub
will continue from the last saved position.
Scrub can be started only on a mounted filesystem, though it's possible to
scrub only a selected device. See **btrfs scrub start** for more.
scrub only a selected device. See :command:`btrfs scrub start` for more.

10
Documentation/ch-seeding-device.rst
View file

@ -8,8 +8,8 @@ systems, but this became obsolete. There are technologies providing similar
functionality, like *unionmount*, *overlayfs* or *qcow2* image snapshot.
The seeding device starts as a normal filesystem, once the contents is ready,
**btrfstune -S 1** is used to flag it as a seeding device. Mounting such device
will not allow any writes, except adding a new device by **btrfs device add**.
:command:`btrfstune -S 1` is used to flag it as a seeding device. Mounting such device
will not allow any writes, except adding a new device by :command:`btrfs device add`.
Then the filesystem can be remounted as read-write.
Given that the filesystem on the seeding device is always recognized as
@ -18,7 +18,7 @@ same time. The UUID that is normally attached to a device is automatically
changed to a random UUID on each mount.
Once the seeding device is mounted, it needs the writable device. After adding
it, something like **remount -o remount,rw /path** makes the filesystem at
it, something like :command:`remount -o remount,rw /path` makes the filesystem at
*/path* ready for use. The simplest use case is to throw away all changes by
unmounting the filesystem when convenient.
@ -26,7 +26,7 @@ Alternatively, deleting the seeding device from the filesystem can turn it into
a normal filesystem, provided that the writable device can also contain all the
data from the seeding device.
The seeding device flag can be cleared again by **btrfstune -f -S 0**, e.g.
The seeding device flag can be cleared again by :command:`btrfstune -f -S 0`, e.g.
allowing to update with newer data but please note that this will invalidate
all existing filesystems that use this particular seeding device. This works
for some use cases, not for others, and the forcing flag to the command is
@ -74,7 +74,7 @@ A few things to note:
for multiple devices but the *single* profile must be used in order to make
the seeding device deletion work
* block group profiles *single* and *dup* support the use cases above
* the label is copied from the seeding device and can be changed by **btrfs filesystem label**
* the label is copied from the seeding device and can be changed by :command:`btrfs filesystem label`
* each new mount of the seeding device gets a new random UUID
Chained seeding devices

10
Documentation/ch-subvolume-intro.rst
View file

@ -24,7 +24,7 @@ similar to a bind mount, and in fact the subvolume mount does exactly that.
A freshly created filesystem is also a subvolume, called *top-level*,
internally has an id 5. This subvolume cannot be removed or replaced by another
subvolume. This is also the subvolume that will be mounted by default, unless
the default subvolume has been changed (see ``btrfs subvolume set-default``).
the default subvolume has been changed (see :command:`btrfs subvolume set-default`).
A snapshot is a subvolume like any other, with given initial content. By
default, snapshots are created read-write. File modifications in a snapshot
@ -65,13 +65,13 @@ the subvolume on the filesystem that produced the stream. The use case relies
on matching data on both sides. Changing the subvolume to read-write after it
has been received requires to reset the *received_uuid*. As this is a notable
change and could potentially break the incremental send use case, performing
it by **btrfs property set** requires force if that is really desired by user.
it by :command:`btrfs property set` requires force if that is really desired by user.
.. note::
The safety checks have been implemented in 5.14.2, any subvolumes previously
received (with a valid *received_uuid*) and read-write status may exist and
could still lead to problems with send/receive. You can use **btrfs subvolume
show** to identify them. Flipping the flags to read-only and back to
could still lead to problems with send/receive. You can use :command:`btrfs subvolume show`
to identify them. Flipping the flags to read-only and back to
read-write will reset the *received_uuid* manually. There may exist a
convenience tool in the future.
@ -85,7 +85,7 @@ descendants of the toplevel one), or nested.
What should be mentioned early is that a snapshotting is not recursive, so a
subvolume or a snapshot is effectively a barrier and no files in the nested
appear in the snapshot. Instead there's a stub subvolume (also sometimes
**empty subvolume** with the same name as original subvolume, with inode number
:command:`empty subvolume` with the same name as original subvolume, with inode number
2). This can be used intentionally but could be confusing in case of nested
layouts.

12
Documentation/ch-swapfile.rst
View file

@ -68,7 +68,7 @@ Once activated the file will appear in */proc/swaps*:
/path/swapfile file 2097152 0 -2
The swapfile can be created as one-time operation or, once properly created,
activated on each boot by the **swapon -a** command (usually started by the
activated on each boot by the :command:`swapon -a` command (usually started by the
service manager). Add the following entry to */etc/fstab*, assuming the
filesystem that provides the */path* has been already mounted at this point.
Additional mount options relevant for the swapfile can be set too (like
@ -79,7 +79,7 @@ priority, not the BTRFS mount options).
/path/swapfile none swap defaults 0 0
From now on the subvolume with the active swapfile cannot be snapshotted until
the swapfile is deactivated again by ``swapoff``. Then the swapfile is a
the swapfile is deactivated again by :command:`swapoff`. Then the swapfile is a
regular file and the subvolume can be snapshotted again, though this would prevent
another activation any swapfile that has been snapshotted. New swapfiles (not
snapshotted) can be created and activated.
@ -96,14 +96,14 @@ hibernation a resume offset must be written to file */sys/power/resume_offset*
or the kernel command line parameter *resume_offset* must be set.
The value is the physical offset on the device. Note that **this is not the same
value that** ``filefrag`` **prints as physical offset!**
value that** :command:`filefrag` **prints as physical offset!**
Btrfs filesystem uses mapping between logical and physical addresses but here
the physical can still map to one or more device-specific physical block
addresses. It's the device-specific physical offset that is suitable as resume
offset.
Since version 6.1 there's a command ``btrfs inspect-internal map-swapfile`` that will
Since version 6.1 there's a command :command:`btrfs inspect-internal map-swapfile` that will
print the device physical offset and the adjusted value for */sys/power/resume_offset*.
Note that the value is divided by page size, i.e. it's not the offset itself.
@ -129,10 +129,10 @@ Troubleshooting
---------------
If the swapfile activation fails please verify that you followed all the steps
above or check the system log (e.g. ``dmesg`` or ``journalctl``) for more
above or check the system log (e.g. :command:`dmesg` or :command:`journalctl`) for more
information.
Notably, the *swapon* utility exits with a message that does not say what
Notably, the :command:`swapon` utility exits with a message that does not say what
failed:
.. code-block:: none

4
Documentation/ch-volume-management-intro.rst
View file

@ -7,10 +7,10 @@ terminology is widely used in the documentation. See :doc:`mkfs.btrfs(8)<mkfs.b
details and the exact profile capabilities and constraints.
The device management works on a mounted filesystem. Devices can be added,
removed or replaced, by commands provided by ``btrfs device`` and ``btrfs replace``.
removed or replaced, by commands provided by :command:`btrfs device` and :command:`btrfs replace`.
The profiles can be also changed, provided there's enough workspace to do the
conversion, using the ``btrfs balance`` command and namely the filter *convert*.
conversion, using the :command:`btrfs balance` command and namely the filter *convert*.
Type
The block group profile type is the main distinction of the information stored

18
Documentation/mkfs.btrfs.rst
View file

@ -9,12 +9,12 @@ SYNOPSIS
DESCRIPTION
-----------
**mkfs.btrfs** is used to create the btrfs filesystem on a single or multiple
:command:`mkfs.btrfs` is used to create the btrfs filesystem on a single or multiple
devices. The *device* is typically a block device but can be a file-backed image
as well. Multiple devices are grouped by UUID of the filesystem.
Before mounting such filesystem, the kernel module must know all the devices
either via preceding execution of **btrfs device scan** or using the *device*
either via preceding execution of :command:`btrfs device scan` or using the *device*
mount option. See section *MULTIPLE DEVICES* for more details.
The default block group profiles for data and metadata depend on number of
@ -145,7 +145,7 @@ OPTIONS
If the destination block device is a regular file, this option will also
truncate the file to the minimal size. Otherwise it will reduce the filesystem
available space. Extra space will not be usable unless the filesystem is
mounted and resized using **btrfs filesystem resize**.
mounted and resized using :command:`btrfs filesystem resize`.
.. note::
Prior to version 4.14.1, the shrinking was done automatically.
@ -155,7 +155,7 @@ OPTIONS
supported by old kernels. To disable a feature, prefix it with *^*.
See section *FILESYSTEM FEATURES* for more details. To see all available
features that **mkfs.btrfs** supports run:
features that :command:`mkfs.btrfs` supports run:
.. code-block:: bash
@ -163,8 +163,8 @@ OPTIONS
-f|--force
Forcibly overwrite the block devices when an existing filesystem is detected.
By default, **mkfs.btrfs** will utilize *libblkid* to check for any known
filesystem on the devices. Alternatively you can use the **wipefs** utility
By default, :command:`mkfs.btrfs` will utilize *libblkid* to check for any known
filesystem on the devices. Alternatively you can use the :command:`wipefs` utility
to clear the devices.
-q|--quiet
@ -179,7 +179,7 @@ OPTIONS
Increase verbosity level, default is 1.
-V|--version
Print the **mkfs.btrfs** version and exit.
Print the :command:`mkfs.btrfs` version and exit.
--help
Print help.
@ -207,7 +207,7 @@ association of the block devices that are attached to the filesystem UUID.
There is typically no action needed from the user. On a system that utilizes a
udev-like daemon, any new block device is automatically registered. The rules
call **btrfs device scan**.
call :command:`btrfs device scan`.
The same command can be used to trigger the device scanning if the btrfs kernel
module is reloaded (naturally all previous information about the device
@ -359,7 +359,7 @@ There are the following block group types available:
performance will be improved.
*Note 1:* DUP may exist on more than 1 device if it starts on a single device and
another one is added. Since version 4.5.1, **mkfs.btrfs** will let you create DUP
another one is added. Since version 4.5.1, :command:`mkfs.btrfs` will let you create DUP
on multiple devices without restrictions.
*Note 2:* It's not recommended to use 2 devices with RAID5. In that case,

6
Documentation/trouble-index.rst
View file

@ -117,12 +117,12 @@ The full message in system log
This means that conversion will remove a degree of metadata redundancy, for
example when going from profile *RAID1* or *dup* to *single*. The force
parameter to ``btrfs balance start -f`` is needed.
parameter to :command:`btrfs balance start -f` is needed.
How to clean old super block
----------------------------
The preferred way is to use the ``wipefs`` utility that is part of the
The preferred way is to use the :command:`wipefs` utility that is part of the
*util-linux* package. Running the command with the device will not destroy
the data, just list the detected filesystems:
@ -161,7 +161,7 @@ Stale signature on device
Related problem regarding partitioned and unpartitioned device: *Long time ago
I created btrfs on /dev/sda. After some changes btrfs moved to /dev/sda1.*
Use ``wipefs -o 0x10040`` (i.e. with the offset of the btrfs signature), it
Use :command:`wipefs -o 0x10040` (i.e. with the offset of the btrfs signature), it
won't touch the partition table.
Manual deletion of super block signature