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*] [-v] \<filenames...\>
  14
  15 # DESCRIPTION
  16
  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_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 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.
  50
  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.
  58
  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.
  62
  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
  65 first index run):
  66
  67     $ touch src/1 src/2
  68     # A "sleep 1" here would avoid the unexpected save.
  69     $ bup index src
  70     $ bup save -n src src  # Saves 1 and 2.
  71     $ date > src/1
  72     $ bup index src
  73     $ date > src/2         # Not indexed.
  74     $ bup save -n src src  # But src/2 is saved anyway.
  75
  76 Strictly speaking, bup should not notice the change to src/2, but it
  77 does, due to the accommodations described above.
  78
  79 # MODES
  80
  81 -u, \--update
  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
  85     default.
  86
  87 -p, \--print
  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 (.).
  92
  93 -m, \--modified
  94 :   prints only files which are marked as modified (ie.
  95     changed since the most recent backup) in the index.
  96     Implies `-p`.
  97
  98 -s, \--status
  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.
 103
 104
 105 # OPTIONS
 106
 107 -H, \--hash
 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`.
 117
 118 -l, \--long
 119 :   print more information about each file, in a similar
 120     format to the `-l` option to `ls`(1).
 121
 122 -x, \--xdev, \--one-file-system
 123 :   don't cross filesystem boundaries when recursing
 124     through the filesystem.  Only applicable if you're
 125     using `-u`.
 126
 127 \--fake-valid
 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
 131     boring.
 132
 133 \--fake-invalid
 134 :   mark specified filenames as not up-to-date, forcing the
 135     next "bup save" run to re-check their contents.
 136
 137 \--check
 138 :   carefully check index file integrity before and after
 139     updating.  Mostly useful for automated tests.
 140
 141 \--clear
 142 :   clear the index.
 143
 144 -f, \--indexfile=*indexfile*
 145 :   use a different index filename instead of
 146     `$BUP_DIR/bupindex`.
 147
 148 \--exclude=*path*
 149 :   exclude *path* from the backup; *path* is not expanded in any
 150     way (can be used more than once).
 151
 152 \--exclude-from=*filename*
 153 :   read --exclude paths from *filename*, one path per-line (can be
 154     used more than once).
 155
 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)
 163
 164     Examples:
 165
 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
 170
 171 \--no-check-device
 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.
 175
 176 -v, \--verbose
 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.
 180
 181
 182 # EXAMPLE
 183
 184     bup index -vux /etc /var /usr
 185
 186
 187 # SEE ALSO
 188
 189 `bup-save`(1), `bup-drecurse`(1), `bup-on`(1)
 190
 191 # BUP
 192
 193 Part of the `bup`(1) suite.