# SYNOPSIS
-bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] [-v] [-q]
-\<paths...\>
+bup restore [-r *host*:[*path*]] [\--outdir=*outdir*] [\--exclude-rx *pattern*]
+
[\--exclude-rx-from *filename*] [-v] [-q] \<paths...\>
# DESCRIPTION
for path/to/dir, and then restore _dir_'s metadata to the current
directory (or the `--outdir`). See the EXAMPLES section.
+As a special case, if _some/where_ names the "latest" symlink,
+e.g. `bup restore /foo/latest`, then bup will act exactly as if the
+save that "latest" points to had been specified, and restore that,
+rather than the "latest" symlink itself.
+
Whenever path metadata is available, `bup restore` will attempt to
restore it. When restoring ownership, bup implements tar/rsync-like
semantics. It will normally prefer user and group names to uids and
# OPTIONS
+-r, \--remote=*host*:*path*
+: restore the backup set from the given remote server. If
+ *path* is omitted, uses the default path on the remote
+ server (you still need to include the ':'). The connection to the
+ remote server is made with SSH. If you'd like to specify which port, user
+ or private key to use for the SSH connection, we recommend you use the
+ `~/.ssh/config` file.
+
-C, \--outdir=*outdir*
: create and change to directory *outdir* before
extracting the files.
* '/foo/.' - exclude the content of any directory named foo
* '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
+\--exclude-rx-from=*filename*
+: read --exclude-rx patterns from *filename*, one pattern per-line
+ (may be repeated). Ignore completely empty lines.
+
+\--sparse
+: write output data sparsely when reasonable. Currently, reasonable
+ just means "at least whenever there are 512 or more consecutive
+ zeroes".
+
\--map-user *old*=*new*
-: restore *old* user as *new* user. Specifying "" for *new* will
- clear the user, i.e. `--map-user foo=`.
+: for every path, restore the *old* (saved) user name as *new*.
+ Specifying "" for *new* will clear the user. For example
+ "--map-user foo=" will allow the uid to take effect for any path
+ that originally had a user of "foo", unless countermanded by a
+ subsequent "--map-user foo=..." specification. See DESCRIPTION
+ above for further information.
\--map-group *old*=*new*
-: restore *old* group as *new* group. Specifying "" for *new* will
- clear the group, i.e. `--map-user foo=`.
+: for every path, restore the *old* (saved) group name as *new*.
+ Specifying "" for *new* will clear the group. For example
+ "--map-group foo=" will allow the gid to take effect for any path
+ that originally had a group of "foo", unless countermanded by a
+ subsequent "--map-group foo=..." specification. See DESCRIPTION
+ above for further information.
\--map-uid *old*=*new*
-: restore *old* uid as *new* uid.
+: for every path, restore the *old* (saved) uid as *new*, unless
+ countermanded by a subsequent "--map-uid *old*=..." option. Note
+ that the uid will only be relevant for paths with no user. See
+ DESCRIPTION above for further information.
\--map-gid *old*=*new*
-: restore *old* gid as *new* gid.
+: for every path, restore the *old* (saved) gid as *new*, unless
+ countermanded by a subsequent "--map-gid *old*=..." option. Note
+ that the gid will only be relevant for paths with no user. See
+ DESCRIPTION above for further information.
-v, \--verbose
: increase log output. Given once, prints every
file and directory.
-q, \--quiet
-: don't show the progress meter. Normally, is stderr is
- a tty, a progress display is printed that shows the
- total number of files restored.
+: suppress output, including the progress meter. Normally, if
+ stderr is a tty, a progress meter displays the total number of
+ files restored.
+
+# EXAMPLES
-# EXAMPLE
-
Create a simple test backup set:
$ bup index -u /etc
Restore a tree, remapping an old user and group to a new user and group:
+ # ls -l /original/y
+ -rw-r----- 1 foo baz 3610 Nov 4 11:31 y
# bup restore -C dest --map-user foo=bar --map-group baz=bax /x/latest/y
Restoring: 42, done.
+ # ls -l dest/y
+ -rw-r----- 1 bar bax 3610 Nov 4 11:31 y
Restore a tree, remapping an old uid to a new uid. Note that the old
user must be erased so that bup won't prefer it over the uid:
+ # ls -l /original/y
+ -rw-r----- 1 foo baz 3610 Nov 4 11:31 y
+ # ls -ln /original/y
+ -rw-r----- 1 1000 1007 3610 Nov 4 11:31 y
# bup restore -C dest --map-user foo= --map-uid 1000=1042 /x/latest/y
Restoring: 97, done.
+ # ls -ln dest/y
+ -rw-r----- 1 1042 1007 3610 Nov 4 11:31 y
An alternate way to do the same by quashing users/groups universally
with `--numeric-ids`:
projects / bup.git / blobdiff