# 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 not try to restore the user unless running as
-root, and it will fall back to the numeric uid or gid whenever the
-metadata contains a user or group name that doesn't exist on the
-current system. The use of user and group names can be disabled via
-`--numeric-ids` (which can be important when restoring a chroot, for
-example), and as a special case, a uid or gid of 0 will never be
-remapped by name. Additionally, some systems don't allow setting a
-uid/gid that doesn't correspond with a known user/group. On those
-systems, bup will log an error for each relevant path.
+semantics. It will normally prefer user and group names to uids and
+gids when they're available, but it will not try to restore the user
+unless running as root, and it will fall back to the numeric uid or
+gid whenever the metadata contains a user or group name that doesn't
+exist on the current system. The use of user and group names can be
+disabled via `--numeric-ids` (which can be important when restoring a
+chroot, for example), and as a special case, a uid or gid of 0 will
+never be remapped by name. Additionally, some systems don't allow
+setting a uid/gid that doesn't correspond with a known user/group. On
+those systems, bup will log an error for each relevant path.
+
+The `--map-user`, `--map-group`, `--map-uid`, `--map-gid` options may
+be used to adjust the available ownership information before any of
+the rules above are applied, but note that due to those rules,
+`--map-uid` and `--map-gid` will have no effect whenever a path has a
+valid user or group. In those cases, either `--numeric-ids` must be
+specified, or the user or group must be cleared by a suitable
+`--map-user foo=` or `--map-group foo=`.
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
# 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*
+: 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*
+: 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*
+: 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*
+: 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
directory as it is restored; given twice, 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
# rmdir restore-tmp
+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`:
+
+ # bup restore -C dest --numeric-ids --map-uid 1000=1042 /x/latest/y
+ Restoring: 97, done.
# SEE ALSO
projects / bup.git / blobdiff