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 vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-08-14
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.rc1.11.gfc6bba66bc
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-MULTI\-PACK\-INDEX" "1" "2023\-08\-14" "Git 2\&.42\&.0\&.rc1\&.11\&.gf" "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 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 Write or verify a multi\-pack\-index (MIDX) file\&.
  41 .SH "OPTIONS"
  42 .PP
  43 \-\-object\-dir=<dir>
  44 .RS 4
  45 Use given directory for the location of Git objects\&. We check
  46 \fB<dir>/packs/multi\-pack\-index\fR
  47 for the current MIDX file, and
  48 \fB<dir>/packs\fR
  49 for the pack\-files to index\&.
  50 .sp
  51 \fB<dir>\fR
  52 must be an alternate of the current repository\&.
  53 .RE
  54 .PP
  55 \-\-[no\-]progress
  56 .RS 4
  57 Turn progress on/off explicitly\&. If neither is specified, progress is shown if standard error is connected to a terminal\&. Supported by sub\-commands
  58 \fBwrite\fR,
  59 \fBverify\fR,
  60 \fBexpire\fR, and `repack\&.
  61 .RE
  62 .sp
  63 The following subcommands are available:
  64 .PP
  65 write
  66 .RS 4
  67 Write a new MIDX file\&. The following options are available for the
  68 \fBwrite\fR
  69 sub\-command:
  70 .PP
  71 \-\-preferred\-pack=<pack>
  72 .RS 4
  73 Optionally specify the tie\-breaking pack used when multiple packs contain the same object\&.
  74 \fB<pack>\fR
  75 must contain at least one object\&. If not given, ties are broken in favor of the pack with the lowest mtime\&.
  76 .RE
  77 .PP
  78 \-\-[no\-]bitmap
  79 .RS 4
  80 Control whether or not a multi\-pack bitmap is written\&.
  81 .RE
  82 .PP
  83 \-\-stdin\-packs
  84 .RS 4
  85 Write a multi\-pack index containing only the set of line\-delimited pack index basenames provided over stdin\&.
  86 .RE
  87 .PP
  88 \-\-refs\-snapshot=<path>
  89 .RS 4
  90 With
  91 \fB\-\-bitmap\fR, optionally specify a file which contains a "refs snapshot" taken prior to repacking\&.
  92 .sp
  93 A reference snapshot is composed of line\-delimited OIDs corresponding to the reference tips, usually taken by
  94 \fBgit repack\fR
  95 prior to generating a new pack\&. A line may optionally start with a
  96 \fB+\fR
  97 character to indicate that the reference which corresponds to that OID is "preferred" (see
  98 \fBgit-config\fR(1)\*(Aqs
  99 \fBpack\&.preferBitmapTips\fR\&.)
 100 .sp
 101 The file given at
 102 \fB<path>\fR
 103 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
 104 \fB+\fR
 105 marker)\&.
 106 .RE
 107 .RE
 108 .PP
 109 verify
 110 .RS 4
 111 Verify the contents of the MIDX file\&.
 112 .RE
 113 .PP
 114 expire
 115 .RS 4
 116 Delete the pack\-files that are tracked by the MIDX file, but have no objects referenced by the MIDX (with the exception of
 117 \fB\&.keep\fR
 118 packs and cruft packs)\&. Rewrite the MIDX file afterward to remove all references to these pack\-files\&.
 119 .RE
 120 .PP
 121 repack
 122 .RS 4
 123 Create a new pack\-file containing objects in small pack\-files referenced by the multi\-pack\-index\&. If the size given by the
 124 \fB\-\-batch\-size=<size>\fR
 125 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
 126 \fIgit multi\-pack\-index expire\fR
 127 will delete the pack\-files that were part of this batch\&.
 128 .sp
 129 If
 130 \fBrepack\&.packKeptObjects\fR
 131 is
 132 \fBfalse\fR, then any pack\-files with an associated
 133 \fB\&.keep\fR
 134 file will not be selected for the batch to repack\&.
 135 .RE
 136 .SH "EXAMPLES"
 137 .sp
 138 .RS 4
 139 .ie n \{\
 140 \h'-04'\(bu\h'+03'\c
 141 .\}
 142 .el \{\
 143 .sp -1
 144 .IP \(bu 2.3
 145 .\}
 146 Write a MIDX file for the packfiles in the current
 147 \fB\&.git\fR
 148 directory\&.
 149 .sp
 150 .if n \{\
 151 .RS 4
 152 .\}
 153 .nf
 154 $ git multi\-pack\-index write
 155 .fi
 156 .if n \{\
 157 .RE
 158 .\}
 159 .sp
 160 .RE
 161 .sp
 162 .RS 4
 163 .ie n \{\
 164 \h'-04'\(bu\h'+03'\c
 165 .\}
 166 .el \{\
 167 .sp -1
 168 .IP \(bu 2.3
 169 .\}
 170 Write a MIDX file for the packfiles in the current
 171 \fB\&.git\fR
 172 directory with a corresponding bitmap\&.
 173 .sp
 174 .if n \{\
 175 .RS 4
 176 .\}
 177 .nf
 178 $ git multi\-pack\-index write \-\-preferred\-pack=<pack> \-\-bitmap
 179 .fi
 180 .if n \{\
 181 .RE
 182 .\}
 183 .sp
 184 .RE
 185 .sp
 186 .RS 4
 187 .ie n \{\
 188 \h'-04'\(bu\h'+03'\c
 189 .\}
 190 .el \{\
 191 .sp -1
 192 .IP \(bu 2.3
 193 .\}
 194 Write a MIDX file for the packfiles in an alternate object store\&.
 195 .sp
 196 .if n \{\
 197 .RS 4
 198 .\}
 199 .nf
 200 $ git multi\-pack\-index \-\-object\-dir <alt> write
 201 .fi
 202 .if n \{\
 203 .RE
 204 .\}
 205 .sp
 206 .RE
 207 .sp
 208 .RS 4
 209 .ie n \{\
 210 \h'-04'\(bu\h'+03'\c
 211 .\}
 212 .el \{\
 213 .sp -1
 214 .IP \(bu 2.3
 215 .\}
 216 Verify the MIDX file for the packfiles in the current
 217 \fB\&.git\fR
 218 directory\&.
 219 .sp
 220 .if n \{\
 221 .RS 4
 222 .\}
 223 .nf
 224 $ git multi\-pack\-index verify
 225 .fi
 226 .if n \{\
 227 .RE
 228 .\}
 229 .sp
 230 .RE
 231 .SH "SEE ALSO"
 232 .sp
 233 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\&.
 234 .SH "GIT"
 235 .sp
 236 Part of the \fBgit\fR(1) suite
 237 .SH "NOTES"
 238 .IP " 1." 4
 239 The Multi-Pack-Index Design Document
 240 .RS 4
 241 \%git-htmldocs/technical/multi-pack-index.html
 242 .RE