| 1 | git-repack(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-repack - Pack unpacked objects in a repository |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] |
| 13 | [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] |
| 14 | [--write-midx[=<mode>]] [--name-hash-version=<n>] [--path-walk] |
| 15 | |
| 16 | DESCRIPTION |
| 17 | ----------- |
| 18 | |
| 19 | This command is used to combine all objects that do not currently |
| 20 | reside in a "pack", into a pack. It can also be used to re-organize |
| 21 | existing packs into a single, more efficient pack. |
| 22 | |
| 23 | A pack is a collection of objects, individually compressed, with |
| 24 | delta compression applied, stored in a single file, with an |
| 25 | associated index file. |
| 26 | |
| 27 | Packs are used to reduce the load on mirror systems, backup |
| 28 | engines, disk storage, etc. |
| 29 | |
| 30 | OPTIONS |
| 31 | ------- |
| 32 | |
| 33 | -a:: |
| 34 | Instead of incrementally packing the unpacked objects, |
| 35 | pack everything referenced into a single pack. |
| 36 | Especially useful when packing a repository that is used |
| 37 | for private development. Use |
| 38 | with `-d`. This will clean up the objects that `git prune` |
| 39 | leaves behind, but `git fsck --full --dangling` shows as |
| 40 | dangling. |
| 41 | + |
| 42 | Note that users fetching over dumb protocols will have to fetch the |
| 43 | whole new pack in order to get any contained object, no matter how many |
| 44 | other objects in that pack they already have locally. |
| 45 | + |
| 46 | Promisor packfiles are repacked separately: if there are packfiles that |
| 47 | have an associated ".promisor" file, these packfiles will be repacked |
| 48 | into another separate pack, and an empty ".promisor" file corresponding |
| 49 | to the new separate pack will be written. |
| 50 | |
| 51 | -A:: |
| 52 | Same as `-a`, unless `-d` is used. Then any unreachable |
| 53 | objects in a previous pack become loose, unpacked objects, |
| 54 | instead of being left in the old pack. Unreachable objects |
| 55 | are never intentionally added to a pack, even when repacking. |
| 56 | This option prevents unreachable objects from being immediately |
| 57 | deleted by way of being left in the old pack and then |
| 58 | removed. Instead, the loose unreachable objects |
| 59 | will be pruned according to normal expiry rules |
| 60 | with the next 'git gc' invocation. See linkgit:git-gc[1]. |
| 61 | |
| 62 | -d:: |
| 63 | After packing, if the newly created packs make some |
| 64 | existing packs redundant, remove the redundant packs. |
| 65 | Also run 'git prune-packed' to remove redundant |
| 66 | loose object files. |
| 67 | |
| 68 | --cruft:: |
| 69 | Same as `-a`, unless `-d` is used. Then any unreachable objects |
| 70 | are packed into a separate cruft pack. Unreachable objects can |
| 71 | be pruned using the normal expiry rules with the next `git gc` |
| 72 | invocation (see linkgit:git-gc[1]). Incompatible with `-k`. |
| 73 | + |
| 74 | When combined with `--geometric`, `--cruft` does not imply `-a`. Instead, |
| 75 | the geometric repack rolls up packs as usual, and a separate cruft pack is |
| 76 | written to collect unreachable objects. Only reachable objects from the |
| 77 | rolled-up packs are included in the resulting geometric pack. |
| 78 | |
| 79 | --cruft-expiration=<approxidate>:: |
| 80 | Expire unreachable objects older than `<approxidate>` |
| 81 | immediately instead of waiting for the next `git gc` invocation. |
| 82 | Only useful with `--cruft -d`. |
| 83 | |
| 84 | --max-cruft-size=<n>:: |
| 85 | Override `--max-pack-size` for cruft packs. Inherits the value of |
| 86 | `--max-pack-size` (if any) by default. See the documentation for |
| 87 | `--max-pack-size` for more details. |
| 88 | |
| 89 | --combine-cruft-below-size=<n>:: |
| 90 | When generating cruft packs without pruning, only repack |
| 91 | existing cruft packs whose size is strictly less than `<n>` |
| 92 | bytes, which can optionally |
| 93 | be suffixed with "k", "m", or "g". Cruft packs whose size is |
| 94 | greater than or equal to `<n>` are left as-is and not repacked. |
| 95 | Useful when you want to avoid repacking large cruft pack(s) in |
| 96 | repositories that have many and/or large unreachable objects. |
| 97 | |
| 98 | --expire-to=<dir>:: |
| 99 | Write a cruft pack containing pruned objects (if any) to the |
| 100 | directory `<dir>`. This option is useful for keeping a copy of |
| 101 | any pruned objects in a separate directory as a backup. Only |
| 102 | useful with `--cruft -d`. |
| 103 | |
| 104 | -l:: |
| 105 | Pass the `--local` option to 'git pack-objects'. See |
| 106 | linkgit:git-pack-objects[1]. |
| 107 | |
| 108 | -f:: |
| 109 | Pass the `--no-reuse-delta` option to `git-pack-objects`, see |
| 110 | linkgit:git-pack-objects[1]. |
| 111 | |
| 112 | -F:: |
| 113 | Pass the `--no-reuse-object` option to `git-pack-objects`, see |
| 114 | linkgit:git-pack-objects[1]. |
| 115 | |
| 116 | -q:: |
| 117 | --quiet:: |
| 118 | Show no progress over the standard error stream and pass the `-q` |
| 119 | option to 'git pack-objects'. See linkgit:git-pack-objects[1]. |
| 120 | |
| 121 | -n:: |
| 122 | Do not update the server information with |
| 123 | 'git update-server-info'. This option skips |
| 124 | updating local catalog files needed to publish |
| 125 | this repository (or a direct copy of it) |
| 126 | over HTTP or FTP. See linkgit:git-update-server-info[1]. |
| 127 | |
| 128 | --window=<n>:: |
| 129 | --depth=<n>:: |
| 130 | These two options affect how the objects contained in the pack are |
| 131 | stored using delta compression. The objects are first internally |
| 132 | sorted by type, size and optionally names and compared against the |
| 133 | other objects within `--window` to see if using delta compression saves |
| 134 | space. `--depth` limits the maximum delta depth; making it too deep |
| 135 | affects the performance on the unpacker side, because delta data needs |
| 136 | to be applied that many times to get to the necessary object. |
| 137 | + |
| 138 | The default value for --window is 10 and --depth is 50. The maximum |
| 139 | depth is 4095. |
| 140 | |
| 141 | --threads=<n>:: |
| 142 | This option is passed through to `git pack-objects`. |
| 143 | |
| 144 | --window-memory=<n>:: |
| 145 | This option provides an additional limit on top of `--window`; |
| 146 | the window size will dynamically scale down so as to not take |
| 147 | up more than '<n>' bytes in memory. This is useful in |
| 148 | repositories with a mix of large and small objects to not run |
| 149 | out of memory with a large window, but still be able to take |
| 150 | advantage of the large window for the smaller objects. The |
| 151 | size can be suffixed with "k", "m", or "g". |
| 152 | `--window-memory=0` makes memory usage unlimited. The default |
| 153 | is taken from the `pack.windowMemory` configuration variable. |
| 154 | Note that the actual memory usage will be the limit multiplied |
| 155 | by the number of threads used by linkgit:git-pack-objects[1]. |
| 156 | |
| 157 | --max-pack-size=<n>:: |
| 158 | Maximum size of each output pack file. The size can be suffixed with |
| 159 | "k", "m", or "g". The minimum size allowed is limited to 1 MiB. |
| 160 | If specified, multiple packfiles may be created, which also |
| 161 | prevents the creation of a bitmap index. |
| 162 | The default is unlimited, unless the config variable |
| 163 | `pack.packSizeLimit` is set. Note that this option may result in |
| 164 | a larger and slower repository; see the discussion in |
| 165 | `pack.packSizeLimit`. |
| 166 | |
| 167 | --filter=<filter-spec>:: |
| 168 | Remove objects matching the filter specification from the |
| 169 | resulting packfile and put them into a separate packfile. Note |
| 170 | that objects used in the working directory are not filtered |
| 171 | out. So for the split to fully work, it's best to perform it |
| 172 | in a bare repo and to use the `-a` and `-d` options along with |
| 173 | this option. Also `--no-write-bitmap-index` (or the |
| 174 | `repack.writebitmaps` config option set to `false`) should be |
| 175 | used otherwise writing bitmap index will fail, as it supposes |
| 176 | a single packfile containing all the objects. See |
| 177 | linkgit:git-rev-list[1] for valid `<filter-spec>` forms. |
| 178 | |
| 179 | --filter-to=<dir>:: |
| 180 | Write the pack containing filtered out objects to the |
| 181 | directory `<dir>`. Only useful with `--filter`. This can be |
| 182 | used for putting the pack on a separate object directory that |
| 183 | is accessed through the Git alternates mechanism. **WARNING:** |
| 184 | If the packfile containing the filtered out objects is not |
| 185 | accessible, the repo can become corrupt as it might not be |
| 186 | possible to access the objects in that packfile. See the |
| 187 | `objects` and `objects/info/alternates` sections of |
| 188 | linkgit:gitrepository-layout[5]. |
| 189 | |
| 190 | -b:: |
| 191 | --write-bitmap-index:: |
| 192 | Write a reachability bitmap index as part of the repack. This |
| 193 | only makes sense when used with `-a`, `-A` or `-m`, as the bitmaps |
| 194 | must be able to refer to all reachable objects. This option |
| 195 | overrides the setting of `repack.writeBitmaps`. This option |
| 196 | has no effect if multiple packfiles are created, unless writing a |
| 197 | MIDX (in which case a multi-pack bitmap is created). |
| 198 | |
| 199 | --pack-kept-objects:: |
| 200 | Include objects in `.keep` files when repacking. Note that we |
| 201 | still do not delete `.keep` packs after `pack-objects` finishes. |
| 202 | This means that we may duplicate objects, but this makes the |
| 203 | option safe to use when there are concurrent pushes or fetches. |
| 204 | This option is generally only useful if you are writing bitmaps |
| 205 | with `-b` or `repack.writeBitmaps`, as it ensures that the |
| 206 | bitmapped packfile has the necessary objects. |
| 207 | |
| 208 | --keep-pack=<pack-name>:: |
| 209 | Exclude the given pack from repacking. This is the equivalent |
| 210 | of having `.keep` file on the pack. `<pack-name>` is the |
| 211 | pack file name without leading directory (e.g. `pack-123.pack`). |
| 212 | The option can be specified multiple times to keep multiple |
| 213 | packs. |
| 214 | |
| 215 | --unpack-unreachable=<when>:: |
| 216 | When loosening unreachable objects, do not bother loosening any |
| 217 | objects older than `<when>`. This can be used to optimize out |
| 218 | the write of any objects that would be immediately pruned by |
| 219 | a follow-up `git prune`. |
| 220 | |
| 221 | -k:: |
| 222 | --keep-unreachable:: |
| 223 | When used with `-ad`, any unreachable objects from existing |
| 224 | packs will be appended to the end of the packfile instead of |
| 225 | being removed. In addition, any unreachable loose objects will |
| 226 | be packed (and their loose counterparts removed). |
| 227 | |
| 228 | -i:: |
| 229 | --delta-islands:: |
| 230 | Pass the `--delta-islands` option to `git-pack-objects`, see |
| 231 | linkgit:git-pack-objects[1]. |
| 232 | |
| 233 | -g<factor>:: |
| 234 | --geometric=<factor>:: |
| 235 | Arrange resulting pack structure so that each successive pack |
| 236 | contains at least `<factor>` times the number of objects as the |
| 237 | next-largest pack. |
| 238 | + |
| 239 | `git repack` ensures this by determining a "cut" of packfiles that need |
| 240 | to be repacked into one in order to ensure a geometric progression. It |
| 241 | picks the smallest set of packfiles such that as many of the larger |
| 242 | packfiles (by count of objects contained in that pack) may be left |
| 243 | intact. |
| 244 | + |
| 245 | Unlike other repack modes, the set of objects to pack is determined |
| 246 | uniquely by the set of packs being "rolled-up"; in other words, the |
| 247 | packs determined to need to be combined in order to restore a geometric |
| 248 | progression. |
| 249 | + |
| 250 | Loose objects are implicitly included in this "roll-up", without respect to |
| 251 | their reachability. This is subject to change in the future. |
| 252 | + |
| 253 | When combined with `--cruft`, only reachable objects from rolled-up packs |
| 254 | are included in the geometric pack, along with any reachable loose objects. |
| 255 | Unreachable objects (both from rolled-up packs and loose) are collected |
| 256 | into a separate cruft pack. Existing cruft packs are retained. See |
| 257 | `--cruft` above for details. |
| 258 | + |
| 259 | When writing a multi-pack bitmap, `git repack` selects the largest resulting |
| 260 | pack as the preferred pack for object selection by the MIDX (see |
| 261 | linkgit:git-multi-pack-index[1]). |
| 262 | |
| 263 | -m:: |
| 264 | --write-midx[=<mode>]:: |
| 265 | Write a multi-pack index (see linkgit:git-multi-pack-index[1]) |
| 266 | containing the non-redundant packs. The following modes are |
| 267 | available: |
| 268 | + |
| 269 | -- |
| 270 | `default`;; |
| 271 | Write a single MIDX covering all packs. This is the |
| 272 | default when `--write-midx` is given without an |
| 273 | explicit mode. |
| 274 | |
| 275 | `incremental`;; |
| 276 | Write an incremental MIDX chain instead of a single |
| 277 | flat MIDX. |
| 278 | + |
| 279 | Without `--geometric`, a new MIDX layer is appended to the existing |
| 280 | chain (or a new chain is started) containing whatever packs were written |
| 281 | by the repack. Existing layers are preserved as-is. |
| 282 | + |
| 283 | When combined with `--geometric`, the incremental mode maintains a chain |
| 284 | of MIDX layers that is compacted over time using a geometric merging |
| 285 | strategy. Each repack creates a new tip layer containing the newly |
| 286 | written pack(s). Adjacent layers are then merged whenever the newer |
| 287 | layer's object count exceeds `1/repack.midxSplitFactor` of the next |
| 288 | deeper layer's count. Layers that do not meet this condition are |
| 289 | retained as-is. |
| 290 | + |
| 291 | The result is that newer (tip) layers tend to contain many small packs |
| 292 | with relatively few objects, while older (deeper) layers contain fewer, |
| 293 | larger packs covering more objects. Because compaction is driven by the |
| 294 | tip of the chain, newer layers are also rewritten more frequently than |
| 295 | older ones, which are only touched when enough objects have accumulated |
| 296 | to justify merging into them. This keeps the total number of layers |
| 297 | logarithmic relative to the total number of objects. |
| 298 | + |
| 299 | Only packs in the tip MIDX layer are considered as candidates for the |
| 300 | geometric repack; packs in deeper layers are left untouched. If the tip |
| 301 | layer contains fewer packs than `repack.midxNewLayerThreshold`, those |
| 302 | packs are excluded from the geometry entirely, and a new layer is |
| 303 | created for any new pack(s) without disturbing the existing chain. |
| 304 | -- |
| 305 | |
| 306 | --name-hash-version=<n>:: |
| 307 | Provide this argument to the underlying `git pack-objects` process. |
| 308 | See linkgit:git-pack-objects[1] for full details. |
| 309 | |
| 310 | --path-walk:: |
| 311 | Pass the `--path-walk` option to the underlying `git pack-objects` |
| 312 | process. See linkgit:git-pack-objects[1] for full details. |
| 313 | |
| 314 | CONFIGURATION |
| 315 | ------------- |
| 316 | |
| 317 | Various configuration variables affect packing, see |
| 318 | linkgit:git-config[1] (search for "pack" and "delta"). |
| 319 | |
| 320 | By default, the command passes `--delta-base-offset` option to |
| 321 | 'git pack-objects'; this typically results in slightly smaller packs, |
| 322 | but the generated packs are incompatible with versions of Git older than |
| 323 | version 1.4.4. If you need to share your repository with such ancient Git |
| 324 | versions, either directly or via the dumb http protocol, then you |
| 325 | need to set the configuration variable `repack.UseDeltaBaseOffset` to |
| 326 | "false" and repack. Access from old Git versions over the native protocol |
| 327 | is unaffected by this option as the conversion is performed on the fly |
| 328 | as needed in that case. |
| 329 | |
| 330 | Delta compression is not used on objects larger than the |
| 331 | `core.bigFileThreshold` configuration variable and on files with the |
| 332 | attribute `delta` set to false. |
| 333 | |
| 334 | SEE ALSO |
| 335 | -------- |
| 336 | linkgit:git-pack-objects[1] |
| 337 | linkgit:git-prune-packed[1] |
| 338 | |
| 339 | GIT |
| 340 | --- |
| 341 | Part of the linkgit:git[1] suite |