From fb9c88fa93fe3c190a3a0b5e4c5edea3233bfcdb 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-image to rst

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

diff --git a/Documentation/btrfs-image.rst b/Documentation/btrfs-image.rst
new file mode 100644
index 00000000..a7b200c1
--- /dev/null
+++ b/Documentation/btrfs-image.rst
@@ -0,0 +1,65 @@
+btrfs-image(8)
+==============
+
+SYNOPSIS
+--------
+**btrfs-image** [options] <source> <target>
+
+DESCRIPTION
+-----------
+
+**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.
+
+In the dump mode, source is the btrfs device/file and target is the output
+file (use *-* for stdout).
+
+In the restore mode (option *-r*), source is the dumped image and target is the btrfs device/file.
+
+OPTIONS
+-------
+
+-r
+        Restore metadump image. By default, this fixes super's chunk tree, by
+        using 1 stripe pointing to primary device, so that file system can be
+        restored by running tree log reply if possible. To restore without
+        changing number of stripes in chunk tree check *-o* option.
+
+-c <value>
+        Compression level (0 ~ 9).
+
+-t <value>
+        Number of threads (1 ~ 32) to be used to process the image dump or restore.
+
+-o
+        Use the old restore method, this does not fixup the chunk tree so the restored
+        file system will not be able to be mounted.
+
+-s
+        Sanitize the file names when generating the image. One -s means just
+        generate random garbage, which means that the directory indexes won't match up
+        since the hashes won't match with the garbage filenames. Using -ss will
+        calculate a collision for the filename so that the hashes match, and if it
+        can't calculate a collision then it will just generate garbage.  The collision
+        calculator is very time and CPU intensive so only use it if you are having
+        problems with your file system tree and need to have it mostly working.
+
+-w
+        Walk all the trees manually and copy any blocks that are referenced. Use this
+        option if your extent tree is corrupted to make sure that all of the metadata is
+        captured.
+
+-m
+        Restore for multiple devices, more than 1 device should be provided.
+
+EXIT STATUS
+-----------
+
+**btrfs-image** will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+SEE ALSO
+--------
+
+``mkfs.btrfs(8)``
diff --git a/Documentation/conf.py b/Documentation/conf.py
index fe754f43..59ec9bce 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -53,4 +53,5 @@ man_pages = [
     ('btrfs-qgroup', 'btrfs-qgroup', 'control the quota group of a btrfs filesystem', '', 8),
     ('btrfs-property', 'btrfs-property', 'get/set/list properties for given filesystem object', '', 8),
     ('btrfs-inspect-internal', 'btrfs-inspect-internal', 'query various internal information', '', 8),
+    ('btrfs-image', 'btrfs-image', 'create/restore an image of the filesystem', '', 8),
 ]
diff --git a/Documentation/man-index.rst b/Documentation/man-index.rst
index 0d8dedd3..5908a01f 100644
--- a/Documentation/man-index.rst
+++ b/Documentation/man-index.rst
@@ -6,6 +6,7 @@ Manual pages
 .. toctree::
    :maxdepth: 1
 
+   btrfs-image
    btrfs-inspect-internal
    btrfs-property
    btrfs-qgroup