Documentation/bup-midx.md

   1 % bup-midx(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-midx - create a multi-index (.midx) file from several .idx files
   8
   9 # SYNOPSIS
  10
  11 bup midx [-o *outfile*] <-a|-f|*idxnames*...>
  12
  13 # DESCRIPTION
  14
  15 `bup midx` creates a multi-index (.midx) file from one or more
  16 git pack index (.idx) files.
  17
  18 You should run this command
  19 occasionally to ensure your backups run quickly and without
  20 requiring too much RAM.
  21
  22 # OPTIONS
  23
  24 -o, --output
  25 :   use the given output filename for the .midx file.
  26     Default is auto-generated.
  27
  28 -a, --auto
  29 :   automatically generate new .midx files for any .idx
  30     files where it would be appropriate.
  31
  32 -f, --force
  33 :   force generation of a single new .midx file containing
  34     *all* your .idx files, even if other .midx files
  35     already exist.  This will result in the fastest backup
  36     performance, but may take a long time to run.
  37
  38
  39 # EXAMPLE
  40
  41     $ bup midx -a
  42     Merging 21 indexes (2278559 objects).
  43     Table size: 524288 (17 bits)
  44     Reading indexes: 100.00% (2278559/2278559), done.
  45     midx-b66d7c9afc4396187218f2936a87b865cf342672.midx
  46
  47 # DISCUSSION
  48
  49 By default, bup uses git-formatted pack files, which
  50 consist of a pack file (containing objects) and an idx
  51 file (containing a sorted list of object names and their
  52 offsets in the .pack file).
  53
  54 Normal idx files are convenient because it means you can use
  55 `git`(1) to access your backup datasets.  However, idx
  56 files can get slow when you have a lot of very large packs
  57 (which git typically doesn't have, but bup often does).
  58
  59 bup .midx files consist of a single sorted list of all the objects
  60 contained in all the .pack files it references.  This list
  61 can be binary searched in about log2(m) steps, where m is
  62 the total number of objects.
  63
  64 To further speed up the search, midx files also have a
  65 variable-sized fanout table that reduces the first n
  66 steps of the binary search.  With the help of this fanout
  67 table, bup can narrow down which page of the midx file a
  68 given object id would be in (if it exists) with a single
  69 lookup.  Thus, typical searches will only need to swap in
  70 two pages: one for the fanout table, and one for the object
  71 id.
  72
  73 midx files are most useful when creating new backups, since
  74 searching for a nonexistent object in the repository
  75 necessarily requires searching through *all* the index
  76 files to ensure that it does not exist.  (Searching for
  77 objects that *do* exist can be optimized; for example,
  78 consecutive objects are often stored in the same pack, so
  79 we can search that one first using an MRU algorithm.)
  80
  81 With large repositories, you should be sure to run
  82 `bup midx -a` or `bup midx -f` every now and then so that
  83 creating backups will remain efficient.
  84
  85
  86 # SEE ALSO
  87
  88 `bup-save`(1), `bup-margin`(1), `bup-memtest`(1)
  89
  90 # BUP
  91
  92 Part of the `bup`(1) suite.