index: Correct inconsitency in documentation of modes

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

diff --git a/Documentation/bup-index.md b/Documentation/bup-index.md
index 4f1bb42e8a200edfb972d823b316d63bea985020..d85d17969b2d82bef736199aeac9fd60e33ffe64 100644 (file)
--- a/Documentation/bup-index.md
+++ b/Documentation/bup-index.md
@@ -8,8 +8,8 @@ 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*]
+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] \<filenames...\>
 
@@ -42,6 +42,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
@@ -101,7 +110,14 @@ does, due to the accommodations described above.
     filename.  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
 
@@ -135,13 +151,6 @@ does, due to the accommodations described above.
 \--fake-invalid
 :   mark specified filenames 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 default index.
 
 -f, \--indexfile=*indexfile*
 :   use a different index filename instead of
@@ -152,7 +161,7 @@ does, due to the accommodations described above.
 
 \--exclude-from=*filename*
 :   read --exclude paths from *filename*, one path per-line (may be
-    repeated).
+    repeated).  Ignore completely empty lines.
 
 \--exclude-rx=*pattern*
 :   exclude any path matching *pattern*, which must be a Python regular
@@ -171,7 +180,7 @@ does, due to the accommodations described above.
 
 \--exclude-rx-from=*filename*
 :   read --exclude-rx patterns from *filename*, one pattern per-line
-    (may be repeated).
+    (may be repeated).  Ignore completely empty lines.
 
 \--no-check-device
 :   don't mark a an entry invalid if the device number (stat(2)
@@ -184,8 +193,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