1 % bup-index(1) Bup %BUP_VERSION%
2 % Avery Pennarun <apenwarr@gmail.com>
7 bup-index - print and/or update the bup filesystem index
11 bup index \<-p|-m|-s|-u|\--clear|\--check\> [-H] [-l] [-x] [\--fake-valid]
12 [\--no-check-device] [\--fake-invalid] [-f *indexfile*] [\--exclude *path*]
13 [\--exclude-from *filename*] [\--exclude-rx *pattern*]
14 [\--exclude-rx-from *filename*] [-v] \<paths...\>
18 `bup index` manipulates the filesystem index, which is a cache of
19 absolute paths and their metadata (atttributes, SHA-1 hashes, etc.).
20 The bup index is similar in function to the `git`(1) index, and the
21 default index can be found in `$BUP_DIR/bupindex`.
23 Creating a backup in bup consists of two steps: updating
24 the index with `bup index`, then actually backing up the
25 files (or a subset of the files) with `bup save`. The
26 separation exists for these reasons:
28 1. There is more than one way to generate a list of files
29 that need to be backed up. For example, you might want to
30 use `inotify`(7) or `dnotify`(7).
32 2. Even if you back up files to multiple destinations (for
33 added redundancy), the file names, attributes, and hashes
34 will be the same each time. Thus, you can save the trouble
35 of repeatedly re-generating the list of files for each
38 3. You may want to use the data tracked by bup index for
39 other purposes (such as speeding up other programs that
40 need the same information).
44 At the moment, bup will ignore Linux attributes (cf. chattr(1) and
45 lsattr(1)) on some systems (any big-endian systems where sizeof(long)
46 < sizeof(int)). This is because the Linux kernel and FUSE currently
47 disagree over the type of the attr system call arguments, and so on
48 big-endian systems there's no way to get the results without the risk
49 of stack corruption (http://lwn.net/Articles/575846/). In these
50 situations, bup will print a warning the first time Linux attrs are
51 relevant during any index/save/restore operation.
53 bup makes accommodations for the expected "worst-case" filesystem
54 timestamp resolution -- currently one second; examples include VFAT,
55 ext2, ext3, small ext4, etc. Since bup cannot know the filesystem
56 timestamp resolution, and could be traversing multiple filesystems
57 during any given run, it always assumes that the resolution may be no
58 better than one second.
60 As a practical matter, this means that index updates are a bit
61 imprecise, and so `bup save` may occasionally record filesystem
62 changes that you didn't expect. That's because, during an index
63 update, if bup encounters a path whose actual timestamps are more
64 recent than one second before the update started, bup will set the
65 index timestamps for that path (mtime and ctime) to exactly one second
66 before the run, -- effectively capping those values.
68 This ensures that no subsequent changes to those paths can result in
69 timestamps that are identical to those in the index. If that were
70 possible, bup could overlook the modifications.
72 You can see the effect of this behavior in this example (assume that
73 less than one second elapses between the initial file creation and
77 # A "sleep 1" here would avoid the unexpected save.
79 $ bup save -n src src # Saves 1 and 2.
82 $ date > src/2 # Not indexed.
83 $ bup save -n src src # But src/2 is saved anyway.
85 Strictly speaking, bup should not notice the change to src/2, but it
86 does, due to the accommodations described above.
91 : recursively update the index for the given paths and their
92 descendants. One or more paths must be specified, and if a path
93 ends with a symbolic link, the link itself will be indexed, not
94 the target. If no mode option is given, `--update` is the
95 default, and paths may be excluded by the `--exclude`,
96 `--exclude-rx`, and `--one-file-system` options.
99 : print the contents of the index. If paths are
100 given, shows the given entries and their descendants.
101 If no paths are given, shows the entries starting
102 at the current working directory (.).
105 : prints only files which are marked as modified (ie.
106 changed since the most recent backup) in the index.
110 : prepend a status code (A, M, D, or space) before each
111 path. Implies `-p`. The codes mean, respectively,
112 that a file is marked in the index as added, modified,
113 deleted, or unchanged since the last backup.
116 : carefully check index file integrity before and after
117 updating. Mostly useful for automated tests.
120 : clear the default index.
126 : for each file printed, prepend the most recently
127 recorded hash code. The hash code is normally
128 generated by `bup save`. For objects which have not yet
129 been backed up, the hash code will be
130 0000000000000000000000000000000000000000. Note that
131 the hash code is printed even if the file is known to
132 be modified or deleted in the index (ie. the file on
133 the filesystem no longer matches the recorded hash).
134 If this is a problem for you, use `--status`.
137 : print more information about each file, in a similar
138 format to the `-l` option to `ls`(1).
140 -x, \--xdev, \--one-file-system
141 : don't cross filesystem boundaries when traversing the
142 filesystem -- though as with tar and rsync, the mount points
143 themselves will still be indexed. Only applicable if you're using
147 : mark specified paths as up-to-date even if they
148 aren't. This can be useful for testing, or to avoid
149 unnecessarily backing up files that you know are
153 : mark specified paths as not up-to-date, forcing the
154 next "bup save" run to re-check their contents.
156 -f, \--indexfile=*indexfile*
157 : use a different index filename instead of
161 : exclude *path* from the backup (may be repeated).
163 \--exclude-from=*filename*
164 : read --exclude paths from *filename*, one path per-line (may be
165 repeated). Ignore completely empty lines.
167 \--exclude-rx=*pattern*
168 : exclude any path matching *pattern*, which must be a Python regular
169 expression (http://docs.python.org/library/re.html). The pattern
170 will be compared against the full path, without anchoring, so
171 "x/y" will match "ox/yard" or "box/yards". To exclude the
172 contents of /tmp, but not the directory itself, use
173 "^/tmp/.". (may be repeated)
177 * '/foo$' - exclude any file named foo
178 * '/foo/$' - exclude any directory named foo
179 * '/foo/.' - exclude the content of any directory named foo
180 * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
182 \--exclude-rx-from=*filename*
183 : read --exclude-rx patterns from *filename*, one pattern per-line
184 (may be repeated). Ignore completely empty lines.
187 : don't mark an entry invalid if the device number (stat(2) st_dev)
188 changes. This can be useful when indexing remote, automounted, or
189 snapshot filesystems (LVM, Btrfs, etc.), where the device number
193 : increase log output during update (can be used more
194 than once). With one `-v`, print each directory as it
195 is updated; with two `-v`, print each file too.
199 bup index -vux /etc /var /usr
204 `bup-save`(1), `bup-drecurse`(1), `bup-on`(1)
208 Part of the `bup`(1) suite.