btrfs-progs: docs: update btrfs-quota manual page
[platform/upstream/btrfs-progs.git] / Documentation / btrfs-restore.asciidoc
index f66d755..41e90e2 100644 (file)
@@ -3,7 +3,7 @@ btrfs-restore(8)
 
 NAME
 ----
-btrfs-restore - try to restore files from a damaged btrfs filesystem(unmounted)
+btrfs-restore - try to restore files from a damaged btrfs filesystem image
 
 SYNOPSIS
 --------
@@ -12,10 +12,22 @@ SYNOPSIS
 DESCRIPTION
 -----------
 *btrfs restore* is used to try to salvage files from a damaged filesystem and
-restore them into <path> or just list the tree roots.
+restore them into <path> or just list the subvolume tree roots. The filesystem
+image is not modified.
 
-Since current `btrfs-check`(8) or `btrfs-rescue`(8) only has very limited usage,
-*btrfs restore* is normally a better choice.
+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: +
@@ -23,52 +35,60 @@ https://btrfs.wiki.kernel.org/index.php/Restore
 
 OPTIONS
 -------
--s::
-get snapshots, btrfs restore skips snapshots in default.
+-s|--snapshots::
+get also snapshots that are skippped by default
 
--x::
-get extended attributes.
+-x|--xattr::
+get extended attributes
 
 -m|--metadata::
-restore owner, mode and times.
+restore owner, mode and times for files and directories
 
--v::
-verbose.
+-S|--symlinks::
+restore symbolic links as well as normal files
 
--i::
-ignore errors.
+-v|--verbose::
+be verbose and print what is being restored
 
--o::
-overwrite directories/files in <path>.
+-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 root tree.
+use <bytenr> to read the root tree
 
 -f <bytenr>::
-only restore files that are under specified root whose root bytenr is <bytenr>.
+only restore files that are under specified subvolume root pointed by <bytenr>
 
--u <mirror>::
-use given superblock mirror identified by <mirror>, it can be 0,1,2.
+-u|--super <mirror>::
+use given superblock mirror identified by <mirror>, it can be 0,1 or 2
 
--r <rootid>::
-only restore files that are under specified root whose objectid is <rootid>.
+-r|--root <rootid>::
+only restore files that are under a specified subvolume whose objectid is <rootid>
 
 -d::
-find dir.
+find directory
 
--l::
-list tree roots.
+-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).
+dry run (only list files that would be recovered)
 
 --path-regex <regex>::
-restore only filenames matching regex, you have to use following syntax (possibly quoted):
+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).
+ignore case (--path-regex only)
 
 EXIT STATUS
 -----------