summaryrefslogtreecommitdiffstats
path: root/Documentation/git-multi-pack-index.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-multi-pack-index.txt')
-rw-r--r--Documentation/git-multi-pack-index.txt138
1 files changed, 138 insertions, 0 deletions
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt
new file mode 100644
index 0000000..3696506
--- /dev/null
+++ b/Documentation/git-multi-pack-index.txt
@@ -0,0 +1,138 @@
+git-multi-pack-index(1)
+=======================
+
+NAME
+----
+git-multi-pack-index - Write and verify multi-pack-indexes
+
+
+SYNOPSIS
+--------
+[verse]
+'git multi-pack-index' [--object-dir=<dir>] [--[no-]bitmap] <sub-command>
+
+DESCRIPTION
+-----------
+Write or verify a multi-pack-index (MIDX) file.
+
+OPTIONS
+-------
+
+--object-dir=<dir>::
+ Use given directory for the location of Git objects. We check
+ `<dir>/packs/multi-pack-index` for the current MIDX file, and
+ `<dir>/packs` for the pack-files to index.
++
+`<dir>` must be an alternate of the current repository.
+
+--[no-]progress::
+ Turn progress on/off explicitly. If neither is specified, progress is
+ shown if standard error is connected to a terminal. Supported by
+ sub-commands `write`, `verify`, `expire`, and `repack.
+
+The following subcommands are available:
+
+write::
+ Write a new MIDX file. The following options are available for
+ the `write` sub-command:
++
+--
+ --preferred-pack=<pack>::
+ Optionally specify the tie-breaking pack used when
+ multiple packs contain the same object. `<pack>` must
+ contain at least one object. If not given, ties are
+ broken in favor of the pack with the lowest mtime.
+
+ --[no-]bitmap::
+ Control whether or not a multi-pack bitmap is written.
+
+ --stdin-packs::
+ Write a multi-pack index containing only the set of
+ line-delimited pack index basenames provided over stdin.
+
+ --refs-snapshot=<path>::
+ With `--bitmap`, optionally specify a file which
+ contains a "refs snapshot" taken prior to repacking.
++
+A reference snapshot is composed of line-delimited OIDs corresponding to
+the reference tips, usually taken by `git repack` prior to generating a
+new pack. A line may optionally start with a `+` character to indicate
+that the reference which corresponds to that OID is "preferred" (see
+linkgit:git-config[1]'s `pack.preferBitmapTips`.)
++
+The file given at `<path>` is expected to be readable, and can contain
+duplicates. (If a given OID is given more than once, it is marked as
+preferred if at least one instance of it begins with the special `+`
+marker).
+--
+
+verify::
+ Verify the contents of the MIDX file.
+
+expire::
+ Delete the pack-files that are tracked by the MIDX file, but
+ have no objects referenced by the MIDX (with the exception of
+ `.keep` packs and cruft packs). Rewrite the MIDX file afterward
+ to remove all references to these pack-files.
+
+repack::
+ Create a new pack-file containing objects in small pack-files
+ referenced by the multi-pack-index. If the size given by the
+ `--batch-size=<size>` argument is zero, then create a pack
+ containing all objects referenced by the multi-pack-index. For
+ a non-zero batch size, Select the pack-files by examining packs
+ from oldest-to-newest, computing the "expected size" by counting
+ the number of objects in the pack referenced by the
+ multi-pack-index, then divide by the total number of objects in
+ the pack and multiply by the pack size. We select packs with
+ expected size below the batch size until the set of packs have
+ total expected size at least the batch size, or all pack-files
+ are considered. If only one pack-file is selected, then do
+ nothing. If a new pack-file is created, rewrite the
+ multi-pack-index to reference the new pack-file. A later run of
+ 'git multi-pack-index expire' will delete the pack-files that
+ were part of this batch.
++
+If `repack.packKeptObjects` is `false`, then any pack-files with an
+associated `.keep` file will not be selected for the batch to repack.
+
+
+EXAMPLES
+--------
+
+* Write a MIDX file for the packfiles in the current `.git` directory.
++
+-----------------------------------------------
+$ git multi-pack-index write
+-----------------------------------------------
+
+* Write a MIDX file for the packfiles in the current `.git` directory with a
+corresponding bitmap.
++
+-------------------------------------------------------------
+$ git multi-pack-index write --preferred-pack=<pack> --bitmap
+-------------------------------------------------------------
+
+* Write a MIDX file for the packfiles in an alternate object store.
++
+-----------------------------------------------
+$ git multi-pack-index --object-dir <alt> write
+-----------------------------------------------
+
+* Verify the MIDX file for the packfiles in the current `.git` directory.
++
+-----------------------------------------------
+$ git multi-pack-index verify
+-----------------------------------------------
+
+
+SEE ALSO
+--------
+See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
+Document] and linkgit:gitformat-pack[5] for more information on the
+multi-pack-index feature and its file format.
+
+
+GIT
+---
+Part of the linkgit:git[1] suite