# SYNOPSIS
-bup restore [\--outdir=*outdir*] [-v] [-q] \<paths...\>;
+bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] [-v] [-q]
+\<paths...\>
# DESCRIPTION
with `bup-save`(1)) to the local filesystem.
The specified *paths* are of the form
-/_branch_/_revision_/_path/to/file_. The components of the
+/_branch_/_revision_/_some/where_. The components of the
path are as follows:
branch
backup on the given branch. You can discover other
revisions using `bup ls /branch`.
-/path/to/file
-: the original absolute filesystem path to the file you
- want to restore. For example, `/etc/passwd`.
+some/where
+: the previously saved path (after any stripping/grafting) that you
+ want to restore. For example, `etc/passwd`.
-Note: if the /path/to/file is a directory, `bup restore`
-will restore that directory as well as recursively
-restoring all its contents.
-
-If /path/to/file is a directory ending in a slash (ie.
-/path/to/dir/), `bup restore` will restore the children of
-that directory directly to the current directory (or the
-`--outdir`). If the directory does *not* end in a slash,
-the children will be restored to a subdirectory of the
-current directory. See the EXAMPLES section to see how
-this works.
+If _some/where_ names a directory, `bup restore` will restore that
+directory and then recursively restore its contents.
+
+If _some/where_ names a directory and ends with a slash (ie.
+path/to/dir/), `bup restore` will restore the children of that
+directory directly to the current directory (or the `--outdir`). If
+_some/where_ does not end in a slash, the children will be restored to
+a subdirectory of the current directory.
+
+If _some/where_ names a directory and ends in '/.' (ie.
+path/to/dir/.), `bup restore` will do exactly what it would have done
+for path/to/dir, and then restore _dir_'s metadata to the current
+directory (or the `--outdir`). See the EXAMPLES section.
Whenever path metadata is available, `bup restore` will attempt to
restore it. When restoring ownership, bup implements tar/rsync-like
example), and as a special case, a uid or gid of 0 will never be
remapped by name.
+Hardlinks will also be restored when possible, but at least currently,
+no links will be made to targets outside the restore tree, and if the
+restore tree spans a different arrangement of filesystems from the
+save tree, some hardlink sets may not be completely restored.
+
+Also note that changing hardlink sets on disk between index and save
+may produce unexpected results. With the current implementation, bup
+will attempt to recreate any given hardlink set as it existed at index
+time, even if all of the files in the set weren't still hardlinked
+(but were otherwise identical) at save time.
+
Note that during the restoration process, access to data within the
restore tree may be more permissive than it was in the original
source. Unless security is irrelevant, you must restore to a private
\--numeric-ids
: restore numeric IDs (user, group, etc.) rather than names.
+\--exclude-rx=*pattern*
+: exclude any path matching *pattern*, which must be a Python
+ regular expression (http://docs.python.org/library/re.html). The
+ pattern will be compared against the full path rooted at the top
+ of the restore tree, without anchoring, so "x/y" will match
+ "ox/yard" or "box/yards". To exclude the contents of /tmp, but
+ not the directory itself, use "^/tmp/.". (can be specified more
+ than once)
+
+ Note that the root of the restore tree (which matches '^/') is the
+ top of the archive tree being restored, and has nothing to do with
+ the filesystem destination. Given "restore ... /foo/latest/etc/",
+ the pattern '^/passwd$' would match if a file named passwd had
+ been saved as '/foo/latest/etc/passwd'.
+
+ Examples:
+
+ * '/foo$' - exclude any file named foo
+ * '/foo/$' - exclude any directory named foo
+ * '/foo/.' - exclude the content of any directory named foo
+ * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
+
-v, \--verbose
: increase log output. Given once, prints every
directory as it is restored; given twice, prints every
$ ls -l passwd
-rw-r--r-- 1 apenwarr apenwarr 1478 2010-09-08 03:06 passwd
+
+Restore etc to test (no trailing slash):
-Restore the whole directory (no trailing slash):
-
- $ bup restore -C test1 /mybackup/latest/etc
+ $ bup restore -C test /mybackup/latest/etc
Restoring: 3, done.
- $ find test1
- test1
- test1/etc
- test1/etc/passwd
- test1/etc/profile
+ $ find test
+ test
+ test/etc
+ test/etc/passwd
+ test/etc/profile
-Restore the whole directory (trailing slash):
+Restore the contents of etc to test (trailing slash):
+
+ $ bup restore -C test /mybackup/latest/etc/
+ Restoring: 2, done.
- $ bup restore -C test2 /mybackup/latest/etc/
+ $ find test
+ test
+ test/passwd
+ test/profile
+
+Restore the contents of etc and etc's metadata to test (trailing
+"/."):
+
+ $ bup restore -C test /mybackup/latest/etc/.
Restoring: 2, done.
- $ find test2
- test2
- test2/passwd
- test2/profile
+ # At this point test and etc's metadata will match.
+ $ find test
+ test
+ test/passwd
+ test/profile
Restore a tree without risk of unauthorized access:
projects / bup.git / blobdiff