1bup-index(1) bup-index(1)
2
6 bup-index - print and/or update the bup filesystem index
7
9 bup index <-p|-m|-s|-u|--clear|--check> [-H] [-l] [-x] [--fake-valid]
10 [--no-check-device] [--fake-invalid] [-f indexfile] [--exclude path]
11 [--exclude-from filename] [--exclude-rx pattern] [--exclude-rx-from
12 filename] [-v] <paths...>
13
15 bup index manipulates the filesystem index, which is a cache of abso‐
16 lute paths and their metadata (atttributes, SHA-1 hashes, etc.). The
17 bup index is similar in function to the git(1) index, and the default
18 index can be found in $BUP_DIR/bupindex.
19 Creating a backup in bup consists of two steps: updating the index with
21 bup index, then actually backing up the files (or a subset of the
22 files) with bup save. The separation exists for these reasons:
23 1. There is more than one way to generate a list of files that need to
25 be backed up. For example, you might want to use inotify(7) or dno‐
26 tify(7).
27 2. Even if you back up files to multiple destinations (for added redun‐
29 dancy), the file names, attributes, and hashes will be the same each
30 time. Thus, you can save the trouble of repeatedly re-generating
31 the list of files for each backup set.
32 3. You may want to use the data tracked by bup index for other purposes
34 (such as speeding up other programs that need the same information).
35
37 At the moment, bup will ignore Linux attributes (cf. chattr(1) and
38 lsattr(1)) on some systems (any big-endian systems where sizeof(long) <
39 sizeof(int)). This is because the Linux kernel and FUSE currently dis‐
40 agree over the type of the attr system call arguments, and so on
41 big-endian systems there's no way to get the results without the risk
42 of stack corruption (http://lwn.net/Articles/575846/). In these situa‐
43 tions, bup will print a warning the first time Linux attrs are relevant
44 during any index/save/restore operation.
45 bup makes accommodations for the expected “worst-case” filesystem time‐
47 stamp resolution – currently one second; examples include VFAT, ext2,
48 ext3, small ext4, etc. Since bup cannot know the filesystem timestamp
49 resolution, and could be traversing multiple filesystems during any
50 given run, it always assumes that the resolution may be no better than
51 one second.
52 As a practical matter, this means that index updates are a bit impre‐
54 cise, and so bup save may occasionally record filesystem changes that
55 you didn't expect. That's because, during an index update, if bup en‐
56 counters a path whose actual timestamps are more recent than one second
57 before the update started, bup will set the index timestamps for that
58 path (mtime and ctime) to exactly one second before the run, – effec‐
59 tively capping those values.
60 This ensures that no subsequent changes to those paths can result in
62 timestamps that are identical to those in the index. If that were pos‐
63 sible, bup could overlook the modifications.
64 You can see the effect of this behavior in this example (assume that
66 less than one second elapses between the initial file creation and
67 first index run):
68 $ touch src/1 src/2
70 # A "sleep 1" here would avoid the unexpected save.
71 $ bup index src
72 $ bup save -n src src # Saves 1 and 2.
73 $ date > src/1
74 $ bup index src
75 $ date > src/2 # Not indexed.
76 $ bup save -n src src # But src/2 is saved anyway.
77 Strictly speaking, bup should not notice the change to src/2, but it
79 does, due to the accommodations described above.
80
82 -u, --update
83 recursively update the index for the given paths and their de‐
84 scendants. One or more paths must be specified, and if a path
85 ends with a symbolic link, the link itself will be indexed, not
86 the target. If no mode option is given, --update is the de‐
87 fault, and paths may be excluded by the --exclude, --exclude-rx,
88 and --one-file-system options.
89 -p, --print
91 print the contents of the index. If paths are given, shows the
92 given entries and their descendants. If no paths are given,
93 shows the entries starting at the current working directory (.).
94 -m, --modified
96 prints only files which are marked as modified (ie. changed
97 since the most recent backup) in the index. Implies -p.
98 -s, --status
100 prepend a status code (A, M, D, or space) before each path. Im‐
101 plies -p. The codes mean, respectively, that a file is marked
102 in the index as added, modified, deleted, or unchanged since the
103 last backup.
104 --check
106 carefully check index file integrity before and after updating.
107 Mostly useful for automated tests.
108 --clear
110 clear the default index.
111
113 -H, --hash
114 for each file printed, prepend the most recently recorded hash
115 code. The hash code is normally generated by bup save. For ob‐
116 jects which have not yet been backed up, the hash code will be
117 0000000000000000000000000000000000000000. Note that the hash
118 code is printed even if the file is known to be modified or
119 deleted in the index (ie. the file on the filesystem no longer
120 matches the recorded hash). If this is a problem for you, use
121 --status.
122 -l, --long
124 print more information about each file, in a similar format to
125 the -l option to ls(1).
126 -x, --xdev, --one-file-system
128 don't cross filesystem boundaries when traversing the filesystem
129 – though as with tar and rsync, the mount points themselves will
130 still be indexed. Only applicable if you're using -u.
131 --fake-valid
133 mark specified paths as up-to-date even if they aren't. This
134 can be useful for testing, or to avoid unnecessarily backing up
135 files that you know are boring.
136 --fake-invalid
138 mark specified paths as not up-to-date, forcing the next “bup
139 save” run to re-check their contents.
140 -f, --indexfile=indexfile
142 use a different index filename instead of $BUP_DIR/bupindex.
143 --exclude=path
145 exclude path from the backup (may be repeated).
146 --exclude-from=filename
148 read –exclude paths from filename, one path per-line (may be re‐
149 peated). Ignore completely empty lines.
150 --exclude-rx=pattern
152 exclude any path matching pattern, which must be a Python regu‐
153 lar expression (http://docs.python.org/library/re.html). The
154 pattern will be compared against the full path, without anchor‐
155 ing, so “x/y” will match “ox/yard” or “box/yards”. To exclude
156 the contents of /tmp, but not the directory itself, use
157 “^/tmp/.”. (may be repeated)
158 Examples:
160 · `/foo$' - exclude any file named foo
162 · `/foo/$' - exclude any directory named foo
164 · `/foo/.' - exclude the content of any directory named foo
166 · `^/tmp/.' - exclude root-level /tmp's content, but not /tmp
168 itself
169 --exclude-rx-from=filename
171 read –exclude-rx patterns from filename, one pattern per-line
172 (may be repeated). Ignore completely empty lines.
173 --no-check-device
175 don't mark an entry invalid if the device number (stat(2)
176 st_dev) changes. This can be useful when indexing remote, auto‐
177 mounted, or snapshot filesystems (LVM, Btrfs, etc.), where the
178 device number isn't fixed.
179 -v, --verbose
181 increase log output during update (can be used more than once).
182 With one -v, print each directory as it is updated; with two -v,
183 print each file too.
184
186 bup index -vux /etc /var /usr
187
189 bup-save(1), bup-drecurse(1), bup-on(1)
190
192 Part of the bup(1) suite.
193
195 Avery Pennarun <apenwarr@gmail.com>.
196Bup 0.29.1 2017-03-26 bup-index(1)