Documentation/bup-index.md

   1 % bup-index(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   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\> [-H] [-l] [-x] [\--fake-valid] [\--no-check-device]
  12 [\--fake-invalid] [\--check] [\--clear] [-f *indexfile*] [\--exclude *path*]
  13 [\--exclude-from *filename*] [\--exclude-rx *pattern*]
  14 [\--exclude-rx-from *filename*] [-v] \<filenames...\>
  15
  16 # DESCRIPTION
  17
  18 `bup index` prints and/or updates the bup filesystem index,
  19 which is a cache of the filenames, attributes, and sha-1
  20 hashes of each file and directory in the filesystem.  The
  21 bup index is similar in function to the `git`(1) index, and
  22 can be found in `$BUP_DIR/bupindex`.
  23
  24 Creating a backup in bup consists of two steps: updating
  25 the index with `bup index`, then actually backing up the
  26 files (or a subset of the files) with `bup save`.  The
  27 separation exists for these reasons:
  28
  29 1. There is more than one way to generate a list of files
  30 that need to be backed up.  For example, you might want to
  31 use `inotify`(7) or `dnotify`(7).
  32
  33 2. Even if you back up files to multiple destinations (for
  34 added redundancy), the file names, attributes, and hashes
  35 will be the same each time.  Thus, you can save the trouble
  36 of repeatedly re-generating the list of files for each
  37 backup set.
  38
  39 3. You may want to use the data tracked by bup index for
  40 other purposes (such as speeding up other programs that
  41 need the same information).
  42
  43 # NOTES
  44
  45 bup makes accommodations for the expected "worst-case" filesystem
  46 timestamp resolution -- currently one second; examples include VFAT,
  47 ext2, ext3, small ext4, etc.  Since bup cannot know the filesystem
  48 timestamp resolution, and could be traversing multiple filesystems
  49 during any given run, it always assumes that the resolution may be no
  50 better than one second.
  51
  52 As a practical matter, this means that index updates are a bit
  53 imprecise, and so `bup save` may occasionally record filesystem
  54 changes that you didn't expect.  That's because, during an index
  55 update, if bup encounters a path whose actual timestamps are more
  56 recent than one second before the update started, bup will set the
  57 index timestamps for that path (mtime and ctime) to exactly one second
  58 before the run, -- effectively capping those values.
  59
  60 This ensures that no subsequent changes to those paths can result in
  61 timestamps that are identical to those in the index.  If that were
  62 possible, bup could overlook the modifications.
  63
  64 You can see the effect of this behavior in this example (assume that
  65 less than one second elapses between the initial file creation and
  66 first index run):
  67
  68     $ touch src/1 src/2
  69     # A "sleep 1" here would avoid the unexpected save.
  70     $ bup index src
  71     $ bup save -n src src  # Saves 1 and 2.
  72     $ date > src/1
  73     $ bup index src
  74     $ date > src/2         # Not indexed.
  75     $ bup save -n src src  # But src/2 is saved anyway.
  76
  77 Strictly speaking, bup should not notice the change to src/2, but it
  78 does, due to the accommodations described above.
  79
  80 # MODES
  81
  82 -u, \--update
  83 :   recursively update the index for the given filenames and
  84     their descendants.  One or more filenames must be
  85     given.  If no mode option is given, this is the
  86     default.
  87
  88 -p, \--print
  89 :   print the contents of the index.  If filenames are
  90     given, shows the given entries and their descendants.
  91     If no filenames are given, shows the entries starting
  92     at the current working directory (.).
  93
  94 -m, \--modified
  95 :   prints only files which are marked as modified (ie.
  96     changed since the most recent backup) in the index.
  97     Implies `-p`.
  98
  99 -s, \--status
 100 :   prepend a status code (A, M, D, or space) before each
 101     filename.  Implies `-p`.  The codes mean, respectively,
 102     that a file is marked in the index as added, modified,
 103     deleted, or unchanged since the last backup.
 104
 105
 106 # OPTIONS
 107
 108 -H, \--hash
 109 :   for each file printed, prepend the most recently
 110     recorded hash code.  The hash code is normally
 111     generated by `bup save`.  For objects which have not yet
 112     been backed up, the hash code will be
 113     0000000000000000000000000000000000000000.  Note that
 114     the hash code is printed even if the file is known to
 115     be modified or deleted in the index (ie. the file on
 116     the filesystem no longer matches the recorded hash).
 117     If this is a problem for you, use `--status`.
 118
 119 -l, \--long
 120 :   print more information about each file, in a similar
 121     format to the `-l` option to `ls`(1).
 122
 123 -x, \--xdev, \--one-file-system
 124 :   don't cross filesystem boundaries when recursing through the
 125     filesystem -- though as with tar and rsync, the mount points
 126     themselves will still be indexed.  Only applicable if you're using
 127     `-u`.
 128
 129 \--fake-valid
 130 :   mark specified filenames as up-to-date even if they
 131     aren't.  This can be useful for testing, or to avoid
 132     unnecessarily backing up files that you know are
 133     boring.
 134
 135 \--fake-invalid
 136 :   mark specified filenames as not up-to-date, forcing the
 137     next "bup save" run to re-check their contents.
 138
 139 \--check
 140 :   carefully check index file integrity before and after
 141     updating.  Mostly useful for automated tests.
 142
 143 \--clear
 144 :   clear the default index.
 145
 146 -f, \--indexfile=*indexfile*
 147 :   use a different index filename instead of
 148     `$BUP_DIR/bupindex`.
 149
 150 \--exclude=*path*
 151 :   exclude *path* from the backup (may be repeated).
 152
 153 \--exclude-from=*filename*
 154 :   read --exclude paths from *filename*, one path per-line (may be
 155     repeated).
 156
 157 \--exclude-rx=*pattern*
 158 :   exclude any path matching *pattern*, which must be a Python regular
 159     expression (http://docs.python.org/library/re.html).  The pattern
 160     will be compared against the full path, without anchoring, so
 161     "x/y" will match "ox/yard" or "box/yards".  To exclude the
 162     contents of /tmp, but not the directory itself, use
 163     "^/tmp/.". (may be repeated)
 164
 165     Examples:
 166
 167       * '/foo$' - exclude any file named foo
 168       * '/foo/$' - exclude any directory named foo
 169       * '/foo/.' - exclude the content of any directory named foo
 170       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 171
 172 \--exclude-rx-from=*filename*
 173 :   read --exclude-rx patterns from *filename*, one pattern per-line
 174     (may be repeated).
 175
 176 \--no-check-device
 177 :   don't mark a an entry invalid if the device number (stat(2)
 178     st_dev) changes.  This can be useful when indexing remote,
 179     automounted, or (LVM) snapshot filesystems.
 180
 181 -v, \--verbose
 182 :   increase log output during update (can be used more
 183     than once).  With one `-v`, print each directory as it
 184     is updated; with two `-v`, print each file too.
 185
 186
 187 # EXAMPLE
 188
 189     bup index -vux /etc /var /usr
 190
 191
 192 # SEE ALSO
 193
 194 `bup-save`(1), `bup-drecurse`(1), `bup-on`(1)
 195
 196 # BUP
 197
 198 Part of the `bup`(1) suite.