| 1 |
% bup-index(1) Bup %BUP_VERSION% |
| 2 |
% Avery Pennarun <[email protected]> |
| 3 |
% %BUP_DATE% |
| 4 |
|
| 5 |
# NAME |
| 6 |
|
| 7 |
bup-index - print and/or update the bup filesystem index |
| 8 |
|
| 9 |
# SYNOPSIS |
| 10 |
|
| 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...\> |
| 15 |
|
| 16 |
# DESCRIPTION |
| 17 |
|
| 18 |
`bup index` manipulates the filesystem index, which is a cache of |
| 19 |
absolute paths and their metadata (attributes, 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`. |
| 22 |
|
| 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: |
| 27 |
|
| 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). |
| 31 |
|
| 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 |
| 36 |
backup set. |
| 37 |
|
| 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). |
| 41 |
|
| 42 |
# NOTES |
| 43 |
|
| 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. |
| 52 |
|
| 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. |
| 59 |
|
| 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. |
| 67 |
|
| 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. |
| 71 |
|
| 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 |
| 74 |
first index run): |
| 75 |
|
| 76 |
$ touch src/1 src/2 |
| 77 |
# A "sleep 1" here would avoid the unexpected save. |
| 78 |
$ bup index src |
| 79 |
$ bup save -n src src # Saves 1 and 2. |
| 80 |
$ date > src/1 |
| 81 |
$ bup index src |
| 82 |
$ date > src/2 # Not indexed. |
| 83 |
$ bup save -n src src # But src/2 is saved anyway. |
| 84 |
|
| 85 |
Strictly speaking, bup should not notice the change to src/2, but it |
| 86 |
does, due to the accommodations described above. |
| 87 |
|
| 88 |
# MODES |
| 89 |
|
| 90 |
-u, \--update |
| 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. |
| 97 |
|
| 98 |
-p, \--print |
| 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 (.). |
| 103 |
|
| 104 |
-m, \--modified |
| 105 |
: prints only files which are marked as modified (ie. |
| 106 |
changed since the most recent backup) in the index. |
| 107 |
Implies `-p`. |
| 108 |
|
| 109 |
-s, \--status |
| 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. |
| 114 |
|
| 115 |
\--check |
| 116 |
: carefully check index file integrity before and after |
| 117 |
updating. Mostly useful for automated tests. |
| 118 |
|
| 119 |
\--clear |
| 120 |
: clear the default index. |
| 121 |
|
| 122 |
|
| 123 |
# OPTIONS |
| 124 |
|
| 125 |
-H, \--hash |
| 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`. |
| 135 |
|
| 136 |
-l, \--long |
| 137 |
: print more information about each file, in a similar |
| 138 |
format to the `-l` option to `ls`(1). |
| 139 |
|
| 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 |
| 144 |
`-u`. |
| 145 |
|
| 146 |
\--fake-valid |
| 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 |
| 150 |
boring. |
| 151 |
|
| 152 |
\--fake-invalid |
| 153 |
: mark specified paths as not up-to-date, forcing the |
| 154 |
next "bup save" run to re-check their contents. |
| 155 |
|
| 156 |
-f, \--indexfile=*indexfile* |
| 157 |
: use a different index filename instead of |
| 158 |
`$BUP_DIR/bupindex`. |
| 159 |
|
| 160 |
\--exclude=*path* |
| 161 |
: exclude *path* from the backup (may be repeated). |
| 162 |
|
| 163 |
\--exclude-from=*filename* |
| 164 |
: read --exclude paths from *filename*, one path per-line (may be |
| 165 |
repeated). Ignore completely empty lines. |
| 166 |
|
| 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) |
| 174 |
|
| 175 |
Examples: |
| 176 |
|
| 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 |
| 181 |
|
| 182 |
\--exclude-rx-from=*filename* |
| 183 |
: read --exclude-rx patterns from *filename*, one pattern per-line |
| 184 |
(may be repeated). Ignore completely empty lines. |
| 185 |
|
| 186 |
\--no-check-device |
| 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 |
| 190 |
isn't fixed. |
| 191 |
|
| 192 |
-v, \--verbose |
| 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. |
| 196 |
|
| 197 |
|
| 198 |
# EXAMPLES |
| 199 |
bup index -vux /etc /var /usr |
| 200 |
|
| 201 |
|
| 202 |
# SEE ALSO |
| 203 |
|
| 204 |
`bup-save`(1), `bup-drecurse`(1), `bup-on`(1) |
| 205 |
|
| 206 |
# BUP |
| 207 |
|
| 208 |
Part of the `bup`(1) suite. |