1bup-index(1)                                                      bup-index(1)
2
3
4

NAME

6       bup-index - print and/or update the bup filesystem index
7

SYNOPSIS

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

DESCRIPTION

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
20       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
24       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
28       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
33       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

NOTES

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
46       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
53       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
61       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
65       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
69              $ 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
78       Strictly  speaking,  bup  should not notice the change to src/2, but it
79       does, due to the accommodations described above.
80

MODES

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
90       -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
95       -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
99       -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
105       --check
106              carefully  check index file integrity before and after updating.
107              Mostly useful for automated tests.
108
109       --clear
110              clear the default index.
111

OPTIONS

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
123       -l, --long
124              print  more  information about each file, in a similar format to
125              the -l option to ls(1).
126
127       -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
132       --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
137       --fake-invalid
138              mark specified paths as not up-to-date, forcing  the  next  “bup
139              save” run to re-check their contents.
140
141       -f, --indexfile=indexfile
142              use a different index filename instead of $BUP_DIR/bupindex.
143
144       --exclude=path
145              exclude path from the backup (may be repeated).
146
147       --exclude-from=filename
148              read –exclude paths from filename, one path per-line (may be re‐
149              peated).  Ignore completely empty lines.
150
151       --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
159              Examples:
160
161              · `/foo$' - exclude any file named foo
162
163              · `/foo/$' - exclude any directory named foo
164
165              · `/foo/.' - exclude the content of any directory named foo
166
167              · `^/tmp/.'  -  exclude  root-level /tmp's content, but not /tmp
168                itself
169
170       --exclude-rx-from=filename
171              read –exclude-rx patterns from filename,  one  pattern  per-line
172              (may be repeated).  Ignore completely empty lines.
173
174       --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
180       -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

EXAMPLES

186              bup index -vux /etc /var /usr
187

SEE ALSO

189       bup-save(1), bup-drecurse(1), bup-on(1)
190

BUP

192       Part of the bup(1) suite.
193

AUTHORS

195       Avery Pennarun <apenwarr@gmail.com>.
196
197
198
199Bup 0.29.1                        2017-03-26                      bup-index(1)
Impressum