Add -l and --human-readable options to "bup ls".

[bup.git] / Documentation / bup-restore.md

diff --git a/Documentation/bup-restore.md b/Documentation/bup-restore.md
index e362cdac433f91b8c7203060747a66c4a2adae23..ab98c00b9e402d054f3096efa9c895cad7a796f2 100644 (file)
--- a/Documentation/bup-restore.md
+++ b/Documentation/bup-restore.md
@@ -8,7 +8,8 @@ bup-restore - extract files from a backup set
 
 # SYNOPSIS
 
-bup restore [\--outdir=*outdir*] [-v] [-q] \<paths...\>;
+bup restore [\--outdir=*outdir*] [\--exclude-rx *pattern*] [-v] [-q]
+\<paths...\>
 
 # DESCRIPTION
 
@@ -16,7 +17,7 @@ bup restore [\--outdir=*outdir*] [-v] [-q] \<paths...\>;
 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
@@ -29,21 +30,23 @@ revision
     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
@@ -81,6 +84,28 @@ See the EXAMPLES section for a demonstration.
 \--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
@@ -105,27 +130,39 @@ Restore just one file:
     
     $ 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: