From 0f4f3b0c729a404f3641ef1020eb0ca85cb28cad 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-restore to rst

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

diff --git a/Documentation/btrfs-restore.rst b/Documentation/btrfs-restore.rst
new file mode 100644
index 00000000..a1f03dfd
--- /dev/null
+++ b/Documentation/btrfs-restore.rst
@@ -0,0 +1,117 @@
+btrfs-restore(8)
+================
+
+SYNOPSIS
+--------
+
+**btrfs restore** [options] <device> <path> | -l <device>
+
+DESCRIPTION
+-----------
+
+**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
+(``btrfs-check(8)`` or ``btrfs-rescue(8)``), **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
+might be incomplete or from older versions if they're available.
+
+There are several options to attempt restoration of various file metadata type.
+You can try a dry run first to see how well the process goes and use further
+options to extend the set of restored metadata.
+
+For images with damaged tree structures, there are several options to point the
+process to some spare copy.
+
+.. note::
+        It is recommended to read the following btrfs wiki page if your data is
+        not salvaged with default option:
+
+        https://btrfs.wiki.kernel.org/index.php/Restore
+
+OPTIONS
+-------
+
+-s|--snapshots
+        get also snapshots that are skipped by default
+
+-x|--xattr
+        get extended attributes
+
+-m|--metadata
+        restore owner, mode and times for files and directories
+
+-S|--symlinks
+        restore symbolic links as well as normal files
+
+-i|--ignore-errors
+        ignore errors during restoration and continue
+
+-o|--overwrite
+        overwrite directories/files in *path*, eg. for repeated runs
+
+-t <bytenr>
+        use *bytenr* to read the root tree
+
+-f <bytenr>
+        only restore files that are under specified subvolume root pointed by *bytenr*
+
+-u|--super <mirror>
+        use given superblock mirror identified by <mirror>, it can be 0,1 or 2
+
+-r|--root <rootid>
+        only restore files that are under a specified subvolume whose objectid is *rootid*
+
+-d
+        find directory
+
+-l|--list-roots
+        list subvolume tree roots, can be used as argument for *-r*
+
+-D|--dry-run
+        dry run (only list files that would be recovered)
+
+--path-regex <regex>
+        restore only filenames matching a regular expression (``regex(7)``)
+        with a mandatory format
+
+        ``^/(|home(|/username(|/Desktop(|/.*))))$``
+
+        The format is not very comfortable and restores all files in the
+        directories in the whole path, so this is not useful for restoring
+        single file in a deep hierarchy.
+
+-c
+        ignore case (*--path-regex* only)
+
+-v|--verbose
+        (deprecated) alias for global *-v* option
+
+``Global options``
+
+-v|--verbose
+        be verbose and print what is being restored
+
+EXIT STATUS
+-----------
+
+**btrfs restore** 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-rescue(8)``,
+``btrfs-check(8)``
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 166a015d..567864b0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -45,4 +45,5 @@ man_pages = [
     ('fsck.btrfs', 'fsck.btrfs', 'do nothing, successfully', '', 8),
     ('btrfs-send', 'btrfs-send', 'generate a stream of changes between two subvolume snapshots', '', 8),
     ('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),
 ]
diff --git a/Documentation/man-index.rst b/Documentation/man-index.rst
index 05636105..2b7fdc42 100644
--- a/Documentation/man-index.rst
+++ b/Documentation/man-index.rst
@@ -6,6 +6,7 @@ Manual pages
 .. toctree::
    :maxdepth: 1
 
+   btrfs-restore
    btrfs-scrub
    btrfs-select-super
    btrfs-send