'\" t
.\"     Title: btrfs-restore
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/05/2021
.\"    Manual: Btrfs Manual
.\"    Source: Btrfs v5.10.1
.\"  Language: English
.\"
.TH "BTRFS\-RESTORE" "8" "02/05/2021" "Btrfs v5\&.10\&.1" "Btrfs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
btrfs-restore \- try to restore files from a damaged btrfs filesystem image
.SH "SYNOPSIS"
.sp
\fBbtrfs restore\fR [options] \fI<device>\fR \fI<path>\fR | \-l \fI<device>\fR
.SH "DESCRIPTION"
.sp
\fBbtrfs restore\fR is used to try to salvage files from a damaged filesystem and restore them into \fI<path>\fR or just list the subvolume tree roots\&. The filesystem image is not modified\&.
.sp
If the filesystem is damaged and cannot be repaired by the other tools (\fBbtrfs\-check\fR(8) or \fBbtrfs\-rescue\fR(8)), \fBbtrfs restore\fR 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\(cqre available\&.
.sp
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\&.
.sp
For images with damaged tree structures, there are several options to point the process to some spare copy\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
It is recommended to read the following btrfs wiki page if your data is not salvaged with default option: \m[blue]\fBhttps://btrfs\&.wiki\&.kernel\&.org/index\&.php/Restore\fR\m[]
.sp .5v
.RE
.SH "OPTIONS"
.PP
\-s|\-\-snapshots
.RS 4
get also snapshots that are skipped by default
.RE
.PP
\-x|\-\-xattr
.RS 4
get extended attributes
.RE
.PP
\-m|\-\-metadata
.RS 4
restore owner, mode and times for files and directories
.RE
.PP
\-S|\-\-symlinks
.RS 4
restore symbolic links as well as normal files
.RE
.PP
\-i|\-\-ignore\-errors
.RS 4
ignore errors during restoration and continue
.RE
.PP
\-o|\-\-overwrite
.RS 4
overwrite directories/files in
\fI<path>\fR, eg\&. for repeated runs
.RE
.PP
\-t \fI<bytenr>\fR
.RS 4
use
\fI<bytenr>\fR
to read the root tree
.RE
.PP
\-f \fI<bytenr>\fR
.RS 4
only restore files that are under specified subvolume root pointed by
\fI<bytenr>\fR
.RE
.PP
\-u|\-\-super \fI<mirror>\fR
.RS 4
use given superblock mirror identified by
\fI<mirror>\fR, it can be 0,1 or 2
.RE
.PP
\-r|\-\-root \fI<rootid>\fR
.RS 4
only restore files that are under a specified subvolume whose objectid is
\fI<rootid>\fR
.RE
.PP
\-d
.RS 4
find directory
.RE
.PP
\-l|\-\-list\-roots
.RS 4
list subvolume tree roots, can be used as argument for
\fI\-r\fR
.RE
.PP
\-D|\-\-dry\-run
.RS 4
dry run (only list files that would be recovered)
.RE
.PP
\-\-path\-regex \fI<regex>\fR
.RS 4
restore only filenames matching a regular expression (\fBregex\fR(7)) with a mandatory format
.sp
\fB^/(|home(|/username(|/Desktop(|/\&.*))))$\fR
.sp
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\&.
.RE
.PP
\-c
.RS 4
ignore case (\-\-path\-regex only)
.RE
.PP
\-v|\-\-verbose
.RS 4
(deprecated) alias for global
\fI\-v\fR
option
.RE
.sp
\fBGlobal options\fR
.PP
\-v|\-\-verbose
.RS 4
be verbose and print what is being restored
.RE
.SH "EXIT STATUS"
.sp
\fBbtrfs restore\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&.
.SH "AVAILABILITY"
.sp
\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
.SH "SEE ALSO"
.sp
\fBmkfs\&.btrfs\fR(8), \fBbtrfs\-rescue\fR(8), \fBbtrfs\-check\fR(8)