get: adjust for python 3 and test there

[bup.git] / Documentation / bup-midx.md

diff --git a/Documentation/bup-midx.md b/Documentation/bup-midx.md
index c216c89b325df63e894928d2ed64ea9fb9ccab81..2f1af3aaa5f9f47bf787713c6fcec0c0ca89222e 100644 (file)
--- a/Documentation/bup-midx.md
+++ b/Documentation/bup-midx.md
@@ -4,48 +4,57 @@
 
 # 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)
@@ -64,7 +73,7 @@ Normal idx files are convenient because it means you can use
 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.
@@ -86,10 +95,6 @@ objects that *do* 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.)
 
-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