From 2c7869dc3af4e8686c674cc34be43abd5e4e1952 Mon Sep 17 00:00:00 2001
From: David Sterba <dsterba@suse.com>
Date: Wed, 27 Oct 2021 00:45:24 +0200
Subject: [PATCH] btrfs-progs: docs: convert btrfs-replace to rst

Signed-off-by: David Sterba <dsterba@suse.com>
---
 Documentation/btrfs-replace.rst | 122 ++++++++++++++++++++++++++++++++
 Documentation/conf.py           |   1 +
 Documentation/man-index.rst     |   1 +
 3 files changed, 124 insertions(+)
 create mode 100644 Documentation/btrfs-replace.rst

diff --git a/Documentation/btrfs-replace.rst b/Documentation/btrfs-replace.rst
new file mode 100644
index 00000000..c50bd6c5
--- /dev/null
+++ b/Documentation/btrfs-replace.rst
@@ -0,0 +1,122 @@
+btrfs-replace(8)
+================
+
+SYNOPSIS
+--------
+
+**btrfs replace** <subcommand> <args>
+
+DESCRIPTION
+-----------
+
+**btrfs replace** is used to replace btrfs managed devices with other device.
+
+SUBCOMMAND
+----------
+
+cancel <mount_point>
+        Cancel a running device replace operation.
+
+start [options] <srcdev>|<devid> <targetdev> <path>
+        Replace device of a btrfs filesystem.
+
+        On a live filesystem, duplicate the data to the target device which
+        is currently stored on the source device.
+        If the source device is not available anymore, or if the -r option is set,
+        the data is built only using the RAID redundancy mechanisms.
+        After completion of the operation, the source device is removed from the
+        filesystem.
+        If the *srcdev* is a numerical value, it is assumed to be the device id
+        of the filesystem which is mounted at *path*, otherwise it is
+        the path to the source device. If the source device is disconnected,
+        from the system, you have to use the devid parameter format.
+        The *targetdev* needs to be same size or larger than the *srcdev*.
+
+        .. note::
+                The filesystem has to be resized to fully take advantage of a
+                larger target device; this can be achieved with
+                `btrfs filesystem resize <devid>:max /path`
+
+        ``Options``
+
+        -r
+                only read from <srcdev> if no other zero-defect mirror exists.
+                (enable this if your drive has lots of read errors, the access would be very
+                slow)
+        -f
+                force using and overwriting <targetdev> even if it looks like
+                it contains a valid btrfs filesystem.
+
+                A valid filesystem is assumed if a btrfs superblock is found which contains a
+                correct checksum. Devices that are currently mounted are
+                never allowed to be used as the <targetdev>.
+        -B
+                no background replace.
+        --enqueue
+                wait if there's another exclusive operation running, otherwise continue
+        -K|--nodiscard
+                Do not perform whole device TRIM operation on devices that are capable of that.
+                This does not affect discard/trim operation when the filesystem is mounted.
+                Please see the mount option 'discard' for that in `btrfs`(5).
+
+status [-1] <mount_point>
+        Print status and progress information of a running device replace operation.
+
+        ``Options``
+
+        -1
+                print once instead of print continuously until the replace
+                operation finishes (or is cancelled)
+
+
+EXAMPLES
+--------
+
+Replacing an online drive with a bigger one
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Given the following filesystem mounted at `/mnt/my-vault`
+
+
+.. code-block:: none
+        Label: 'MyVault'  uuid: ae20903e-b72d-49ba-b944-901fc6d888a1
+                Total devices 2 FS bytes used 1TiB
+                devid    1 size 1TiB used 500.00GiB path /dev/sda
+                devid    2 size 1TiB used 500.00GiB path /dev/sdb
+
+In order to replace */dev/sda* (*devid 1*) with a bigger drive located at
+*/dev/sdc* you would run the following:
+
+.. code-block:: bash
+        btrfs replace start 1 /dev/sdc /mnt/my-vault/
+
+You can monitor progress via:
+
+.. code-block:: bash
+        btrfs replace status /mnt/my-vault/
+
+After the replacement is complete, as per the docs at ``btrfs-filesystem(8)`` in
+order to use the entire storage space of the new drive you need to run:
+
+.. code-block:: bash
+        btrfs filesystem resize 1:max /mnt/my-vault/
+
+EXIT STATUS
+-----------
+
+**btrfs replace** returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+
+**btrfs** is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+
+``mkfs.btrfs(8)``,
+``btrfs-device(8)``,
+``btrfs-filesystem(8)``,
diff --git a/Documentation/conf.py b/Documentation/conf.py
index d581c174..4be00748 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -47,4 +47,5 @@ man_pages = [
     ('btrfs-scrub', 'btrfs-scrub', 'scrub btrfs filesystem, verify block checksums', '', 8),
     ('btrfs-restore', 'btrfs-restore', 'try to restore files from a damaged filesystem image', '', 8),
     ('btrfs-rescue', 'btrfs-rescue', 'recover a damaged btrfs filesystem', '', 8),
+    ('btrfs-replace', 'btrfs-replace', 'replace devices managed by btrfs with other device', '', 8),
 ]
diff --git a/Documentation/man-index.rst b/Documentation/man-index.rst
index fb5f18b8..20c7c817 100644
--- a/Documentation/man-index.rst
+++ b/Documentation/man-index.rst
@@ -6,6 +6,7 @@ Manual pages
 .. toctree::
    :maxdepth: 1
 
+   btrfs-replace
    btrfs-rescue
    btrfs-restore
    btrfs-scrub