Update base_version to 0.34~ for 0.34 development

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

diff --git a/Documentation/bup-save.md b/Documentation/bup-save.md
index 091618c957192185e10a94a4ce8d4e7116877cf6..7bbe44e38122755f967b759210b4097e813b2773 100644 (file)
--- a/Documentation/bup-save.md
+++ b/Documentation/bup-save.md
@@ -16,11 +16,22 @@ bup save [-r *host*:*path*] \<-t|-c|-n *name*\> [-#] [-f *indexfile*]
 `bup save` saves the contents of the given files or paths
 into a new backup set and optionally names that backup set.
 
+Note that in order to refer to your backup set later (i.e. for
+restoration), you must either specify `--name` (the normal case), or
+record the tree or commit id printed by `--tree` or `--commit`.
+
 Before trying to save files using `bup save`, you should
 first update the index using `bup index`.  The reasons
 for separating the two steps are described in the man page
 for `bup-index`(1).
 
+By default, metadata will be saved for every path, and the metadata
+for any unindexed parent directories of indexed paths will be taken
+directly from the filesystem.  However, if `--strip`, `--strip-path`,
+or `--graft` is specified, metadata will not be saved for the root
+directory (*/*).  See `bup-restore`(1) for more information about the
+handling of metadata.
+
 # OPTIONS
 
 -r, \--remote=*host*:*path*
@@ -54,7 +65,7 @@ for `bup-index`(1).
 
 -f, \--indexfile=*indexfile*
 :   use a different index filename instead of
-    `~/.bup/bupindex`.
+    `$BUP_DIR/bupindex`.
 
 -v, \--verbose
 :   increase verbosity (can be used more than once).  With
@@ -71,7 +82,7 @@ for `bup-index`(1).
     over large ones (like virtual machine images) which
     take longer.  Then you can back up the large files
     less frequently.  Use a suffix like k, M, or G to
-    specify multiples of 1024, 1024*1024, 1024*1024*1024
+    specify multiples of 1024, 1024\*1024, 1024\*1024\*1024
     respectively.
     
 \--bwlimit=*bytes/sec*
@@ -79,30 +90,34 @@ for `bup-index`(1).
     to the server.  This is good for making your backups
     not suck up all your network bandwidth.  Use a suffix
     like k, M, or G to specify multiples of 1024,
-    1024*1024, 1024*1024*1024 respectively.
+    1024\*1024, 1024\*1024\*1024 respectively.
     
 \--strip
 :   strips the path that is given from all files and directories.
     
-    A directory */root/chroot/etc* saved with
-    "bup save -n chroot \--strip /root/chroot" would be saved
-    as */etc*.
+    A directory */root/chroot/etc* saved with "bup save -n chroot
+    \--strip /root/chroot" would be saved as */etc*.  Note that
+    currently, metadata will not be saved for the root directory (*/*)
+    when this option is specified.
     
 \--strip-path=*path-prefix*
 :   strips the given path prefix *path-prefix* from all
     files and directories.
     
-    A directory */root/chroots/webserver* saved with
-    "bup save -n webserver \--strip-path=/root/chroots" would
-    be saved as */webserver/etc*
+    A directory */root/chroot/webserver/etc* saved with "bup save -n
+    webserver \--strip-path=/root/chroot /root/chroot/webserver/etc"
+    would be saved as */webserver/etc*.  Note that currently, metadata
+    will not be saved for the root directory (*/*) when this option is
+    specified.
     
 \--graft=*old_path*=*new_path*
 :   a graft point *old_path*=*new_path* (can be used more than
     once).
 
-    A directory */root/chroot/a/etc* saved with
-    "bup save -n chroots \--graft /root/chroot/a/etc=/chroots/a"
-    would be saved as */chroots/a/etc*
+    A directory */root/chroot/a/etc* saved with "bup save -n chroot
+    \--graft /root/chroot/a=/chroot/a" would be saved as
+    */chroot/a/etc*.  Note that currently, metadata will not be saved
+    for the root directory (*/*) when this option is specified.
 
 -*#*, \--compress=*#*
 :   set the compression level to # (a value from 0-9, where
@@ -110,8 +125,7 @@ for `bup-index`(1).
     is 1 (fast, loose compression)
 
 
-# EXAMPLE
-
+# EXAMPLES
     $ bup index -ux /etc
     Indexing: 1981, done.
 
@@ -121,13 +135,13 @@ for `bup-index`(1).
 
 
 
-    $ ls /home/joe/chroots/httpd
+    $ ls /home/joe/chroot/httpd
     bin var
 
-    $ bup index -ux /home/joe/chroots/httpd
+    $ bup index -ux /home/joe/chroot/httpd
     Indexing: 1337, done.
 
-    $ bup save --strip -n joes-httpd-chroot /home/joe/chroots/httpd
+    $ bup save --strip -n joes-httpd-chroot /home/joe/chroot/httpd
     Reading index: 1337, done.
     Saving: 100.00% (998/998k, 1337/1337 files), done.
 
@@ -136,18 +150,18 @@ for `bup-index`(1).
     var/
 
 
-    $ bup save --strip-prefix=/home/joe/chroots -n joes-chroots \
-         /home/joe/chroots/httpd
+    $ bup save --strip-path=/home/joe/chroot -n joes-chroot \
+         /home/joe/chroot/httpd
     Reading index: 1337, done.
     Saving: 100.00% (998/998k, 1337/1337 files), done.
 
-    $ bup ls joes-chroots/latest/
+    $ bup ls joes-chroot/latest/
     httpd/
 
 
-    $ bup save --graft /home/joe/chroots/httpd=/http-chroot \
+    $ bup save --graft /home/joe/chroot/httpd=/http-chroot \
          -n joe
-         /home/joe/chroots/httpd
+         /home/joe/chroot/httpd
     Reading index: 1337, done.
     Saving: 100.00% (998/998k, 1337/1337 files), done.