# SYNOPSIS
-bup index \<-p|-m|-s|-u\> [-H] [-l] [-x] [\--fake-valid]
-[\--fake-invalid] [\--check] [-f *indexfile*] [\--exclude *path*]
-[\--exclude-from *filename*] [-v] \<filenames...\>
+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...\>
# DESCRIPTION
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/bupindex`.
+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
other purposes (such as speeding up other programs that
need the same information).
+# NOTES
+
+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
+timestamp resolution, and could be traversing multiple filesystems
+during any given run, it always assumes that the resolution may be no
+better than one second.
+
+As a practical matter, this means that index updates are a bit
+imprecise, and so `bup save` may occasionally record filesystem
+changes that you didn't expect. That's because, during an index
+update, if bup encounters a path whose actual timestamps are more
+recent than one second before the update started, bup will set the
+index timestamps for that path (mtime and ctime) to exactly one second
+before the run, -- effectively capping those values.
+
+This ensures that no subsequent changes to those paths can result in
+timestamps that are identical to those in the index. If that were
+possible, bup could overlook the modifications.
+
+You can see the effect of this behavior in this example (assume that
+less than one second elapses between the initial file creation and
+first index run):
+
+ $ touch src/1 src/2
+ # A "sleep 1" here would avoid the unexpected save.
+ $ bup index src
+ $ bup save -n src src # Saves 1 and 2.
+ $ date > src/1
+ $ bup index src
+ $ date > src/2 # Not indexed.
+ $ bup save -n src src # But src/2 is saved anyway.
+
+Strictly speaking, bup should not notice the change to src/2, but it
+does, due to the accommodations described above.
# MODES
: 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/bupindex`.
+ `$BUP_DIR/bupindex`.
\--exclude=*path*
: a path to exclude from the backup (can be used more
: a file that contains exclude paths (can be used more
than once)
+\--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, 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)
+
+ 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
+
+\--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.
+
-v, \--verbose
: increase log output during update (can be used more
than once). With one `-v`, print each directory as it