.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "bup-midx" "1" "0.33.3" "Bup 0.33.3" ""
.hy
.SH NAME
.PP
bup-midx - create a multi-index (\f[V].midx\f[R]) file from several
\f[V].idx\f[R] files
.SH SYNOPSIS
.PP
bup midx [-o \f[I]outfile\f[R]] <-a|-f|\f[I]idxnames\f[R]\&...>
.SH DESCRIPTION
.PP
\f[V]bup midx\f[R] creates a multi-index (\f[V].midx\f[R]) file from one
or more git pack index (\f[V].idx\f[R]) files.
.PP
Note: you should no longer need to run this command by hand.
It gets run automatically by \f[V]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[V].midx\f[R] file.
Default is auto-generated.
.TP
-a, --auto
automatically generate new \f[V].midx\f[R] files for any \f[V].idx\f[R]
files where it would be appropriate.
.TP
-f, --force
force generation of a single new \f[V].midx\f[R] file containing
\f[I]all\f[R] your \f[V].idx\f[R] files, even if other \f[V].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[V].idx\f[R]/\f[V].midx\f[R]
files to work with.
The default is \f[V]$BUP_DIR/objects/pack\f[R].
.TP
--max-files
maximum number of \f[V].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[V].idx\f[R] files
at once.
The default value of this option should be fine for most people.
.TP
--check
validate a \f[V].midx\f[R] file by ensuring that all objects in its
contained \f[V].idx\f[R] files exist inside the \f[V].midx\f[R].
May be useful for debugging.
.SH EXAMPLES
.IP
.nf
\f[C]
$ bup midx -a
Merging 21 indexes (2278559 objects).
Table size: 524288 (17 bits)
Reading indexes: 100.00% (2278559/2278559), done.
midx-b66d7c9afc4396187218f2936a87b865cf342672.midx
\f[R]
.fi
.SH DISCUSSION
.PP
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[V]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[V].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
.PP
\f[V]bup-save\f[R](1), \f[V]bup-margin\f[R](1), \f[V]bup-memtest\f[R](1)
.SH BUP
.PP
Part of the \f[V]bup\f[R](1) suite.
.SH AUTHORS
Avery Pennarun <apenwarr@gmail.com>.