| 1 | git-multi-pack-index(1) |
| 2 | ======================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-multi-pack-index - Write and verify multi-pack-indexes |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git multi-pack-index' [<options>] write [--preferred-pack=<pack>] |
| 13 | [--[no-]bitmap] [--[no-]incremental] [--[no-]stdin-packs] |
| 14 | [--refs-snapshot=<path>] [--[no-]write-chain-file] |
| 15 | [--base=<checksum>] |
| 16 | 'git multi-pack-index' [<options>] compact [--[no-]incremental] |
| 17 | [--[no-]bitmap] [--base=<checksum>] [--[no-]write-chain-file] |
| 18 | <from> <to> |
| 19 | 'git multi-pack-index' [<options>] verify |
| 20 | 'git multi-pack-index' [<options>] expire |
| 21 | 'git multi-pack-index' [<options>] repack [--batch-size=<size>] |
| 22 | |
| 23 | DESCRIPTION |
| 24 | ----------- |
| 25 | Write or verify a multi-pack-index (MIDX) file. |
| 26 | |
| 27 | OPTIONS |
| 28 | ------- |
| 29 | |
| 30 | The following command-line options are applicable to all sub-commands: |
| 31 | |
| 32 | --object-dir=<dir>:: |
| 33 | Use given directory for the location of Git objects. We check |
| 34 | `<dir>/packs/multi-pack-index` for the current MIDX file, and |
| 35 | `<dir>/packs` for the pack-files to index. |
| 36 | + |
| 37 | `<dir>` must be an alternate of the current repository. |
| 38 | |
| 39 | --progress:: |
| 40 | --no-progress:: |
| 41 | Turn progress on/off explicitly. If neither is specified, progress is |
| 42 | shown if standard error is connected to a terminal. Supported by |
| 43 | sub-commands `write`, `verify`, `expire`, and `repack`. |
| 44 | |
| 45 | The following subcommands are available: |
| 46 | |
| 47 | write:: |
| 48 | Write a new MIDX file. The following options are available for |
| 49 | the `write` sub-command: |
| 50 | + |
| 51 | -- |
| 52 | --preferred-pack=<pack>:: |
| 53 | When specified, break ties in favor of this pack when |
| 54 | there are additional copies of its objects in other |
| 55 | packs. Ties for objects not found in the preferred |
| 56 | pack are always resolved in favor of the copy in the |
| 57 | pack with the highest mtime. If unspecified, the pack |
| 58 | with the lowest mtime is used by default. The |
| 59 | preferred pack must have at least one object. |
| 60 | |
| 61 | --[no-]bitmap:: |
| 62 | Control whether or not a multi-pack bitmap is written. |
| 63 | |
| 64 | --stdin-packs:: |
| 65 | Write a multi-pack index containing only the set of |
| 66 | line-delimited pack index basenames provided over stdin. |
| 67 | |
| 68 | --refs-snapshot=<path>:: |
| 69 | With `--bitmap`, optionally specify a file which |
| 70 | contains a "refs snapshot" taken prior to repacking. |
| 71 | + |
| 72 | A reference snapshot is composed of line-delimited OIDs corresponding to |
| 73 | the reference tips, usually taken by `git repack` prior to generating a |
| 74 | new pack. A line may optionally start with a `+` character to indicate |
| 75 | that the reference which corresponds to that OID is "preferred" (see |
| 76 | linkgit:git-config[1]'s `pack.preferBitmapTips`.) |
| 77 | + |
| 78 | The file given at `<path>` is expected to be readable, and can contain |
| 79 | duplicates. (If a given OID is given more than once, it is marked as |
| 80 | preferred if at least one instance of it begins with the special `+` |
| 81 | marker). |
| 82 | |
| 83 | --incremental:: |
| 84 | Write an incremental MIDX file containing only objects |
| 85 | and packs not present in an existing MIDX layer. |
| 86 | Migrates non-incremental MIDXs to incremental ones when |
| 87 | necessary. |
| 88 | |
| 89 | --[no-]write-chain-file:: |
| 90 | When used with `--incremental`, write a new MIDX layer |
| 91 | but do not update the multi-pack-index-chain file. |
| 92 | The checksum of the new layer is printed to standard |
| 93 | output, allowing the caller to assemble and write the |
| 94 | chain itself. Requires `--incremental`. |
| 95 | |
| 96 | --base=<checksum>:: |
| 97 | Specify the checksum of an existing MIDX layer to use |
| 98 | as the base when writing a new incremental layer. |
| 99 | The special value `none` indicates that the new layer |
| 100 | should have no base (i.e., it becomes a root layer). |
| 101 | Requires `--no-write-chain-file`. |
| 102 | -- |
| 103 | |
| 104 | compact:: |
| 105 | Write a new MIDX layer containing only objects and packs present |
| 106 | in the range `<from>` to `<to>`, where both arguments are |
| 107 | checksums of existing layers in the MIDX chain. |
| 108 | + |
| 109 | -- |
| 110 | --incremental:: |
| 111 | Write the result to a MIDX chain instead of writing a |
| 112 | stand-alone MIDX. |
| 113 | |
| 114 | --[no-]bitmap:: |
| 115 | Control whether or not a multi-pack bitmap is written. |
| 116 | |
| 117 | --[no-]write-chain-file:: |
| 118 | When used with `--incremental`, write a new compacted |
| 119 | MIDX layer but do not update the multi-pack-index-chain |
| 120 | file. The checksum of the new layer is printed to |
| 121 | standard output. Requires `--incremental`. |
| 122 | |
| 123 | --base=<checksum>:: |
| 124 | Specify the checksum of an existing MIDX layer to use |
| 125 | as the base for the compacted result, instead of using |
| 126 | the immediate parent of `<from>`. The special value |
| 127 | `none` indicates that the result should have no base. |
| 128 | -- |
| 129 | + |
| 130 | Note that the compact command requires writing a version-2 midx that |
| 131 | cannot be read by versions of Git prior to v2.54. |
| 132 | |
| 133 | verify:: |
| 134 | Verify the contents of the MIDX file. |
| 135 | |
| 136 | expire:: |
| 137 | Delete the pack-files that are tracked by the MIDX file, but |
| 138 | have no objects referenced by the MIDX (with the exception of |
| 139 | `.keep` packs and cruft packs). Rewrite the MIDX file afterward |
| 140 | to remove all references to these pack-files. |
| 141 | + |
| 142 | NOTE: this mode is incompatible with incremental MIDX files. |
| 143 | |
| 144 | repack:: |
| 145 | Create a new pack-file containing objects in small pack-files |
| 146 | referenced by the multi-pack-index. If the size given by the |
| 147 | `--batch-size=<size>` argument is zero, then create a pack |
| 148 | containing all objects referenced by the multi-pack-index. For |
| 149 | a non-zero batch size, Select the pack-files by examining packs |
| 150 | from oldest-to-newest, computing the "expected size" by counting |
| 151 | the number of objects in the pack referenced by the |
| 152 | multi-pack-index, then divide by the total number of objects in |
| 153 | the pack and multiply by the pack size. We select packs with |
| 154 | expected size below the batch size until the set of packs have |
| 155 | total expected size at least the batch size, or all pack-files |
| 156 | are considered. If only one pack-file is selected, then do |
| 157 | nothing. If a new pack-file is created, rewrite the |
| 158 | multi-pack-index to reference the new pack-file. A later run of |
| 159 | 'git multi-pack-index expire' will delete the pack-files that |
| 160 | were part of this batch. |
| 161 | + |
| 162 | If `repack.packKeptObjects` is `false`, then any pack-files with an |
| 163 | associated `.keep` file will not be selected for the batch to repack. |
| 164 | + |
| 165 | NOTE: this mode is incompatible with incremental MIDX files. |
| 166 | |
| 167 | EXAMPLES |
| 168 | -------- |
| 169 | |
| 170 | * Write a MIDX file for the packfiles in the current `.git` directory. |
| 171 | + |
| 172 | ----------------------------------------------- |
| 173 | $ git multi-pack-index write |
| 174 | ----------------------------------------------- |
| 175 | |
| 176 | * Write a MIDX file for the packfiles in the current `.git` directory with a |
| 177 | corresponding bitmap. |
| 178 | + |
| 179 | ------------------------------------------------------------- |
| 180 | $ git multi-pack-index write --preferred-pack=<pack> --bitmap |
| 181 | ------------------------------------------------------------- |
| 182 | |
| 183 | * Write a MIDX file for the packfiles in an alternate object store. |
| 184 | + |
| 185 | ----------------------------------------------- |
| 186 | $ git multi-pack-index --object-dir <alt> write |
| 187 | ----------------------------------------------- |
| 188 | |
| 189 | * Verify the MIDX file for the packfiles in the current `.git` directory. |
| 190 | + |
| 191 | ----------------------------------------------- |
| 192 | $ git multi-pack-index verify |
| 193 | ----------------------------------------------- |
| 194 | |
| 195 | |
| 196 | SEE ALSO |
| 197 | -------- |
| 198 | See link:technical/multi-pack-index.html[The Multi-Pack-Index Design |
| 199 | Document] and linkgit:gitformat-pack[5] for more information on the |
| 200 | multi-pack-index feature and its file format. |
| 201 | |
| 202 | |
| 203 | GIT |
| 204 | --- |
| 205 | Part of the linkgit:git[1] suite |