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|-u> [-s] [-H] [-l] [-x] [--fake-valid]
  12 [--check] [-f *indexfile*] [-v] <filenames...>
  13
  14 # DESCRIPTION
  15
  16 `bup index` prints and/or updates the bup filesystem index,
  17 which is a cache of the filenames, attributes, and sha-1
  18 hashes of each file and directory in the filesystem.  The
  19 bup index is similar in function to the `git`(1) index, and
  20 can be found in `~/.bup/bupindex`.
  21
  22 Creating a backup in bup consists of two steps: updating
  23 the index with `bup index`, then actually backing up the
  24 files (or a subset of the files) with `bup save`.  The
  25 separation exists for these reasons:
  26
  27 1. There is more than one way to generate a list of files
  28 that need to be backed up.  For example, you might want to
  29 use `inotify`(7) or `dnotify`(7).
  30
  31 2. Even if you back up files to multiple destinations (for
  32 added redundancy), the file names, attributes, and hashes
  33 will be the same each time.  Thus, you can save the trouble
  34 of repeatedly re-generating the list of files for each
  35 backup set.
  36
  37 3. You may want to use the data tracked by bup index for
  38 other purposes (such as speeding up other programs that
  39 need the same information).
  40
  41
  42 # OPTIONS
  43
  44 -u, --update
  45 :   (recursively) update the index for the given filenames and
  46     their descendants.  One or more filenames must be
  47     given.
  48
  49 -p, --print
  50 :   print the contents of the index.  If filenames are
  51     given, shows the given entries and their descendants.
  52     If no filenames are given, shows the entries starting
  53     at the current working directory (.).
  54
  55 -m, --modified
  56 :   prints only files which are marked as modified (ie.
  57     changed since the most recent backup) in the index.
  58     Implies `-p`.
  59
  60 -s, --status
  61 :   prepend a status code (A, M, D, or space) before each
  62     filename.  Implies `-p`.  The codes mean, respectively,
  63     that a file is marked in the index as added, modified,
  64     deleted, or unchanged since the last backup.
  65
  66 -H, --hash
  67 :   for each file printed, prepend the most recently
  68     recorded hash code.  The hash code is normally
  69     generated by `bup save`.  For objects which have not yet
  70     been backed up, the hash code will be
  71     0000000000000000000000000000000000000000.  Note that
  72     the hash code is printed even if the file is known to
  73     be modified or deleted in the index (ie. the file on
  74     the filesystem no longer matches the recorded hash).
  75     If this is a problem for you, use `--status`.
  76
  77 -l, --long
  78 :   print more information about each file, in a similar
  79     format to the `-l` option to `ls`(1).
  80
  81 -x, --xdev, --one-file-system
  82 :   don't cross filesystem boundaries when recursing
  83     through the filesystem.  Only applicable if you're
  84     using `-u`.
  85
  86 --fake-valid
  87 :   mark specified filenames as up-to-date even if they
  88     aren't.  This can be useful for testing, or to avoid
  89     unnecessarily backing up files that you know are
  90     boring.
  91
  92 --check
  93 :   carefully check index file integrity before and after
  94     updating.  Mostly useful for automated tests.
  95
  96 -f, --indexfile=*indexfile*
  97 :   use a different index filename instead of
  98     `~/.bup/bupindex`.
  99
 100 -v, --verbose
 101 :   increase log output during update (can be used more
 102     than once).  With one `-v`, print each directory as it
 103     is updated; with two `-v`, print each file too.
 104
 105
 106 # EXAMPLE
 107
 108     bup index -vux /etc /var /usr
 109
 110
 111 # SEE ALSO
 112
 113 `bup-save`(1), `bup-drecurse`(1)
 114
 115 # BUP
 116
 117 Part of the `bup`(1) suite.