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]
  12 [\--fake-invalid] [\--check] [-f *indexfile*] [\--exclude *path*]
  13 [\--exclude-from *filename*] [-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/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
  43 # MODES
  44
  45 -u, \--update
  46 :   recursively update the index for the given filenames and
  47     their descendants.  One or more filenames must be
  48     given.  If no mode option is given, this is the
  49     default.
  50
  51 -p, \--print
  52 :   print the contents of the index.  If filenames are
  53     given, shows the given entries and their descendants.
  54     If no filenames are given, shows the entries starting
  55     at the current working directory (.).
  56
  57 -m, \--modified
  58 :   prints only files which are marked as modified (ie.
  59     changed since the most recent backup) in the index.
  60     Implies `-p`.
  61
  62 -s, \--status
  63 :   prepend a status code (A, M, D, or space) before each
  64     filename.  Implies `-p`.  The codes mean, respectively,
  65     that a file is marked in the index as added, modified,
  66     deleted, or unchanged since the last backup.
  67
  68
  69 # OPTIONS
  70
  71 -H, \--hash
  72 :   for each file printed, prepend the most recently
  73     recorded hash code.  The hash code is normally
  74     generated by `bup save`.  For objects which have not yet
  75     been backed up, the hash code will be
  76     0000000000000000000000000000000000000000.  Note that
  77     the hash code is printed even if the file is known to
  78     be modified or deleted in the index (ie. the file on
  79     the filesystem no longer matches the recorded hash).
  80     If this is a problem for you, use `--status`.
  81
  82 -l, \--long
  83 :   print more information about each file, in a similar
  84     format to the `-l` option to `ls`(1).
  85
  86 -x, \--xdev, \--one-file-system
  87 :   don't cross filesystem boundaries when recursing
  88     through the filesystem.  Only applicable if you're
  89     using `-u`.
  90
  91 \--fake-valid
  92 :   mark specified filenames as up-to-date even if they
  93     aren't.  This can be useful for testing, or to avoid
  94     unnecessarily backing up files that you know are
  95     boring.
  96
  97 \--fake-invalid
  98 :   mark specified filenames as not up-to-date, forcing the
  99     next "bup save" run to re-check their contents.
 100
 101 \--check
 102 :   carefully check index file integrity before and after
 103     updating.  Mostly useful for automated tests.
 104
 105 -f, \--indexfile=*indexfile*
 106 :   use a different index filename instead of
 107     `~/.bup/bupindex`.
 108
 109 \--exclude=*path*
 110 :   a path to exclude from the backup (can be used more
 111     than once)
 112
 113 \--exclude-from=*filename*
 114 :   a file that contains exclude paths (can be used more
 115     than once)
 116
 117 -v, \--verbose
 118 :   increase log output during update (can be used more
 119     than once).  With one `-v`, print each directory as it
 120     is updated; with two `-v`, print each file too.
 121
 122
 123 # EXAMPLE
 124
 125     bup index -vux /etc /var /usr
 126
 127
 128 # SEE ALSO
 129
 130 `bup-save`(1), `bup-drecurse`(1), `bup-on`(1)
 131
 132 # BUP
 133
 134 Part of the `bup`(1) suite.