# NAME
-bup-midx - create a multi-index (.midx) file from several .idx files
+bup-midx - create a multi-index (`.midx`) file from several `.idx` files
# SYNOPSIS
-bup midx [-o *outfile*] <-a|-f|*idxnames*...>
+bup midx [-o *outfile*] \<-a|-f|*idxnames*...\>
# DESCRIPTION
-`bup midx` creates a multi-index (.midx) file from one or more
-git pack index (.idx) files.
+`bup midx` creates a multi-index (`.midx`) file from one or more
+git pack index (`.idx`) files.
-You should run this command
-occasionally to ensure your backups run quickly and without
-requiring too much RAM.
+Note: you should no longer need to run this command by hand.
+It gets run automatically by `bup-save`(1) and similar
+commands.
# OPTIONS
--o, --output
-: use the given output filename for the .midx file.
+-o, \--output=*filename.midx*
+: use the given output filename for the `.midx` file.
Default is auto-generated.
-
--a, --auto
-: automatically generate new .midx files for any .idx
+
+-a, \--auto
+: automatically generate new `.midx` files for any `.idx`
files where it would be appropriate.
-
--f, --force
-: force generation of a single new .midx file containing
- *all* your .idx files, even if other .midx files
+
+-f, \--force
+: force generation of a single new `.midx` file containing
+ *all* your `.idx` files, even if other `.midx` files
already exist. This will result in the fastest backup
performance, but may take a long time to run.
---max-files
-: maximum number of .idx files to open at a time. You
+\--dir=*packdir*
+: specify the directory containing the `.idx`/`.midx` files
+ to work with. The default is $BUP_DIR/objects/pack and
+ $BUP_DIR/indexcache/*.
+
+\--max-files
+: maximum number of `.idx` files to open at a time. You
can use this if you have an especially small number of file
descriptors available, so that midx can complete
(though possibly non-optimally) even if it can't open
- all your .idx files at once. The default value of this
+ all your `.idx` files at once. The default value of this
option should be fine for most people.
+
+\--check
+: validate a `.midx` file by ensuring that all objects in
+ its contained `.idx` files exist inside the `.midx`. May
+ be useful for debugging.
-# EXAMPLE
-
+# EXAMPLES
$ bup midx -a
Merging 21 indexes (2278559 objects).
Table size: 524288 (17 bits)
files can get slow when you have a lot of very large packs
(which git typically doesn't have, but bup often does).
-bup .midx files consist of a single sorted list of all the objects
+bup `.midx` files consist of a single sorted list of all the objects
contained in all the .pack files it references. This list
can be binary searched in about log2(m) steps, where m is
the total number of objects.
consecutive objects are often stored in the same pack, so
we can search that one first using an MRU algorithm.)
-With large repositories, you should be sure to run
-`bup midx -a` or `bup midx -f` every now and then so that
-creating backups will remain efficient.
-
# SEE ALSO