# SYNOPSIS
-bup restore [\--outdir=*outdir*] [-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.
+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
\--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
+
+\--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
a tty, a progress display is printed that shows the
total number of files restored.
-# EXAMPLE
-
+# EXAMPLES
+
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