# 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
# 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
# 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
-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
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
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:
* '/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
is updated; with two `-v`, print each file too.
-# EXAMPLE
-
+# EXAMPLES
bup index -vux /etc /var /usr
projects / bup.git / blobdiff