man1/git-multi-pack-index.1

   1 '\" t
   2 .\"     Title: git-multi-pack-index
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-18
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.1.565.g6531f31ef3
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-MULTI\-PACK\-INDEX" "1" "2024-09-18" "Git 2\&.46\&.1\&.565\&.g6531f3" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-multi-pack-index \- Write and verify multi\-pack\-indexes
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit multi\-pack\-index\fR [\-\-object\-dir=<dir>] [\-\-[no\-]bitmap] <sub\-command>
  36 .fi
  37 .SH "DESCRIPTION"
  38 .sp
  39 Write or verify a multi\-pack\-index (MIDX) file\&.
  40 .SH "OPTIONS"
  41 .PP
  42 \-\-object\-dir=<dir>
  43 .RS 4
  44 Use given directory for the location of Git objects\&. We check
  45 \fB<dir>/packs/multi\-pack\-index\fR
  46 for the current MIDX file, and
  47 \fB<dir>/packs\fR
  48 for the pack\-files to index\&.
  49 .sp
  50 \fB<dir>\fR
  51 must be an alternate of the current repository\&.
  52 .RE
  53 .PP
  54 \-\-[no\-]progress
  55 .RS 4
  56 Turn progress on/off explicitly\&. If neither is specified, progress is shown if standard error is connected to a terminal\&. Supported by sub\-commands
  57 \fBwrite\fR,
  58 \fBverify\fR,
  59 \fBexpire\fR, and `repack\&.
  60 .RE
  61 .sp
  62 The following subcommands are available:
  63 .PP
  64 write
  65 .RS 4
  66 Write a new MIDX file\&. The following options are available for the
  67 \fBwrite\fR
  68 sub\-command:
  69 .PP
  70 \-\-preferred\-pack=<pack>
  71 .RS 4
  72 Optionally specify the tie\-breaking pack used when multiple packs contain the same object\&.
  73 \fB<pack>\fR
  74 must contain at least one object\&. If not given, ties are broken in favor of the pack with the lowest mtime\&.
  75 .RE
  76 .PP
  77 \-\-[no\-]bitmap
  78 .RS 4
  79 Control whether or not a multi\-pack bitmap is written\&.
  80 .RE
  81 .PP
  82 \-\-stdin\-packs
  83 .RS 4
  84 Write a multi\-pack index containing only the set of line\-delimited pack index basenames provided over stdin\&.
  85 .RE
  86 .PP
  87 \-\-refs\-snapshot=<path>
  88 .RS 4
  89 With
  90 \fB\-\-bitmap\fR, optionally specify a file which contains a "refs snapshot" taken prior to repacking\&.
  91 .sp
  92 A reference snapshot is composed of line\-delimited OIDs corresponding to the reference tips, usually taken by
  93 \fBgit repack\fR
  94 prior to generating a new pack\&. A line may optionally start with a
  95 \fB+\fR
  96 character to indicate that the reference which corresponds to that OID is "preferred" (see
  97 \fBgit-config\fR(1)\*(Aqs
  98 \fBpack\&.preferBitmapTips\fR\&.)
  99 .sp
 100 The file given at
 101 \fB<path>\fR
 102 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
 103 \fB+\fR
 104 marker)\&.
 105 .RE
 106 .PP
 107 \-\-incremental
 108 .RS 4
 109 Write an incremental MIDX file containing only objects and packs not present in an existing MIDX layer\&. Migrates non\-incremental MIDXs to incremental ones when necessary\&. Incompatible with
 110 \fB\-\-bitmap\fR\&.
 111 .RE
 112 .RE
 113 .PP
 114 verify
 115 .RS 4
 116 Verify the contents of the MIDX file\&.
 117 .RE
 118 .PP
 119 expire
 120 .RS 4
 121 Delete the pack\-files that are tracked by the MIDX file, but have no objects referenced by the MIDX (with the exception of
 122 \fB\&.keep\fR
 123 packs and cruft packs)\&. Rewrite the MIDX file afterward to remove all references to these pack\-files\&.
 124 .if n \{\
 125 .sp
 126 .\}
 127 .RS 4
 128 .it 1 an-trap
 129 .nr an-no-space-flag 1
 130 .nr an-break-flag 1
 131 .br
 132 .ps +1
 133 \fBNote\fR
 134 .ps -1
 135 .br
 136 this mode is incompatible with incremental MIDX files\&.
 137 .sp .5v
 138 .RE
 139 .RE
 140 .PP
 141 repack
 142 .RS 4
 143 Create a new pack\-file containing objects in small pack\-files referenced by the multi\-pack\-index\&. If the size given by the
 144 \fB\-\-batch\-size=<size>\fR
 145 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
 146 \fIgit multi\-pack\-index expire\fR
 147 will delete the pack\-files that were part of this batch\&.
 148 .sp
 149 If
 150 \fBrepack\&.packKeptObjects\fR
 151 is
 152 \fBfalse\fR, then any pack\-files with an associated
 153 \fB\&.keep\fR
 154 file will not be selected for the batch to repack\&.
 155 .if n \{\
 156 .sp
 157 .\}
 158 .RS 4
 159 .it 1 an-trap
 160 .nr an-no-space-flag 1
 161 .nr an-break-flag 1
 162 .br
 163 .ps +1
 164 \fBNote\fR
 165 .ps -1
 166 .br
 167 this mode is incompatible with incremental MIDX files\&.
 168 .sp .5v
 169 .RE
 170 .RE
 171 .SH "EXAMPLES"
 172 .sp
 173 .RS 4
 174 .ie n \{\
 175 \h'-04'\(bu\h'+03'\c
 176 .\}
 177 .el \{\
 178 .sp -1
 179 .IP \(bu 2.3
 180 .\}
 181 Write a MIDX file for the packfiles in the current
 182 \fB\&.git\fR
 183 directory\&.
 184 .sp
 185 .if n \{\
 186 .RS 4
 187 .\}
 188 .nf
 189 $ git multi\-pack\-index write
 190 .fi
 191 .if n \{\
 192 .RE
 193 .\}
 194 .RE
 195 .sp
 196 .RS 4
 197 .ie n \{\
 198 \h'-04'\(bu\h'+03'\c
 199 .\}
 200 .el \{\
 201 .sp -1
 202 .IP \(bu 2.3
 203 .\}
 204 Write a MIDX file for the packfiles in the current
 205 \fB\&.git\fR
 206 directory with a corresponding bitmap\&.
 207 .sp
 208 .if n \{\
 209 .RS 4
 210 .\}
 211 .nf
 212 $ git multi\-pack\-index write \-\-preferred\-pack=<pack> \-\-bitmap
 213 .fi
 214 .if n \{\
 215 .RE
 216 .\}
 217 .RE
 218 .sp
 219 .RS 4
 220 .ie n \{\
 221 \h'-04'\(bu\h'+03'\c
 222 .\}
 223 .el \{\
 224 .sp -1
 225 .IP \(bu 2.3
 226 .\}
 227 Write a MIDX file for the packfiles in an alternate object store\&.
 228 .sp
 229 .if n \{\
 230 .RS 4
 231 .\}
 232 .nf
 233 $ git multi\-pack\-index \-\-object\-dir <alt> write
 234 .fi
 235 .if n \{\
 236 .RE
 237 .\}
 238 .RE
 239 .sp
 240 .RS 4
 241 .ie n \{\
 242 \h'-04'\(bu\h'+03'\c
 243 .\}
 244 .el \{\
 245 .sp -1
 246 .IP \(bu 2.3
 247 .\}
 248 Verify the MIDX file for the packfiles in the current
 249 \fB\&.git\fR
 250 directory\&.
 251 .sp
 252 .if n \{\
 253 .RS 4
 254 .\}
 255 .nf
 256 $ git multi\-pack\-index verify
 257 .fi
 258 .if n \{\
 259 .RE
 260 .\}
 261 .RE
 262 .SH "SEE ALSO"
 263 .sp
 264 See \m[blue]\fBThe Multi\-Pack\-Index Design Document\fR\m[]\&\s-2\u[1]\d\s+2 and \fBgitformat-pack\fR(5) for more information on the multi\-pack\-index feature and its file format\&.
 265 .SH "GIT"
 266 .sp
 267 Part of the \fBgit\fR(1) suite
 268 .SH "NOTES"
 269 .IP " 1." 4
 270 The Multi-Pack-Index Design Document
 271 .RS 4
 272 \%git-htmldocs/technical/multi-pack-index.html
 273 .RE