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|\--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.