# SYNOPSIS
-bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] [-v] [-q]
-\<paths...\>
+bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*]
+[\--exclude-rx-from *filename*] [-v] [-q] \<paths...\>
# DESCRIPTION
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
* '/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