X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=Documentation%2Fbup-index.md;h=734009556246383894fadb658bed2c3171d98fb5;hb=HEAD;hp=29576e77afa4ebd001e97be8823f06e10f98dfd0;hpb=077e0daec79d9891886d64351930b11e85a58e3b;p=bup.git

diff --git a/Documentation/bup-index.md b/Documentation/bup-index.md
index 29576e7..7340095 100644
--- a/Documentation/bup-index.md
+++ b/Documentation/bup-index.md
@@ -8,17 +8,17 @@ bup-index - print and/or update the bup filesystem index
 
 # SYNOPSIS
 
-bup index \<-p|-m|-s|-u\> [-H] [-l] [-x] [\--fake-valid] [\--no-check-device]
-[\--fake-invalid] [\--check] [\--clear] [-f *indexfile*] [\--exclude *path*]
-[\--exclude-from *filename*] [\--exclude-rx *pattern*] [-v] \<filenames...\>
+bup index \<-p|-m|-s|-u|\--clear|\--check\> [-H] [-l] [-x] [\--fake-valid]
+[\--no-check-device] [\--fake-invalid] [-f *indexfile*] [\--exclude *path*]
+[\--exclude-from *filename*] [\--exclude-rx *pattern*]
+[\--exclude-rx-from *filename*] [-v] \<paths...\>
 
 # DESCRIPTION
 
-`bup index` prints and/or updates the bup filesystem index,
-which is a cache of the filenames, attributes, and sha-1
-hashes of each file and directory in the filesystem.  The
-bup index is similar in function to the `git`(1) index, and
-can be found in `$BUP_DIR/bupindex`.
+`bup index` manipulates the filesystem index, which is a cache of
+absolute paths and their metadata (attributes, SHA-1 hashes, etc.).
+The bup index is similar in function to the `git`(1) index, and the
+default index can be found in `$BUP_DIR/bupindex`.
 
 Creating a backup in bup consists of two steps: updating
 the index with `bup index`, then actually backing up the
@@ -41,6 +41,15 @@ need the same information).
 
 # NOTES
 
+At the moment, bup will ignore Linux attributes (cf. chattr(1) and
+lsattr(1)) on some systems (any big-endian systems where sizeof(long)
+< sizeof(int)).  This is because the Linux kernel and FUSE currently
+disagree over the type of the attr system call arguments, and so on
+big-endian systems there's no way to get the results without the risk
+of stack corruption (http://lwn.net/Articles/575846/).  In these
+situations, bup will print a warning the first time Linux attrs are
+relevant during any index/save/restore operation.
+
 bup makes accommodations for the expected "worst-case" filesystem
 timestamp resolution -- currently one second; examples include VFAT,
 ext2, ext3, small ext4, etc.  Since bup cannot know the filesystem
@@ -79,15 +88,17 @@ does, due to the accommodations described above.
 # MODES
 
 -u, \--update
-:   recursively update the index for the given filenames and
-    their descendants.  One or more filenames must be
-    given.  If no mode option is given, this is the
-    default.
+:   recursively update the index for the given paths and their
+    descendants.  One or more paths must be specified, and if a path
+    ends with a symbolic link, the link itself will be indexed, not
+    the target.  If no mode option is given, `--update` is the
+    default, and paths may be excluded by the `--exclude`,
+    `--exclude-rx`, and `--one-file-system` options.
 
 -p, \--print
-:   print the contents of the index.  If filenames are
+:   print the contents of the index.  If paths are
     given, shows the given entries and their descendants. 
-    If no filenames are given, shows the entries starting
+    If no paths are given, shows the entries starting
     at the current working directory (.).
     
 -m, \--modified
@@ -97,10 +108,17 @@ does, due to the accommodations described above.
 
 -s, \--status
 :   prepend a status code (A, M, D, or space) before each
-    filename.  Implies `-p`.  The codes mean, respectively,
+    path.  Implies `-p`.  The codes mean, respectively,
     that a file is marked in the index as added, modified,
     deleted, or unchanged since the last backup.
-    
+
+\--check
+:   carefully check index file integrity before and after
+    updating.  Mostly useful for automated tests.
+
+\--clear
+:   clear the default index.
+
 
 # OPTIONS
 
@@ -120,38 +138,31 @@ does, due to the accommodations described above.
     format to the `-l` option to `ls`(1).
 
 -x, \--xdev, \--one-file-system
-:   don't cross filesystem boundaries when recursing
-    through the filesystem.  Only applicable if you're
-    using `-u`.
+:   don't cross filesystem boundaries when traversing the
+    filesystem -- though as with tar and rsync, the mount points
+    themselves will still be indexed.  Only applicable if you're using
+    `-u`.
     
 \--fake-valid
-:   mark specified filenames as up-to-date even if they
+:   mark specified paths as up-to-date even if they
     aren't.  This can be useful for testing, or to avoid
     unnecessarily backing up files that you know are
     boring.
     
 \--fake-invalid
-:   mark specified filenames as not up-to-date, forcing the
+:   mark specified paths as not up-to-date, forcing the
     next "bup save" run to re-check their contents.
-    
-\--check
-:   carefully check index file integrity before and after
-    updating.  Mostly useful for automated tests.
-
-\--clear
-:   clear the index.
 
 -f, \--indexfile=*indexfile*
 :   use a different index filename instead of
     `$BUP_DIR/bupindex`.
 
 \--exclude=*path*
-:   a path to exclude from the backup (can be used more
-    than once)
+:   exclude *path* from the backup (may be repeated).
 
 \--exclude-from=*filename*
-:   a file that contains exclude paths (can be used more
-    than once)
+:   read --exclude paths from *filename*, one path per-line (may be
+    repeated).  Ignore completely empty lines.
 
 \--exclude-rx=*pattern*
 :   exclude any path matching *pattern*, which must be a Python regular
@@ -159,7 +170,7 @@ does, due to the accommodations described above.
     will be compared against the full path, 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)
+    "^/tmp/.". (may be repeated)
 
     Examples:
 
@@ -168,10 +179,15 @@ does, due to the accommodations described above.
       * '/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.
+
 \--no-check-device
-:   don't mark a an entry invalid if the device number (stat(2)
-    st_dev) changes.  This can be useful when indexing remote,
-    automounted, or (LVM) snapshot filesystems.
+:   don't mark an entry invalid if the device number (stat(2) st_dev)
+    changes.  This can be useful when indexing remote, automounted, or
+    snapshot filesystems (LVM, Btrfs, etc.), where the device number
+    isn't fixed.
 
 -v, \--verbose
 :   increase log output during update (can be used more
@@ -179,8 +195,7 @@ does, due to the accommodations described above.
     is updated; with two `-v`, print each file too.
 
 
-# EXAMPLE
-
+# EXAMPLES
     bup index -vux /etc /var /usr