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 --max-files
  39 :   maximum number of .idx files to open at a time.  You
  40     can use this if you have an especially small number of file
  41     descriptors available, so that midx can complete
  42     (though possibly non-optimally) even if it can't open
  43     all your .idx files at once.  The default value of this
  44     option should be fine for most people.
  45
  46
  47 # EXAMPLE
  48
  49     $ bup midx -a
  50     Merging 21 indexes (2278559 objects).
  51     Table size: 524288 (17 bits)
  52     Reading indexes: 100.00% (2278559/2278559), done.
  53     midx-b66d7c9afc4396187218f2936a87b865cf342672.midx
  54
  55 # DISCUSSION
  56
  57 By default, bup uses git-formatted pack files, which
  58 consist of a pack file (containing objects) and an idx
  59 file (containing a sorted list of object names and their
  60 offsets in the .pack file).
  61
  62 Normal idx files are convenient because it means you can use
  63 `git`(1) to access your backup datasets.  However, idx
  64 files can get slow when you have a lot of very large packs
  65 (which git typically doesn't have, but bup often does).
  66
  67 bup .midx files consist of a single sorted list of all the objects
  68 contained in all the .pack files it references.  This list
  69 can be binary searched in about log2(m) steps, where m is
  70 the total number of objects.
  71
  72 To further speed up the search, midx files also have a
  73 variable-sized fanout table that reduces the first n
  74 steps of the binary search.  With the help of this fanout
  75 table, bup can narrow down which page of the midx file a
  76 given object id would be in (if it exists) with a single
  77 lookup.  Thus, typical searches will only need to swap in
  78 two pages: one for the fanout table, and one for the object
  79 id.
  80
  81 midx files are most useful when creating new backups, since
  82 searching for a nonexistent object in the repository
  83 necessarily requires searching through *all* the index
  84 files to ensure that it does not exist.  (Searching for
  85 objects that *do* exist can be optimized; for example,
  86 consecutive objects are often stored in the same pack, so
  87 we can search that one first using an MRU algorithm.)
  88
  89 With large repositories, you should be sure to run
  90 `bup midx -a` or `bup midx -f` every now and then so that
  91 creating backups will remain efficient.
  92
  93
  94 # SEE ALSO
  95
  96 `bup-save`(1), `bup-margin`(1), `bup-memtest`(1)
  97
  98 # BUP
  99
 100 Part of the `bup`(1) suite.