| 1 |
.\" Man page generated from reStructuredText |
| 2 |
.\" by the Docutils 0.22.4 manpage writer. |
| 3 |
. |
| 4 |
. |
| 5 |
.nr rst2man-indent-level 0 |
| 6 |
. |
| 7 |
.de1 rstReportMargin |
| 8 |
\\$1 \\n[an-margin] |
| 9 |
level \\n[rst2man-indent-level] |
| 10 |
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 11 |
- |
| 12 |
\\n[rst2man-indent0] |
| 13 |
\\n[rst2man-indent1] |
| 14 |
\\n[rst2man-indent2] |
| 15 |
.. |
| 16 |
.de1 INDENT |
| 17 |
.\" .rstReportMargin pre: |
| 18 |
. RS \\$1 |
| 19 |
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| 20 |
. nr rst2man-indent-level +1 |
| 21 |
.\" .rstReportMargin post: |
| 22 |
.. |
| 23 |
.de UNINDENT |
| 24 |
. RE |
| 25 |
.\" indent \\n[an-margin] |
| 26 |
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 27 |
.nr rst2man-indent-level -1 |
| 28 |
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 29 |
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| 30 |
.. |
| 31 |
.TH "BTRFS-RESTORE" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-restore \- try to restore files from a damaged filesystem image |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs restore\fP [options] <device> <path> | \-l <device> |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
\fBbtrfs restore\fP is used to try to salvage files from a damaged filesystem and |
| 40 |
restore them into \fIpath\fP or just list the subvolume tree roots. The filesystem |
| 41 |
image is not modified. |
| 42 |
.sp |
| 43 |
If the filesystem is damaged and cannot be repaired by the other tools |
| 44 |
(btrfs\-check(8) \%<> or btrfs\-rescue(8) \%<>), |
| 45 |
\fBbtrfs restore\fP could be used to |
| 46 |
retrieve file data, as far as the metadata are readable. The checks done by |
| 47 |
restore are less strict and the process is usually able to get far enough to |
| 48 |
retrieve data from the whole filesystem. This comes at a cost that some data |
| 49 |
might be incomplete or from older versions if they\(aqre available. |
| 50 |
.sp |
| 51 |
There are several options to attempt restoration of various file metadata type. |
| 52 |
You can try a dry run first to see how well the process goes and use further |
| 53 |
options to extend the set of restored metadata. |
| 54 |
.sp |
| 55 |
For images with damaged tree structures, there are several options to point the |
| 56 |
process to some spare copy. |
| 57 |
.SH OPTIONS |
| 58 |
.INDENT 0.0 |
| 59 |
.TP |
| 60 |
.B \-s|\-\-snapshots |
| 61 |
get also snapshots that are skipped by default |
| 62 |
.TP |
| 63 |
.B \-x|\-\-xattr |
| 64 |
get extended attributes |
| 65 |
.TP |
| 66 |
.B \-m|\-\-metadata |
| 67 |
restore owner, mode and times for files and directories |
| 68 |
.TP |
| 69 |
.B \-S|\-\-symlinks |
| 70 |
restore symbolic links as well as normal files |
| 71 |
.TP |
| 72 |
.B \-i|\-\-ignore\-errors |
| 73 |
ignore errors during restoration and continue |
| 74 |
.TP |
| 75 |
.B \-o|\-\-overwrite |
| 76 |
overwrite directories/files in \fIpath\fP, e.g. for repeated runs |
| 77 |
.UNINDENT |
| 78 |
.INDENT 0.0 |
| 79 |
.TP |
| 80 |
.BI \-t \ <bytenr> |
| 81 |
use \fIbytenr\fP to read the root tree |
| 82 |
.TP |
| 83 |
.BI \-f \ <bytenr> |
| 84 |
only restore files that are under specified subvolume root pointed by \fIbytenr\fP |
| 85 |
.UNINDENT |
| 86 |
.INDENT 0.0 |
| 87 |
.TP |
| 88 |
.B \-u|\-\-super <mirror> |
| 89 |
use given superblock mirror identified by <mirror>, it can be 0,1 or 2 |
| 90 |
.TP |
| 91 |
.B \-r|\-\-root <rootid> |
| 92 |
only restore files that are under a specified subvolume whose objectid is \fIrootid\fP |
| 93 |
.UNINDENT |
| 94 |
.INDENT 0.0 |
| 95 |
.TP |
| 96 |
.B \-d |
| 97 |
find directory |
| 98 |
.UNINDENT |
| 99 |
.INDENT 0.0 |
| 100 |
.TP |
| 101 |
.B \-l|\-\-list\-roots |
| 102 |
list subvolume tree roots, can be used as argument for \fI\-r\fP |
| 103 |
.TP |
| 104 |
.B \-D|\-\-dry\-run |
| 105 |
dry run (only list files that would be recovered) |
| 106 |
.UNINDENT |
| 107 |
.INDENT 0.0 |
| 108 |
.TP |
| 109 |
.BI \-\-path\-regex \ <regex> |
| 110 |
restore only filenames matching a regular expression (regex(7) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man7/\:regex\:.7\:.html>) |
| 111 |
with a mandatory format |
| 112 |
.sp |
| 113 |
\fB^/(|home(|/username(|/Desktop(|/.*))))$\fP |
| 114 |
.sp |
| 115 |
The format is not very comfortable and restores all files in the |
| 116 |
directories in the whole path, so this is not useful for restoring |
| 117 |
single file in a deep hierarchy. |
| 118 |
.TP |
| 119 |
.B \-c |
| 120 |
ignore case (\fI\-\-path\-regex\fP only) |
| 121 |
.UNINDENT |
| 122 |
.INDENT 0.0 |
| 123 |
.TP |
| 124 |
.B \-v|\-\-verbose |
| 125 |
(deprecated) alias for global \fI\-v\fP option |
| 126 |
.UNINDENT |
| 127 |
.sp |
| 128 |
\fBGlobal options\fP |
| 129 |
.INDENT 0.0 |
| 130 |
.TP |
| 131 |
.B \-v|\-\-verbose |
| 132 |
be verbose and print what is being restored |
| 133 |
.UNINDENT |
| 134 |
.SH EXIT STATUS |
| 135 |
.sp |
| 136 |
\fBbtrfs restore\fP returns a zero exit status if it succeeds. Non zero is |
| 137 |
returned in case of failure. |
| 138 |
.SH AVAILABILITY |
| 139 |
.sp |
| 140 |
\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at |
| 141 |
\%<https://\:btrfs\:.readthedocs\:.io>\&. |
| 142 |
.SH SEE ALSO |
| 143 |
.sp |
| 144 |
btrfs\-check(8) \%<>, |
| 145 |
btrfs\-rescue(8) \%<>, |
| 146 |
mkfs.btrfs(8) \%<> |
| 147 |
.\" End of generated man page. |