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\> [-H] [-l] [-x] [\--fake-valid] [\--no-check-device]
12 [\--fake-invalid] [\--check] [\--clear] [-f *indexfile*] [\--exclude *path*]
13 [\--exclude-from *filename*] [\--exclude-rx *pattern*] [-v] \<filenames...\>
17 `bup index` prints and/or updates the bup filesystem index,
18 which is a cache of the filenames, attributes, and sha-1
19 hashes of each file and directory in the filesystem. The
20 bup index is similar in function to the `git`(1) index, and
21 can be found in `~/.bup/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 bup makes accommodations for the expected "worst-case" filesystem
45 timestamp resolution -- currently one second; examples include VFAT,
46 ext2, ext3, small ext4, etc. Since bup cannot know the filesystem
47 timestamp resolution, and could be traversing multiple filesystems
48 during any given run, it always assumes that the resolution may be no
49 better than one second.
51 As a practical matter, this means that index updates are a bit
52 imprecise, and so `bup save` may occasionally record filesystem
53 changes that you didn't expect. That's because, during an index
54 update, if bup encounters a path whose actual timestamps are more
55 recent than one second before the update started, bup will set the
56 index timestamps for that path (mtime and ctime) to exactly one second
57 before the run, -- effectively capping those values.
59 This ensures that no subsequent changes to those paths can result in
60 timestamps that are identical to those in the index. If that were
61 possible, bup could overlook the modifications.
63 You can see the effect of this behavior in this example (assume that
64 less than one second elapses between the initial file creation and
68 # A "sleep 1" here would avoid the unexpected save.
70 $ bup save -n src src # Saves 1 and 2.
73 $ date > src/2 # Not indexed.
74 $ bup save -n src src # But src/2 is saved anyway.
76 Strictly speaking, bup should not notice the change to src/2, but it
77 does, due to the accommodations described above.
82 : recursively update the index for the given filenames and
83 their descendants. One or more filenames must be
84 given. If no mode option is given, this is the
88 : print the contents of the index. If filenames are
89 given, shows the given entries and their descendants.
90 If no filenames are given, shows the entries starting
91 at the current working directory (.).
94 : prints only files which are marked as modified (ie.
95 changed since the most recent backup) in the index.
99 : prepend a status code (A, M, D, or space) before each
100 filename. Implies `-p`. The codes mean, respectively,
101 that a file is marked in the index as added, modified,
102 deleted, or unchanged since the last backup.
108 : for each file printed, prepend the most recently
109 recorded hash code. The hash code is normally
110 generated by `bup save`. For objects which have not yet
111 been backed up, the hash code will be
112 0000000000000000000000000000000000000000. Note that
113 the hash code is printed even if the file is known to
114 be modified or deleted in the index (ie. the file on
115 the filesystem no longer matches the recorded hash).
116 If this is a problem for you, use `--status`.
119 : print more information about each file, in a similar
120 format to the `-l` option to `ls`(1).
122 -x, \--xdev, \--one-file-system
123 : don't cross filesystem boundaries when recursing
124 through the filesystem. Only applicable if you're
128 : mark specified filenames as up-to-date even if they
129 aren't. This can be useful for testing, or to avoid
130 unnecessarily backing up files that you know are
134 : mark specified filenames as not up-to-date, forcing the
135 next "bup save" run to re-check their contents.
138 : carefully check index file integrity before and after
139 updating. Mostly useful for automated tests.
144 -f, \--indexfile=*indexfile*
145 : use a different index filename instead of
149 : a path to exclude from the backup (can be used more
152 \--exclude-from=*filename*
153 : a file that contains exclude paths (can be used more
156 \--exclude-rx=*pattern*
157 : exclude any path matching *pattern*, which must be a Python regular
158 expression (http://docs.python.org/library/re.html). The pattern
159 will be compared against the full path, without anchoring, so
160 "x/y" will match "ox/yard" or "box/yards". To exclude the
161 contents of /tmp, but not the directory itself, use
162 "^/tmp/.". (can be specified more than once)
166 * '/foo$' - exclude any file named foo
167 * '/foo/$' - exclude any directory named foo
168 * '/foo/.' - exclude the content of any directory named foo
169 * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
172 : don't mark a an entry invalid if the device number (stat(2)
173 st_dev) changes. This can be useful when indexing remote,
174 automounted, or (LVM) snapshot filesystems.
177 : increase log output during update (can be used more
178 than once). With one `-v`, print each directory as it
179 is updated; with two `-v`, print each file too.
184 bup index -vux /etc /var /usr
189 `bup-save`(1), `bup-drecurse`(1), `bup-on`(1)
193 Part of the `bup`(1) suite.