/usr/share/doc/bup/bup-midx.html is in bup-doc 0.29-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<meta name="author" content="Avery Pennarun apenwarr@gmail.com" />
<meta name="date" content="2017-04-01" />
<title>bup-midx(1) Bup debian/0.29-3</title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<div id="header">
<h1 class="title">bup-midx(1) Bup debian/0.29-3</h1>
<h2 class="author">Avery Pennarun <a href="mailto:apenwarr@gmail.com">apenwarr@gmail.com</a></h2>
<h3 class="date">2017-04-01</h3>
</div>
<h1 id="name">NAME</h1>
<p>bup-midx - create a multi-index (<code>.midx</code>) file from several <code>.idx</code> files</p>
<h1 id="synopsis">SYNOPSIS</h1>
<p>bup midx [-o <em>outfile</em>] <-a|-f|<em>idxnames</em>...></p>
<h1 id="description">DESCRIPTION</h1>
<p><code>bup midx</code> creates a multi-index (<code>.midx</code>) file from one or more git pack index (<code>.idx</code>) files.</p>
<p>Note: you should no longer need to run this command by hand. It gets run automatically by <code>bup-save</code>(1) and similar commands.</p>
<h1 id="options">OPTIONS</h1>
<dl>
<dt>-o, --output=<em>filename.midx</em></dt>
<dd>use the given output filename for the <code>.midx</code> file. Default is auto-generated.
</dd>
<dt>-a, --auto</dt>
<dd>automatically generate new <code>.midx</code> files for any <code>.idx</code> files where it would be appropriate.
</dd>
<dt>-f, --force</dt>
<dd>force generation of a single new <code>.midx</code> file containing <em>all</em> your <code>.idx</code> files, even if other <code>.midx</code> files already exist. This will result in the fastest backup performance, but may take a long time to run.
</dd>
<dt>--dir=<em>packdir</em></dt>
<dd>specify the directory containing the <code>.idx</code>/<code>.midx</code> files to work with. The default is $BUP_DIR/objects/pack and $BUP_DIR/indexcache/*.
</dd>
<dt>--max-files</dt>
<dd>maximum number of <code>.idx</code> 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 <code>.idx</code> files at once. The default value of this option should be fine for most people.
</dd>
<dt>--check</dt>
<dd>validate a <code>.midx</code> file by ensuring that all objects in its contained <code>.idx</code> files exist inside the <code>.midx</code>. May be useful for debugging.
</dd>
</dl>
<h1 id="examples">EXAMPLES</h1>
<pre><code>$ bup midx -a
Merging 21 indexes (2278559 objects).
Table size: 524288 (17 bits)
Reading indexes: 100.00% (2278559/2278559), done.
midx-b66d7c9afc4396187218f2936a87b865cf342672.midx</code></pre>
<h1 id="discussion">DISCUSSION</h1>
<p>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).</p>
<p>Normal idx files are convenient because it means you can use <code>git</code>(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't have, but bup often does).</p>
<p>bup <code>.midx</code> 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.</p>
<p>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.</p>
<p>midx files are most useful when creating new backups, since searching for a nonexistent object in the repository necessarily requires searching through <em>all</em> the index files to ensure that it does not exist. (Searching for objects that <em>do</em> 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.)</p>
<h1 id="see-also">SEE ALSO</h1>
<p><code>bup-save</code>(1), <code>bup-margin</code>(1), <code>bup-memtest</code>(1)</p>
<h1 id="bup">BUP</h1>
<p>Part of the <code>bup</code>(1) suite.</p>
</body>
</html>
|