# SYNOPSIS
-bup index <-p|-m|-u> [-s] [-H] [-l] [-x] [--fake-valid]
-[--check] [-f *indexfile*] [--exclude *path*]
-[--exclude-from *filename*] [-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] \<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).
-
-# OPTIONS
-
--u, --update
-: (recursively) update the index for the given filenames and
+# 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
+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
+
+-u, \--update
+: recursively update the index for the given filenames and
their descendants. One or more filenames must be
- given.
+ given. If no mode option is given, this is the
+ default.
--p, --print
+-p, \--print
: print the contents of the index. If filenames are
given, shows the given entries and their descendants.
If no filenames are given, shows the entries starting
at the current working directory (.).
--m, --modified
+-m, \--modified
: prints only files which are marked as modified (ie.
changed since the most recent backup) in the index.
Implies `-p`.
--s, --status
+-s, \--status
: prepend a status code (A, M, D, or space) before each
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.
-
--H, --hash
+
+\--check
+: carefully check index file integrity before and after
+ updating. Mostly useful for automated tests.
+
+\--clear
+: clear the default index.
+
+
+# OPTIONS
+
+-H, \--hash
: for each file printed, prepend the most recently
recorded hash code. The hash code is normally
generated by `bup save`. For objects which have not yet
the filesystem no longer matches the recorded hash).
If this is a problem for you, use `--status`.
--l, --long
+-l, \--long
: print more information about each file, in a similar
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`.
+-x, \--xdev, \--one-file-system
+: don't cross filesystem boundaries when recursing through 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
+\--fake-valid
: mark specified filenames 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.
---check
-: carefully check index file integrity before and after
- updating. Mostly useful for automated tests.
+\--fake-invalid
+: mark specified filenames as not up-to-date, forcing the
+ next "bup save" run to re-check their contents.
--f, --indexfile=*indexfile*
+-f, \--indexfile=*indexfile*
: use a different index filename instead of
- `~/.bup/bupindex`.
+ `$BUP_DIR/bupindex`.
+
+\--exclude=*path*
+: exclude *path* from the backup (may be repeated).
---exclude=*path*
-: a path to exclude from the backup (can be used more
- than once)
+\--exclude-from=*filename*
+: read --exclude paths from *filename*, one path per-line (may be
+ repeated). Ignore completely empty lines.
---exclude-from=*filename*
-: 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/.". (may be repeated)
--v, --verbose
+ 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
+
+\--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.
+
+-v, \--verbose
: increase log output during update (can be used more
than once). With one `-v`, print each directory as it
is updated; with two `-v`, print each file too.
-# EXAMPLE
-
+# EXAMPLES
bup index -vux /etc /var /usr
projects / bup.git / blobdiff