.\" Automatically generated by Pandoc 3.5
.\"
.TH "bup\-midx" "1" "2026\-01\-28" "Bup 0.33.10+"
.SH NAME
bup\-midx \- create a multi\-index (\f[CR].midx\f[R]) file from several
\f[CR].idx\f[R] files
.SH SYNOPSIS
bup midx [\-o \f[I]outfile\f[R]] <\-a|\-f|\f[I]idxnames\f[R]\&...>
.SH DESCRIPTION
\f[CR]bup midx\f[R] creates a multi\-index (\f[CR].midx\f[R]) file from
one or more git pack index (\f[CR].idx\f[R]) files.
.PP
Note: you should no longer need to run this command by hand.
It gets run automatically by \f[CR]bup\-save\f[R](1) and similar
commands.
.SH OPTIONS
.TP
\-o, \-\-output=\f[I]filename.midx\f[R]
use the given output filename for the \f[CR].midx\f[R] file.
Default is auto\-generated.
.TP
\-a, \-\-auto
automatically generate new \f[CR].midx\f[R] files for any
\f[CR].idx\f[R] files where it would be appropriate.
.TP
\-f, \-\-force
force generation of a single new \f[CR].midx\f[R] file containing
\f[I]all\f[R] your \f[CR].idx\f[R] files, even if other \f[CR].midx\f[R]
files already exist.
This will result in the fastest backup performance, but may take a long
time to run.
.TP
\-\-dir=\f[I]packdir\f[R]
specify the directory containing the \f[CR].idx\f[R]/\f[CR].midx\f[R]
files to work with.
The default is \f[CR]$BUP_DIR/objects/pack\f[R].
.TP
\-\-max\-files
maximum number of \f[CR].idx\f[R] 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\[cq]t open all your \f[CR].idx\f[R] files
at once.
The default value of this option should be fine for most people.
.TP
\-\-check
validate a \f[CR].midx\f[R] file by ensuring that all objects in its
contained \f[CR].idx\f[R] files exist inside the \f[CR].midx\f[R].
May be useful for debugging.
.SH EXAMPLES
.IP
.EX
$ bup midx \-a
Merging 21 indexes (2278559 objects).
Table size: 524288 (17 bits)
Reading indexes: 100.00% (2278559/2278559), done.
midx\-b66d7c9afc4396187218f2936a87b865cf342672.midx
.EE
.SH DISCUSSION
By default, bup uses git\-formatted pack files, which consist of a pack
file (containing objects) and an idx file (containing a sorted list of
object names and their offsets in the .pack file).
.PP
Normal idx files are convenient because it means you can use
\f[CR]git\f[R](1) to access your backup datasets.
However, idx files can get slow when you have a lot of very large packs
(which git typically doesn\[cq]t have, but bup often does).
.PP
bup \f[CR].midx\f[R] 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.
.PP
To further speed up the search, midx files also have a variable\-sized
fanout table that reduces the first n steps of the binary search.
With the help of this fanout table, bup can narrow down which page of
the midx file a given object id would be in (if it exists) with a single
lookup.
Thus, typical searches will only need to swap in two pages: one for the
fanout table, and one for the object id.
.PP
midx files are most useful when creating new backups, since searching
for a nonexistent object in the repository necessarily requires
searching through \f[I]all\f[R] the index files to ensure that it does
not exist.
(Searching for objects that \f[I]do\f[R] exist can be optimized; for
example, consecutive objects are often stored in the same pack, so we
can search that one first using an MRU algorithm.)
.SH SEE ALSO
\f[CR]bup\-save\f[R](1), \f[CR]bup\-margin\f[R](1),
\f[CR]bup\-memtest\f[R](1)
.SH BUP
Part of the \f[CR]bup\f[R](1) suite.
.SH AUTHORS
Avery Pennarun \c
.MT apenwarr@gmail.com
.ME \c.