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` prints and/or updates the bup filesystem index,
  19 which is a cache of the absolute paths, 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 At the moment, bup will ignore Linux attributes (cf. chattr(1) and
  46 lsattr(1)) on some systems (any big-endian systems where sizeof(long)
  47 < sizeof(int)).  This is because the Linux kernel and FUSE currently
  48 disagree over the type of the attr system call arguments, and so on
  49 big-endian systems there's no way to get the results without the risk
  50 of stack corruption (http://lwn.net/Articles/575846/).  In these
  51 situations, bup will print a warning the first time Linux attrs are
  52 relevant during any index/save/restore operation.
  53
  54 bup makes accommodations for the expected "worst-case" filesystem
  55 timestamp resolution -- currently one second; examples include VFAT,
  56 ext2, ext3, small ext4, etc.  Since bup cannot know the filesystem
  57 timestamp resolution, and could be traversing multiple filesystems
  58 during any given run, it always assumes that the resolution may be no
  59 better than one second.
  60
  61 As a practical matter, this means that index updates are a bit
  62 imprecise, and so `bup save` may occasionally record filesystem
  63 changes that you didn't expect.  That's because, during an index
  64 update, if bup encounters a path whose actual timestamps are more
  65 recent than one second before the update started, bup will set the
  66 index timestamps for that path (mtime and ctime) to exactly one second
  67 before the run, -- effectively capping those values.
  68
  69 This ensures that no subsequent changes to those paths can result in
  70 timestamps that are identical to those in the index.  If that were
  71 possible, bup could overlook the modifications.
  72
  73 You can see the effect of this behavior in this example (assume that
  74 less than one second elapses between the initial file creation and
  75 first index run):
  76
  77     $ touch src/1 src/2
  78     # A "sleep 1" here would avoid the unexpected save.
  79     $ bup index src
  80     $ bup save -n src src  # Saves 1 and 2.
  81     $ date > src/1
  82     $ bup index src
  83     $ date > src/2         # Not indexed.
  84     $ bup save -n src src  # But src/2 is saved anyway.
  85
  86 Strictly speaking, bup should not notice the change to src/2, but it
  87 does, due to the accommodations described above.
  88
  89 # MODES
  90
  91 -u, \--update
  92 :   recursively update the index for the given paths and their
  93     descendants.  One or more paths must be specified, and if a path
  94     ends with a symbolic link, the link itself will be indexed, not
  95     the target.  If no mode option is given, `--update` is the
  96     default, and paths may be excluded by the `--exclude`,
  97     `--exclude-rx`, and `--one-file-system` options.
  98
  99 -p, \--print
 100 :   print the contents of the index.  If paths are
 101     given, shows the given entries and their descendants.
 102     If no paths are given, shows the entries starting
 103     at the current working directory (.).
 104
 105 -m, \--modified
 106 :   prints only files which are marked as modified (ie.
 107     changed since the most recent backup) in the index.
 108     Implies `-p`.
 109
 110 -s, \--status
 111 :   prepend a status code (A, M, D, or space) before each
 112     filename.  Implies `-p`.  The codes mean, respectively,
 113     that a file is marked in the index as added, modified,
 114     deleted, or unchanged since the last backup.
 115
 116 \--check
 117 :   carefully check index file integrity before and after
 118     updating.  Mostly useful for automated tests.
 119
 120 \--clear
 121 :   clear the default index.
 122
 123
 124 # OPTIONS
 125
 126 -H, \--hash
 127 :   for each file printed, prepend the most recently
 128     recorded hash code.  The hash code is normally
 129     generated by `bup save`.  For objects which have not yet
 130     been backed up, the hash code will be
 131     0000000000000000000000000000000000000000.  Note that
 132     the hash code is printed even if the file is known to
 133     be modified or deleted in the index (ie. the file on
 134     the filesystem no longer matches the recorded hash).
 135     If this is a problem for you, use `--status`.
 136
 137 -l, \--long
 138 :   print more information about each file, in a similar
 139     format to the `-l` option to `ls`(1).
 140
 141 -x, \--xdev, \--one-file-system
 142 :   don't cross filesystem boundaries when recursing through the
 143     filesystem -- though as with tar and rsync, the mount points
 144     themselves will still be indexed.  Only applicable if you're using
 145     `-u`.
 146
 147 \--fake-valid
 148 :   mark specified paths as up-to-date even if they
 149     aren't.  This can be useful for testing, or to avoid
 150     unnecessarily backing up files that you know are
 151     boring.
 152
 153 \--fake-invalid
 154 :   mark specified paths as not up-to-date, forcing the
 155     next "bup save" run to re-check their contents.
 156
 157 -f, \--indexfile=*indexfile*
 158 :   use a different index filename instead of
 159     `$BUP_DIR/bupindex`.
 160
 161 \--exclude=*path*
 162 :   exclude *path* from the backup (may be repeated).
 163
 164 \--exclude-from=*filename*
 165 :   read --exclude paths from *filename*, one path per-line (may be
 166     repeated).  Ignore completely empty lines.
 167
 168 \--exclude-rx=*pattern*
 169 :   exclude any path matching *pattern*, which must be a Python regular
 170     expression (http://docs.python.org/library/re.html).  The pattern
 171     will be compared against the full path, without anchoring, so
 172     "x/y" will match "ox/yard" or "box/yards".  To exclude the
 173     contents of /tmp, but not the directory itself, use
 174     "^/tmp/.". (may be repeated)
 175
 176     Examples:
 177
 178       * '/foo$' - exclude any file named foo
 179       * '/foo/$' - exclude any directory named foo
 180       * '/foo/.' - exclude the content of any directory named foo
 181       * '^/tmp/.' - exclude root-level /tmp's content, but not /tmp itself
 182
 183 \--exclude-rx-from=*filename*
 184 :   read --exclude-rx patterns from *filename*, one pattern per-line
 185     (may be repeated).  Ignore completely empty lines.
 186
 187 \--no-check-device
 188 :   don't mark an entry invalid if the device number (stat(2) st_dev)
 189     changes.  This can be useful when indexing remote, automounted, or
 190     snapshot filesystems (LVM, Btrfs, etc.), where the device number
 191     isn't fixed.
 192
 193 -v, \--verbose
 194 :   increase log output during update (can be used more
 195     than once).  With one `-v`, print each directory as it
 196     is updated; with two `-v`, print each file too.
 197
 198
 199 # EXAMPLES
 200     bup index -vux /etc /var /usr
 201
 202
 203 # SEE ALSO
 204
 205 `bup-save`(1), `bup-drecurse`(1), `bup-on`(1)
 206
 207 # BUP
 208
 209 Part of the `bup`(1) suite.