| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" |
| 2 | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| 4 | <head> |
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 6 | <meta name="generator" content="AsciiDoc 8.4.5" /> |
| 7 | <title>git-fast-import(1)</title> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 8 | <style type="text/css"> |
| 9 | /* Debug borders */ |
| 10 | p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { |
| 11 | /* |
| 12 | border: 1px solid red; |
| 13 | */ |
| 14 | } |
| 15 | |
| 16 | body { |
| 17 | margin: 1em 5% 1em 5%; |
| 18 | } |
| 19 | |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 20 | a { |
| 21 | color: blue; |
| 22 | text-decoration: underline; |
| 23 | } |
| 24 | a:visited { |
| 25 | color: fuchsia; |
| 26 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 27 | |
| 28 | em { |
| 29 | font-style: italic; |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 30 | color: navy; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 31 | } |
| 32 | |
| 33 | strong { |
| 34 | font-weight: bold; |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 35 | color: #083194; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 36 | } |
| 37 | |
| 38 | tt { |
| 39 | color: navy; |
| 40 | } |
| 41 | |
| 42 | h1, h2, h3, h4, h5, h6 { |
| 43 | color: #527bbd; |
| 44 | font-family: sans-serif; |
| 45 | margin-top: 1.2em; |
| 46 | margin-bottom: 0.5em; |
| 47 | line-height: 1.3; |
| 48 | } |
| 49 | |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 50 | h1, h2, h3 { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 51 | border-bottom: 2px solid silver; |
| 52 | } |
| 53 | h2 { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 54 | padding-top: 0.5em; |
| 55 | } |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 56 | h3 { |
| 57 | float: left; |
| 58 | } |
| 59 | h3 + * { |
| 60 | clear: left; |
| 61 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 62 | |
| 63 | div.sectionbody { |
| 64 | font-family: serif; |
| 65 | margin-left: 0; |
| 66 | } |
| 67 | |
| 68 | hr { |
| 69 | border: 1px solid silver; |
| 70 | } |
| 71 | |
| 72 | p { |
| 73 | margin-top: 0.5em; |
| 74 | margin-bottom: 0.5em; |
| 75 | } |
| 76 | |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 77 | ul, ol, li > p { |
| 78 | margin-top: 0; |
| 79 | } |
| 80 | |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 81 | pre { |
| 82 | padding: 0; |
| 83 | margin: 0; |
| 84 | } |
| 85 | |
| 86 | span#author { |
| 87 | color: #527bbd; |
| 88 | font-family: sans-serif; |
| 89 | font-weight: bold; |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 90 | font-size: 1.1em; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 91 | } |
| 92 | span#email { |
| 93 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 94 | span#revnumber, span#revdate, span#revremark { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 95 | font-family: sans-serif; |
| 96 | } |
| 97 | |
| 98 | div#footer { |
| 99 | font-family: sans-serif; |
| 100 | font-size: small; |
| 101 | border-top: 2px solid silver; |
| 102 | padding-top: 0.5em; |
| 103 | margin-top: 4.0em; |
| 104 | } |
| 105 | div#footer-text { |
| 106 | float: left; |
| 107 | padding-bottom: 0.5em; |
| 108 | } |
| 109 | div#footer-badges { |
| 110 | float: right; |
| 111 | padding-bottom: 0.5em; |
| 112 | } |
| 113 | |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 114 | div#preamble { |
| 115 | margin-top: 1.5em; |
| 116 | margin-bottom: 1.5em; |
| 117 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 118 | div.tableblock, div.imageblock, div.exampleblock, div.verseblock, |
| 119 | div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, |
| 120 | div.admonitionblock { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 121 | margin-top: 1.5em; |
| 122 | margin-bottom: 1.5em; |
| 123 | } |
| 124 | div.admonitionblock { |
| 125 | margin-top: 2.5em; |
| 126 | margin-bottom: 2.5em; |
| 127 | } |
| 128 | |
| 129 | div.content { /* Block element content. */ |
| 130 | padding: 0; |
| 131 | } |
| 132 | |
| 133 | /* Block element titles. */ |
| 134 | div.title, caption.title { |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 135 | color: #527bbd; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 136 | font-family: sans-serif; |
| 137 | font-weight: bold; |
| 138 | text-align: left; |
| 139 | margin-top: 1.0em; |
| 140 | margin-bottom: 0.5em; |
| 141 | } |
| 142 | div.title + * { |
| 143 | margin-top: 0; |
| 144 | } |
| 145 | |
| 146 | td div.title:first-child { |
| 147 | margin-top: 0.0em; |
| 148 | } |
| 149 | div.content div.title:first-child { |
| 150 | margin-top: 0.0em; |
| 151 | } |
| 152 | div.content + div.title { |
| 153 | margin-top: 0.0em; |
| 154 | } |
| 155 | |
| 156 | div.sidebarblock > div.content { |
| 157 | background: #ffffee; |
| 158 | border: 1px solid silver; |
| 159 | padding: 0.5em; |
| 160 | } |
| 161 | |
| 162 | div.listingblock > div.content { |
| 163 | border: 1px solid silver; |
| 164 | background: #f4f4f4; |
| 165 | padding: 0.5em; |
| 166 | } |
| 167 | |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 168 | div.quoteblock { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 169 | padding-left: 2.0em; |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 170 | margin-right: 10%; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 171 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 172 | div.quoteblock > div.attribution { |
| 173 | padding-top: 0.5em; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 174 | text-align: right; |
| 175 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 176 | |
| 177 | div.verseblock { |
| 178 | padding-left: 2.0em; |
| 179 | margin-right: 10%; |
| 180 | } |
| 181 | div.verseblock > div.content { |
| 182 | white-space: pre; |
| 183 | } |
| 184 | div.verseblock > div.attribution { |
| 185 | padding-top: 0.75em; |
| 186 | text-align: left; |
| 187 | } |
| 188 | /* DEPRECATED: Pre version 8.2.7 verse style literal block. */ |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 189 | div.verseblock + div.attribution { |
| 190 | text-align: left; |
| 191 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 192 | |
| 193 | div.admonitionblock .icon { |
| 194 | vertical-align: top; |
| 195 | font-size: 1.1em; |
| 196 | font-weight: bold; |
| 197 | text-decoration: underline; |
| 198 | color: #527bbd; |
| 199 | padding-right: 0.5em; |
| 200 | } |
| 201 | div.admonitionblock td.content { |
| 202 | padding-left: 0.5em; |
| 203 | border-left: 2px solid silver; |
| 204 | } |
| 205 | |
| 206 | div.exampleblock > div.content { |
| 207 | border-left: 2px solid silver; |
| 208 | padding: 0.5em; |
| 209 | } |
| 210 | |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 211 | div.imageblock div.content { padding-left: 0; } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 212 | span.image img { border-style: none; } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 213 | a.image:visited { color: white; } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 214 | |
| 215 | dl { |
| 216 | margin-top: 0.8em; |
| 217 | margin-bottom: 0.8em; |
| 218 | } |
| 219 | dt { |
| 220 | margin-top: 0.5em; |
| 221 | margin-bottom: 0; |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 222 | font-style: normal; |
| 223 | color: navy; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 224 | } |
| 225 | dd > *:first-child { |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 226 | margin-top: 0.1em; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 227 | } |
| 228 | |
| 229 | ul, ol { |
| 230 | list-style-position: outside; |
| 231 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 232 | ol.arabic { |
| 233 | list-style-type: decimal; |
| 234 | } |
| 235 | ol.loweralpha { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 236 | list-style-type: lower-alpha; |
| 237 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 238 | ol.upperalpha { |
| 239 | list-style-type: upper-alpha; |
| 240 | } |
| 241 | ol.lowerroman { |
| 242 | list-style-type: lower-roman; |
| 243 | } |
| 244 | ol.upperroman { |
| 245 | list-style-type: upper-roman; |
| 246 | } |
| 247 | |
| 248 | div.compact ul, div.compact ol, |
| 249 | div.compact p, div.compact p, |
| 250 | div.compact div, div.compact div { |
| 251 | margin-top: 0.1em; |
| 252 | margin-bottom: 0.1em; |
| 253 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 254 | |
| 255 | div.tableblock > table { |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 256 | border: 3px solid #527bbd; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 257 | } |
| 258 | thead { |
| 259 | font-family: sans-serif; |
| 260 | font-weight: bold; |
| 261 | } |
| 262 | tfoot { |
| 263 | font-weight: bold; |
| 264 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 265 | td > div.verse { |
| 266 | white-space: pre; |
| 267 | } |
| 268 | p.table { |
| 269 | margin-top: 0; |
| 270 | } |
| 271 | /* Because the table frame attribute is overriden by CSS in most browsers. */ |
| 272 | div.tableblock > table[frame="void"] { |
| 273 | border-style: none; |
| 274 | } |
| 275 | div.tableblock > table[frame="hsides"] { |
| 276 | border-left-style: none; |
| 277 | border-right-style: none; |
| 278 | } |
| 279 | div.tableblock > table[frame="vsides"] { |
| 280 | border-top-style: none; |
| 281 | border-bottom-style: none; |
| 282 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 283 | |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 284 | |
| 285 | div.hdlist { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 286 | margin-top: 0.8em; |
| 287 | margin-bottom: 0.8em; |
| 288 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 289 | div.hdlist tr { |
| 290 | padding-bottom: 15px; |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 291 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 292 | dt.hdlist1.strong, td.hdlist1.strong { |
| 293 | font-weight: bold; |
| 294 | } |
| 295 | td.hdlist1 { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 296 | vertical-align: top; |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 297 | font-style: normal; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 298 | padding-right: 0.8em; |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 299 | color: navy; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 300 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 301 | td.hdlist2 { |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 302 | vertical-align: top; |
| 303 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 304 | div.hdlist.compact tr { |
| 305 | margin: 0; |
| 306 | padding-bottom: 0; |
| 307 | } |
| 308 | |
| 309 | .comment { |
| 310 | background: yellow; |
| 311 | } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 312 | |
| 313 | @media print { |
| 314 | div#footer-badges { display: none; } |
| 315 | } |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 316 | |
| 317 | div#toctitle { |
| 318 | color: #527bbd; |
| 319 | font-family: sans-serif; |
| 320 | font-size: 1.1em; |
| 321 | font-weight: bold; |
| 322 | margin-top: 1.0em; |
| 323 | margin-bottom: 0.1em; |
| 324 | } |
| 325 | |
| 326 | div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { |
| 327 | margin-top: 0; |
| 328 | margin-bottom: 0; |
| 329 | } |
| 330 | div.toclevel2 { |
| 331 | margin-left: 2em; |
| 332 | font-size: 0.9em; |
| 333 | } |
| 334 | div.toclevel3 { |
| 335 | margin-left: 4em; |
| 336 | font-size: 0.9em; |
| 337 | } |
| 338 | div.toclevel4 { |
| 339 | margin-left: 6em; |
| 340 | font-size: 0.9em; |
| 341 | } |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 342 | /* Overrides for manpage documents */ |
| 343 | h1 { |
| 344 | padding-top: 0.5em; |
| 345 | padding-bottom: 0.5em; |
| 346 | border-top: 2px solid silver; |
| 347 | border-bottom: 2px solid silver; |
| 348 | } |
| 349 | h2 { |
| 350 | border-style: none; |
| 351 | } |
| 352 | div.sectionbody { |
| 353 | margin-left: 5%; |
| 354 | } |
| 355 | |
| 356 | @media print { |
| 357 | div#toc { display: none; } |
| 358 | } |
| 359 | |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 360 | /* Workarounds for IE6's broken and incomplete CSS2. */ |
| 361 | |
| 362 | div.sidebar-content { |
| 363 | background: #ffffee; |
| 364 | border: 1px solid silver; |
| 365 | padding: 0.5em; |
| 366 | } |
| 367 | div.sidebar-title, div.image-title { |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 368 | color: #527bbd; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 369 | font-family: sans-serif; |
| 370 | font-weight: bold; |
| 371 | margin-top: 0.0em; |
| 372 | margin-bottom: 0.5em; |
| 373 | } |
| 374 | |
| 375 | div.listingblock div.content { |
| 376 | border: 1px solid silver; |
| 377 | background: #f4f4f4; |
| 378 | padding: 0.5em; |
| 379 | } |
| 380 | |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 381 | div.quoteblock-attribution { |
| 382 | padding-top: 0.5em; |
| 383 | text-align: right; |
| 384 | } |
| 385 | |
| 386 | div.verseblock-content { |
| 387 | white-space: pre; |
| 388 | } |
| 389 | div.verseblock-attribution { |
| 390 | padding-top: 0.75em; |
| 391 | text-align: left; |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 392 | } |
| 393 | |
| 394 | div.exampleblock-content { |
| 395 | border-left: 2px solid silver; |
| 396 | padding-left: 0.5em; |
| 397 | } |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 398 | |
| 399 | /* IE6 sets dynamically generated links as visited. */ |
| 400 | div#toc a:visited { color: blue; } |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 401 | </style> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 402 | </head> |
| 403 | <body> |
| 404 | <div id="header"> |
| 405 | <h1> |
| 406 | git-fast-import(1) Manual Page |
| 407 | </h1> |
| 408 | <h2>NAME</h2> |
| 409 | <div class="sectionbody"> |
| 410 | <p>git-fast-import - |
| Junio C Hamano | 053827f | 2007-02-14 07:23:58 | [diff] [blame] | 411 | Backend for fast Git data importers |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 412 | </p> |
| 413 | </div> |
| 414 | </div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 415 | <h2 id="_synopsis">SYNOPSIS</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 416 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 417 | <div class="paragraph"><p>frontend | <em>git fast-import</em> [options]</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 418 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 419 | <h2 id="_description">DESCRIPTION</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 420 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 421 | <div class="paragraph"><p>This program is usually not what the end user wants to run directly. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 422 | Most end users want to use one of the existing frontend programs, |
| 423 | which parses a specific type of foreign source and feeds the contents |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 424 | stored there to <em>git fast-import</em>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 425 | <div class="paragraph"><p>fast-import reads a mixed command/data stream from standard input and |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 426 | writes one or more packfiles directly into the current repository. |
| 427 | When EOF is received on standard input, fast import writes out |
| 428 | updated branch and tag refs, fully updating the current repository |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 429 | with the newly imported data.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 430 | <div class="paragraph"><p>The fast-import backend itself can import into an empty repository (one that |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 431 | has already been initialized by <em>git init</em>) or incrementally |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 432 | update an existing populated repository. Whether or not incremental |
| 433 | imports are supported from a particular foreign source depends on |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 434 | the frontend program in use.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 435 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 436 | <h2 id="_options">OPTIONS</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 437 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 438 | <div class="dlist"><dl> |
| 439 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 440 | --date-format=<fmt> |
| 441 | </dt> |
| 442 | <dd> |
| 443 | <p> |
| 444 | Specify the type of dates the frontend will supply to |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 445 | fast-import within <tt>author</tt>, <tt>committer</tt> and <tt>tagger</tt> commands. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 446 | See “Date Formats” below for details about which formats |
| 447 | are supported, and their syntax. |
| 448 | </p> |
| 449 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 450 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 451 | --force |
| 452 | </dt> |
| 453 | <dd> |
| 454 | <p> |
| 455 | Force updating modified existing branches, even if doing |
| 456 | so would cause commits to be lost (as the new commit does |
| 457 | not contain the old commit). |
| 458 | </p> |
| 459 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 460 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 461 | --max-pack-size=<n> |
| 462 | </dt> |
| 463 | <dd> |
| 464 | <p> |
| Junio C Hamano | d330432 | 2010-02-05 03:28:27 | [diff] [blame] | 465 | Maximum size of each output packfile. |
| Junio C Hamano | 4fdccb2 | 2010-02-19 09:58:14 | [diff] [blame] | 466 | The default is unlimited. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 467 | </p> |
| 468 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 469 | <dt class="hdlist1"> |
| Junio C Hamano | 5c246f2 | 2010-02-03 07:34:53 | [diff] [blame] | 470 | --big-file-threshold=<n> |
| 471 | </dt> |
| 472 | <dd> |
| 473 | <p> |
| 474 | Maximum size of a blob that fast-import will attempt to |
| 475 | create a delta for, expressed in bytes. The default is 512m |
| 476 | (512 MiB). Some importers may wish to lower this on systems |
| 477 | with constrained memory. |
| 478 | </p> |
| 479 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 480 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 481 | --depth=<n> |
| 482 | </dt> |
| 483 | <dd> |
| 484 | <p> |
| 485 | Maximum delta depth, for blob and tree deltification. |
| 486 | Default is 10. |
| 487 | </p> |
| 488 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 489 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 490 | --active-branches=<n> |
| 491 | </dt> |
| 492 | <dd> |
| 493 | <p> |
| 494 | Maximum number of branches to maintain active at once. |
| 495 | See “Memory Utilization” below for details. Default is 5. |
| 496 | </p> |
| 497 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 498 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 499 | --export-marks=<file> |
| 500 | </dt> |
| 501 | <dd> |
| 502 | <p> |
| 503 | Dumps the internal marks table to <file> when complete. |
| 504 | Marks are written one per line as <tt>:markid SHA-1</tt>. |
| 505 | Frontends can use this file to validate imports after they |
| Junio C Hamano | d15328a | 2007-03-09 09:06:40 | [diff] [blame] | 506 | have been completed, or to save the marks table across |
| 507 | incremental runs. As <file> is only opened and truncated |
| 508 | at checkpoint (or completion) the same path can also be |
| 509 | safely given to --import-marks. |
| 510 | </p> |
| 511 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 512 | <dt class="hdlist1"> |
| Junio C Hamano | d15328a | 2007-03-09 09:06:40 | [diff] [blame] | 513 | --import-marks=<file> |
| 514 | </dt> |
| 515 | <dd> |
| 516 | <p> |
| 517 | Before processing any input, load the marks specified in |
| 518 | <file>. The input file must exist, must be readable, and |
| 519 | must use the same format as produced by --export-marks. |
| 520 | Multiple options may be supplied to import more than one |
| 521 | set of marks. If a mark is defined to different values, |
| 522 | the last file wins. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 523 | </p> |
| 524 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 525 | <dt class="hdlist1"> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 526 | --relative-marks |
| 527 | </dt> |
| 528 | <dd> |
| 529 | <p> |
| 530 | After specifying --relative-marks= the paths specified |
| 531 | with --import-marks= and --export-marks= are relative |
| 532 | to an internal directory in the current repository. |
| 533 | In git-fast-import this means that the paths are relative |
| 534 | to the .git/info/fast-import directory. However, other |
| 535 | importers may use a different location. |
| 536 | </p> |
| 537 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 538 | <dt class="hdlist1"> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 539 | --no-relative-marks |
| 540 | </dt> |
| 541 | <dd> |
| 542 | <p> |
| 543 | Negates a previous --relative-marks. Allows for combining |
| 544 | relative and non-relative marks by interweaving |
| 545 | --(no-)-relative-marks= with the --(import|export)-marks= |
| 546 | options. |
| 547 | </p> |
| 548 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 549 | <dt class="hdlist1"> |
| Junio C Hamano | 9dd8bb0 | 2007-02-12 07:15:35 | [diff] [blame] | 550 | --export-pack-edges=<file> |
| 551 | </dt> |
| 552 | <dd> |
| 553 | <p> |
| 554 | After creating a packfile, print a line of data to |
| 555 | <file> listing the filename of the packfile and the last |
| 556 | commit on each branch that was written to that packfile. |
| 557 | This information may be useful after importing projects |
| 558 | whose total object set exceeds the 4 GiB packfile limit, |
| 559 | as these commits can be used as edge points during calls |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 560 | to <em>git pack-objects</em>. |
| Junio C Hamano | 9dd8bb0 | 2007-02-12 07:15:35 | [diff] [blame] | 561 | </p> |
| 562 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 563 | <dt class="hdlist1"> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 564 | --quiet |
| 565 | </dt> |
| 566 | <dd> |
| 567 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 568 | Disable all non-fatal output, making fast-import silent when it |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 569 | is successful. This option disables the output shown by |
| 570 | --stats. |
| 571 | </p> |
| 572 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 573 | <dt class="hdlist1"> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 574 | --stats |
| 575 | </dt> |
| 576 | <dd> |
| 577 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 578 | Display some basic statistics about the objects fast-import has |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 579 | created, the packfiles they were stored into, and the |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 580 | memory used by fast-import during this run. Showing this output |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 581 | is currently the default, but can be disabled with --quiet. |
| 582 | </p> |
| 583 | </dd> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 584 | </dl></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 585 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 586 | <h2 id="_performance">Performance</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 587 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 588 | <div class="paragraph"><p>The design of fast-import allows it to import large projects in a minimum |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 589 | amount of memory usage and processing time. Assuming the frontend |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 590 | is able to keep up with fast-import and feed it a constant stream of data, |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 591 | import times for projects holding 10+ years of history and containing |
| 592 | 100,000+ individual commits are generally completed in just 1-2 |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 593 | hours on quite modest (~$2,000 USD) hardware.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 594 | <div class="paragraph"><p>Most bottlenecks appear to be in foreign source data access (the |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 595 | source just cannot extract revisions fast enough) or disk IO (fast-import |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 596 | writes as fast as the disk will take the data). Imports will run |
| 597 | faster if the source data is stored on a different drive than the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 598 | destination Git repository (due to less IO contention).</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 599 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 600 | <h2 id="_development_cost">Development Cost</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 601 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 602 | <div class="paragraph"><p>A typical frontend for fast-import tends to weigh in at approximately 200 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 603 | lines of Perl/Python/Ruby code. Most developers have been able to |
| 604 | create working importers in just a couple of hours, even though it |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 605 | is their first exposure to fast-import, and sometimes even to Git. This is |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 606 | an ideal situation, given that most conversion tools are throw-away |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 607 | (use once, and never look back).</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 608 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 609 | <h2 id="_parallel_operation">Parallel Operation</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 610 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 611 | <div class="paragraph"><p>Like <em>git push</em> or <em>git fetch</em>, imports handled by fast-import are safe to |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 612 | run alongside parallel <tt>git repack -a -d</tt> or <tt>git gc</tt> invocations, |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 613 | or any other Git operation (including <em>git prune</em>, as loose objects |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 614 | are never used by fast-import).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 615 | <div class="paragraph"><p>fast-import does not lock the branch or tag refs it is actively importing. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 616 | After the import, during its ref update phase, fast-import tests each |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 617 | existing branch ref to verify the update will be a fast-forward |
| 618 | update (the commit stored in the ref is contained in the new |
| 619 | history of the commit to be written). If the update is not a |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 620 | fast-forward update, fast-import will skip updating that ref and instead |
| 621 | prints a warning message. fast-import will always attempt to update all |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 622 | branch refs, and does not stop on the first failure.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 623 | <div class="paragraph"><p>Branch updates can be forced with --force, but it’s recommended that |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 624 | this only be used on an otherwise quiet repository. Using --force |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 625 | is not necessary for an initial import into an empty repository.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 626 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 627 | <h2 id="_technical_discussion">Technical Discussion</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 628 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 629 | <div class="paragraph"><p>fast-import tracks a set of branches in memory. Any branch can be created |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 630 | or modified at any point during the import process by sending a |
| 631 | <tt>commit</tt> command on the input stream. This design allows a frontend |
| 632 | program to process an unlimited number of branches simultaneously, |
| 633 | generating commits in the order they are available from the source |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 634 | data. It also simplifies the frontend programs considerably.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 635 | <div class="paragraph"><p>fast-import does not use or alter the current working directory, or any |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 636 | file within it. (It does however update the current Git repository, |
| 637 | as referenced by <tt>GIT_DIR</tt>.) Therefore an import frontend may use |
| 638 | the working directory for its own purposes, such as extracting file |
| 639 | revisions from the foreign source. This ignorance of the working |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 640 | directory also allows fast-import to run very quickly, as it does not |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 641 | need to perform any costly file update operations when switching |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 642 | between branches.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 643 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 644 | <h2 id="_input_format">Input Format</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 645 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 646 | <div class="paragraph"><p>With the exception of raw file data (which Git does not interpret) |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 647 | the fast-import input format is text (ASCII) based. This text based |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 648 | format simplifies development and debugging of frontend programs, |
| 649 | especially when a higher level language such as Perl, Python or |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 650 | Ruby is being used.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 651 | <div class="paragraph"><p>fast-import is very strict about its input. Where we say SP below we mean |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 652 | <strong>exactly</strong> one space. Likewise LF means one (and only one) linefeed. |
| 653 | Supplying additional whitespace characters will cause unexpected |
| 654 | results, such as branch names or file names with leading or trailing |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 655 | spaces in their name, or early termination of fast-import when it encounters |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 656 | unexpected input.</p></div> |
| 657 | <h3 id="_stream_comments">Stream Comments</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 658 | <div class="paragraph"><p>To aid in debugging frontends fast-import ignores any line that |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 659 | begins with <tt>#</tt> (ASCII pound/hash) up to and including the line |
| 660 | ending <tt>LF</tt>. A comment line may contain any sequence of bytes |
| 661 | that does not contain an LF and therefore may be used to include |
| 662 | any detailed debugging information that might be specific to the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 663 | frontend and useful when inspecting a fast-import data stream.</p></div> |
| 664 | <h3 id="_date_formats">Date Formats</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 665 | <div class="paragraph"><p>The following date formats are supported. A frontend should select |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 666 | the format it will use for this import by passing the format name |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 667 | in the --date-format=<fmt> command line option.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 668 | <div class="dlist"><dl> |
| 669 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 670 | <tt>raw</tt> |
| 671 | </dt> |
| 672 | <dd> |
| 673 | <p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 674 | This is the Git native format and is <tt><time> SP <offutc></tt>. |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 675 | It is also fast-import’s default format, if --date-format was |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 676 | not specified. |
| 677 | </p> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 678 | <div class="paragraph"><p>The time of the event is specified by <tt><time></tt> as the number of |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 679 | seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 680 | written as an ASCII decimal integer.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 681 | <div class="paragraph"><p>The local offset is specified by <tt><offutc></tt> as a positive or negative |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 682 | offset from UTC. For example EST (which is 5 hours behind UTC) |
| 683 | would be expressed in <tt><tz></tt> by “-0500” while UTC is “+0000”. |
| 684 | The local offset does not affect <tt><time></tt>; it is used only as an |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 685 | advisement to help formatting routines display the timestamp.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 686 | <div class="paragraph"><p>If the local offset is not available in the source material, use |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 687 | “+0000”, or the most common local offset. For example many |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 688 | organizations have a CVS repository which has only ever been accessed |
| 689 | by users who are located in the same location and timezone. In this |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 690 | case a reasonable offset from UTC could be assumed.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 691 | <div class="paragraph"><p>Unlike the <tt>rfc2822</tt> format, this format is very strict. Any |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 692 | variation in formatting will cause fast-import to reject the value.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 693 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 694 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 695 | <tt>rfc2822</tt> |
| 696 | </dt> |
| 697 | <dd> |
| 698 | <p> |
| 699 | This is the standard email format as described by RFC 2822. |
| 700 | </p> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 701 | <div class="paragraph"><p>An example value is “Tue Feb 6 11:22:18 2007 -0500”. The Git |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 702 | parser is accurate, but a little on the lenient side. It is the |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 703 | same parser used by <em>git am</em> when applying patches |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 704 | received from email.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 705 | <div class="paragraph"><p>Some malformed strings may be accepted as valid dates. In some of |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 706 | these cases Git will still be able to obtain the correct date from |
| 707 | the malformed string. There are also some types of malformed |
| 708 | strings which Git will parse wrong, and yet consider valid. |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 709 | Seriously malformed strings will be rejected.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 710 | <div class="paragraph"><p>Unlike the <tt>raw</tt> format above, the timezone/UTC offset information |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 711 | contained in an RFC 2822 date string is used to adjust the date |
| 712 | value to UTC prior to storage. Therefore it is important that |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 713 | this information be as accurate as possible.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 714 | <div class="paragraph"><p>If the source material uses RFC 2822 style dates, |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 715 | the frontend should let fast-import handle the parsing and conversion |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 716 | (rather than attempting to do it itself) as the Git parser has |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 717 | been well tested in the wild.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 718 | <div class="paragraph"><p>Frontends should prefer the <tt>raw</tt> format if the source material |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 719 | already uses UNIX-epoch format, can be coaxed to give dates in that |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 720 | format, or its format is easily convertible to it, as there is no |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 721 | ambiguity in parsing.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 722 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 723 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 724 | <tt>now</tt> |
| 725 | </dt> |
| 726 | <dd> |
| 727 | <p> |
| 728 | Always use the current time and timezone. The literal |
| 729 | <tt>now</tt> must always be supplied for <tt><when></tt>. |
| 730 | </p> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 731 | <div class="paragraph"><p>This is a toy format. The current time and timezone of this system |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 732 | is always copied into the identity string at the time it is being |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 733 | created by fast-import. There is no way to specify a different time or |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 734 | timezone.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 735 | <div class="paragraph"><p>This particular format is supplied as it’s short to implement and |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 736 | may be useful to a process that wants to create a new commit |
| 737 | right now, without needing to use a working directory or |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 738 | <em>git update-index</em>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 739 | <div class="paragraph"><p>If separate <tt>author</tt> and <tt>committer</tt> commands are used in a <tt>commit</tt> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 740 | the timestamps may not match, as the system clock will be polled |
| 741 | twice (once for each command). The only way to ensure that both |
| 742 | author and committer identity information has the same timestamp |
| 743 | is to omit <tt>author</tt> (thus copying from <tt>committer</tt>) or to use a |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 744 | date format other than <tt>now</tt>.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 745 | </dd> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 746 | </dl></div> |
| 747 | <h3 id="_commands">Commands</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 748 | <div class="paragraph"><p>fast-import accepts several commands to update the current repository |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 749 | and control the current import process. More detailed discussion |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 750 | (with examples) of each command follows later.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 751 | <div class="dlist"><dl> |
| 752 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 753 | <tt>commit</tt> |
| 754 | </dt> |
| 755 | <dd> |
| 756 | <p> |
| 757 | Creates a new branch or updates an existing branch by |
| 758 | creating a new commit and updating the branch to point at |
| 759 | the newly created commit. |
| 760 | </p> |
| 761 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 762 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 763 | <tt>tag</tt> |
| 764 | </dt> |
| 765 | <dd> |
| 766 | <p> |
| 767 | Creates an annotated tag object from an existing commit or |
| 768 | branch. Lightweight tags are not supported by this command, |
| 769 | as they are not recommended for recording meaningful points |
| 770 | in time. |
| 771 | </p> |
| 772 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 773 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 774 | <tt>reset</tt> |
| 775 | </dt> |
| 776 | <dd> |
| 777 | <p> |
| 778 | Reset an existing branch (or a new branch) to a specific |
| 779 | revision. This command must be used to change a branch to |
| 780 | a specific revision without making a commit on it. |
| 781 | </p> |
| 782 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 783 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 784 | <tt>blob</tt> |
| 785 | </dt> |
| 786 | <dd> |
| 787 | <p> |
| 788 | Convert raw file data into a blob, for future use in a |
| 789 | <tt>commit</tt> command. This command is optional and is not |
| 790 | needed to perform an import. |
| 791 | </p> |
| 792 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 793 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 794 | <tt>checkpoint</tt> |
| 795 | </dt> |
| 796 | <dd> |
| 797 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 798 | Forces fast-import to close the current packfile, generate its |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 799 | unique SHA-1 checksum and index, and start a new packfile. |
| 800 | This command is optional and is not needed to perform |
| 801 | an import. |
| 802 | </p> |
| 803 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 804 | <dt class="hdlist1"> |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 805 | <tt>progress</tt> |
| 806 | </dt> |
| 807 | <dd> |
| 808 | <p> |
| 809 | Causes fast-import to echo the entire line to its own |
| 810 | standard output. This command is optional and is not needed |
| 811 | to perform an import. |
| 812 | </p> |
| 813 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 814 | <dt class="hdlist1"> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 815 | <tt>feature</tt> |
| 816 | </dt> |
| 817 | <dd> |
| 818 | <p> |
| 819 | Require that fast-import supports the specified feature, or |
| 820 | abort if it does not. |
| 821 | </p> |
| 822 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 823 | <dt class="hdlist1"> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 824 | <tt>option</tt> |
| 825 | </dt> |
| 826 | <dd> |
| 827 | <p> |
| 828 | Specify any of the options listed under OPTIONS that do not |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 829 | change stream semantic to suit the frontend’s needs. This |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 830 | command is optional and is not needed to perform an import. |
| 831 | </p> |
| 832 | </dd> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 833 | </dl></div> |
| 834 | <h3 id="_tt_commit_tt"><tt>commit</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 835 | <div class="paragraph"><p>Create or update a branch with a new commit, recording one logical |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 836 | change to the project.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 837 | <div class="literalblock"> |
| 838 | <div class="content"> |
| 839 | <pre><tt> 'commit' SP <ref> LF |
| 840 | mark? |
| Junio C Hamano | 6d325df | 2010-01-01 00:02:47 | [diff] [blame] | 841 | ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? |
| 842 | 'committer' (SP <name>)? SP LT <email> GT SP <when> LF |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 843 | data |
| 844 | ('from' SP <committish> LF)? |
| 845 | ('merge' SP <committish> LF)? |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 846 | (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 847 | LF?</tt></pre> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 848 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 849 | <div class="paragraph"><p>where <tt><ref></tt> is the name of the branch to make the commit on. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 850 | Typically branch names are prefixed with <tt>refs/heads/</tt> in |
| 851 | Git, so importing the CVS branch symbol <tt>RELENG-1_0</tt> would use |
| 852 | <tt>refs/heads/RELENG-1_0</tt> for the value of <tt><ref></tt>. The value of |
| 853 | <tt><ref></tt> must be a valid refname in Git. As <tt>LF</tt> is not valid in |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 854 | a Git refname, no quoting or escaping syntax is supported here.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 855 | <div class="paragraph"><p>A <tt>mark</tt> command may optionally appear, requesting fast-import to save a |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 856 | reference to the newly created commit for future use by the frontend |
| 857 | (see below for format). It is very common for frontends to mark |
| 858 | every commit they create, thereby allowing future branch creation |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 859 | from any imported commit.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 860 | <div class="paragraph"><p>The <tt>data</tt> command following <tt>committer</tt> must supply the commit |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 861 | message (see below for <tt>data</tt> command syntax). To import an empty |
| 862 | commit message use a 0 length data. Commit messages are free-form |
| 863 | and are not interpreted by Git. Currently they must be encoded in |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 864 | UTF-8, as fast-import does not permit other encodings to be specified.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 865 | <div class="paragraph"><p>Zero or more <tt>filemodify</tt>, <tt>filedelete</tt>, <tt>filecopy</tt>, <tt>filerename</tt>, |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 866 | <tt>filedeleteall</tt> and <tt>notemodify</tt> commands |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 867 | may be included to update the contents of the branch prior to |
| 868 | creating the commit. These commands may be supplied in any order. |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 869 | However it is recommended that a <tt>filedeleteall</tt> command precede |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 870 | all <tt>filemodify</tt>, <tt>filecopy</tt>, <tt>filerename</tt> and <tt>notemodify</tt> commands in |
| 871 | the same commit, as <tt>filedeleteall</tt> wipes the branch clean (see below).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 872 | <div class="paragraph"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 873 | <h4 id="_tt_author_tt"><tt>author</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 874 | <div class="paragraph"><p>An <tt>author</tt> command may optionally appear, if the author information |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 875 | might differ from the committer information. If <tt>author</tt> is omitted |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 876 | then fast-import will automatically use the committer’s information for |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 877 | the author portion of the commit. See below for a description of |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 878 | the fields in <tt>author</tt>, as they are identical to <tt>committer</tt>.</p></div> |
| 879 | <h4 id="_tt_committer_tt"><tt>committer</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 880 | <div class="paragraph"><p>The <tt>committer</tt> command indicates who made this commit, and when |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 881 | they made it.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 882 | <div class="paragraph"><p>Here <tt><name></tt> is the person’s display name (for example |
| 883 | “Com M Itter”) and <tt><email></tt> is the person’s email address |
| 884 | (“<a href="mailto:cm@example.com">cm@example.com</a>”). <tt>LT</tt> and <tt>GT</tt> are the literal less-than (\x3c) |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 885 | and greater-than (\x3e) symbols. These are required to delimit |
| 886 | the email address from the other fields in the line. Note that |
| 887 | <tt><name></tt> is free-form and may contain any sequence of bytes, except |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 888 | <tt>LT</tt> and <tt>LF</tt>. It is typically UTF-8 encoded.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 889 | <div class="paragraph"><p>The time of the change is specified by <tt><when></tt> using the date format |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 890 | that was selected by the --date-format=<fmt> command line option. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 891 | See “Date Formats” above for the set of supported formats, and |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 892 | their syntax.</p></div> |
| 893 | <h4 id="_tt_from_tt"><tt>from</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 894 | <div class="paragraph"><p>The <tt>from</tt> command is used to specify the commit to initialize |
| Junio C Hamano | 5dad083 | 2007-02-13 05:16:23 | [diff] [blame] | 895 | this branch from. This revision will be the first ancestor of the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 896 | new commit.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 897 | <div class="paragraph"><p>Omitting the <tt>from</tt> command in the first commit of a new branch |
| Junio C Hamano | 5dad083 | 2007-02-13 05:16:23 | [diff] [blame] | 898 | will cause fast-import to create that commit with no ancestor. This |
| 899 | tends to be desired only for the initial commit of a project. |
| Junio C Hamano | 25c0b70 | 2008-03-23 09:41:37 | [diff] [blame] | 900 | If the frontend creates all files from scratch when making a new |
| 901 | branch, a <tt>merge</tt> command may be used instead of <tt>from</tt> to start |
| 902 | the commit with an empty tree. |
| Junio C Hamano | 5dad083 | 2007-02-13 05:16:23 | [diff] [blame] | 903 | Omitting the <tt>from</tt> command on existing branches is usually desired, |
| 904 | as the current commit on that branch is automatically assumed to |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 905 | be the first ancestor of the new commit.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 906 | <div class="paragraph"><p>As <tt>LF</tt> is not valid in a Git refname or SHA-1 expression, no |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 907 | quoting or escaping syntax is supported within <tt><committish></tt>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 908 | <div class="paragraph"><p>Here <tt><committish></tt> is any of the following:</p></div> |
| 909 | <div class="ulist"><ul> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 910 | <li> |
| 911 | <p> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 912 | The name of an existing branch already in fast-import’s internal branch |
| 913 | table. If fast-import doesn’t know the name, it’s treated as a SHA-1 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 914 | expression. |
| 915 | </p> |
| 916 | </li> |
| 917 | <li> |
| 918 | <p> |
| 919 | A mark reference, <tt>:<idnum></tt>, where <tt><idnum></tt> is the mark number. |
| 920 | </p> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 921 | <div class="paragraph"><p>The reason fast-import uses <tt>:</tt> to denote a mark reference is this character |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 922 | is not legal in a Git branch name. The leading <tt>:</tt> makes it easy |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 923 | to distinguish between the mark 42 (<tt>:42</tt>) and the branch 42 (<tt>42</tt> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 924 | or <tt>refs/heads/42</tt>), or an abbreviated SHA-1 which happened to |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 925 | consist only of base-10 digits.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 926 | <div class="paragraph"><p>Marks must be declared (via <tt>mark</tt>) before they can be used.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 927 | </li> |
| 928 | <li> |
| 929 | <p> |
| 930 | A complete 40 byte or abbreviated commit SHA-1 in hex. |
| 931 | </p> |
| 932 | </li> |
| 933 | <li> |
| 934 | <p> |
| 935 | Any valid Git SHA-1 expression that resolves to a commit. See |
| Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 936 | “SPECIFYING REVISIONS” in <a href="gitrevisions.html">gitrevisions(7)</a> for details. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 937 | </p> |
| 938 | </li> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 939 | </ul></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 940 | <div class="paragraph"><p>The special case of restarting an incremental import from the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 941 | current branch value should be written as:</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 942 | <div class="listingblock"> |
| 943 | <div class="content"> |
| 944 | <pre><tt> from refs/heads/branch^0</tt></pre> |
| 945 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 946 | <div class="paragraph"><p>The <tt>^0</tt> suffix is necessary as fast-import does not permit a branch to |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 947 | start from itself, and the branch is created in memory before the |
| Junio C Hamano | 6926bef | 2007-06-16 09:54:05 | [diff] [blame] | 948 | <tt>from</tt> command is even read from the input. Adding <tt>^0</tt> will force |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 949 | fast-import to resolve the commit through Git’s revision parsing library, |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 950 | rather than its internal branch table, thereby loading in the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 951 | existing value of the branch.</p></div> |
| 952 | <h4 id="_tt_merge_tt"><tt>merge</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 953 | <div class="paragraph"><p>Includes one additional ancestor commit. If the <tt>from</tt> command is |
| Junio C Hamano | 25c0b70 | 2008-03-23 09:41:37 | [diff] [blame] | 954 | omitted when creating a new branch, the first <tt>merge</tt> commit will be |
| 955 | the first ancestor of the current commit, and the branch will start |
| 956 | out with no files. An unlimited number of <tt>merge</tt> commands per |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 957 | commit are permitted by fast-import, thereby establishing an n-way merge. |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 958 | However Git’s other tools never create commits with more than 15 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 959 | additional ancestors (forming a 16-way merge). For this reason |
| 960 | it is suggested that frontends do not use more than 15 <tt>merge</tt> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 961 | commands per commit; 16, if starting a new, empty branch.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 962 | <div class="paragraph"><p>Here <tt><committish></tt> is any of the commit specification expressions |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 963 | also accepted by <tt>from</tt> (see above).</p></div> |
| 964 | <h4 id="_tt_filemodify_tt"><tt>filemodify</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 965 | <div class="paragraph"><p>Included in a <tt>commit</tt> command to add a new file or change the |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 966 | content of an existing file. This command has two different means |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 967 | of specifying the content of the file.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 968 | <div class="dlist"><dl> |
| 969 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 970 | External data format |
| 971 | </dt> |
| 972 | <dd> |
| 973 | <p> |
| 974 | The data content for the file was already supplied by a prior |
| 975 | <tt>blob</tt> command. The frontend just needs to connect it. |
| 976 | </p> |
| 977 | <div class="literalblock"> |
| 978 | <div class="content"> |
| 979 | <pre><tt> 'M' SP <mode> SP <dataref> SP <path> LF</tt></pre> |
| 980 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 981 | <div class="paragraph"><p>Here usually <tt><dataref></tt> must be either a mark reference (<tt>:<idnum></tt>) |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 982 | set by a prior <tt>blob</tt> command, or a full 40-byte SHA-1 of an |
| Junio C Hamano | 619596a | 2010-08-18 22:15:35 | [diff] [blame] | 983 | existing Git blob object. If <tt><mode></tt> is <tt>040000</tt>` then |
| 984 | <tt><dataref></tt> must be the full 40-byte SHA-1 of an existing |
| 985 | Git tree object or a mark reference set with <tt>--import-marks</tt>.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 986 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 987 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 988 | Inline data format |
| 989 | </dt> |
| 990 | <dd> |
| 991 | <p> |
| 992 | The data content for the file has not been supplied yet. |
| 993 | The frontend wants to supply it as part of this modify |
| 994 | command. |
| 995 | </p> |
| 996 | <div class="literalblock"> |
| 997 | <div class="content"> |
| 998 | <pre><tt> 'M' SP <mode> SP 'inline' SP <path> LF |
| 999 | data</tt></pre> |
| 1000 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1001 | <div class="paragraph"><p>See below for a detailed description of the <tt>data</tt> command.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1002 | </dd> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1003 | </dl></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1004 | <div class="paragraph"><p>In both formats <tt><mode></tt> is the type of file entry, specified |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1005 | in octal. Git only supports the following modes:</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1006 | <div class="ulist"><ul> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1007 | <li> |
| 1008 | <p> |
| 1009 | <tt>100644</tt> or <tt>644</tt>: A normal (not-executable) file. The majority |
| 1010 | of files in most projects use this mode. If in doubt, this is |
| 1011 | what you want. |
| 1012 | </p> |
| 1013 | </li> |
| 1014 | <li> |
| 1015 | <p> |
| 1016 | <tt>100755</tt> or <tt>755</tt>: A normal, but executable, file. |
| 1017 | </p> |
| 1018 | </li> |
| 1019 | <li> |
| 1020 | <p> |
| 1021 | <tt>120000</tt>: A symlink, the content of the file will be the link target. |
| 1022 | </p> |
| 1023 | </li> |
| Junio C Hamano | 915cd9b | 2008-07-20 01:24:17 | [diff] [blame] | 1024 | <li> |
| 1025 | <p> |
| 1026 | <tt>160000</tt>: A gitlink, SHA-1 of the object refers to a commit in |
| 1027 | another repository. Git links can only be specified by SHA or through |
| 1028 | a commit mark. They are used to implement submodules. |
| 1029 | </p> |
| 1030 | </li> |
| Junio C Hamano | 619596a | 2010-08-18 22:15:35 | [diff] [blame] | 1031 | <li> |
| 1032 | <p> |
| 1033 | <tt>040000</tt>: A subdirectory. Subdirectories can only be specified by |
| 1034 | SHA or through a tree mark set with <tt>--import-marks</tt>. |
| 1035 | </p> |
| 1036 | </li> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1037 | </ul></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1038 | <div class="paragraph"><p>In both formats <tt><path></tt> is the complete path of the file to be added |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1039 | (if not already existing) or modified (if already existing).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1040 | <div class="paragraph"><p>A <tt><path></tt> string must use UNIX-style directory separators (forward |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1041 | slash <tt>/</tt>), may contain any byte other than <tt>LF</tt>, and must not |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1042 | start with double quote (<tt>"</tt>).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1043 | <div class="paragraph"><p>If an <tt>LF</tt> or double quote must be encoded into <tt><path></tt> shell-style |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1044 | quoting should be used, e.g. <tt>"path/with\n and \" in it"</tt>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1045 | <div class="paragraph"><p>Additionally, in <tt>040000</tt> mode, <tt><path></tt> may also be an empty string |
| Junio C Hamano | c27b733 | 2010-10-14 04:37:28 | [diff] [blame] | 1046 | (<tt>""</tt>) to specify the root of the tree.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1047 | <div class="paragraph"><p>The value of <tt><path></tt> must be in canonical form. That is it must not:</p></div> |
| 1048 | <div class="ulist"><ul> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1049 | <li> |
| 1050 | <p> |
| 1051 | contain an empty directory component (e.g. <tt>foo//bar</tt> is invalid), |
| 1052 | </p> |
| 1053 | </li> |
| 1054 | <li> |
| 1055 | <p> |
| Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 1056 | end with a directory separator (e.g. <tt>foo/</tt> is invalid), |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1057 | </p> |
| 1058 | </li> |
| 1059 | <li> |
| 1060 | <p> |
| Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame] | 1061 | start with a directory separator (e.g. <tt>/foo</tt> is invalid), |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1062 | </p> |
| 1063 | </li> |
| 1064 | <li> |
| 1065 | <p> |
| 1066 | contain the special component <tt>.</tt> or <tt>..</tt> (e.g. <tt>foo/./bar</tt> and |
| 1067 | <tt>foo/../bar</tt> are invalid). |
| 1068 | </p> |
| 1069 | </li> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1070 | </ul></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1071 | <div class="paragraph"><p>It is recommended that <tt><path></tt> always be encoded using UTF-8.</p></div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1072 | <h4 id="_tt_filedelete_tt"><tt>filedelete</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1073 | <div class="paragraph"><p>Included in a <tt>commit</tt> command to remove a file or recursively |
| Junio C Hamano | 06216df | 2007-07-10 07:49:37 | [diff] [blame] | 1074 | delete an entire directory from the branch. If the file or directory |
| 1075 | removal makes its parent directory empty, the parent directory will |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1076 | be automatically removed too. This cascades up the tree until the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1077 | first non-empty directory or the root is reached.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1078 | <div class="literalblock"> |
| 1079 | <div class="content"> |
| 1080 | <pre><tt> 'D' SP <path> LF</tt></pre> |
| 1081 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1082 | <div class="paragraph"><p>here <tt><path></tt> is the complete path of the file or subdirectory to |
| Junio C Hamano | 06216df | 2007-07-10 07:49:37 | [diff] [blame] | 1083 | be removed from the branch. |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1084 | See <tt>filemodify</tt> above for a detailed description of <tt><path></tt>.</p></div> |
| 1085 | <h4 id="_tt_filecopy_tt"><tt>filecopy</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1086 | <div class="paragraph"><p>Recursively copies an existing file or subdirectory to a different |
| Junio C Hamano | c0ea7c6 | 2007-07-15 07:19:06 | [diff] [blame] | 1087 | location within the branch. The existing file or directory must |
| 1088 | exist. If the destination exists it will be completely replaced |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1089 | by the content copied from the source.</p></div> |
| Junio C Hamano | c0ea7c6 | 2007-07-15 07:19:06 | [diff] [blame] | 1090 | <div class="literalblock"> |
| 1091 | <div class="content"> |
| 1092 | <pre><tt> 'C' SP <path> SP <path> LF</tt></pre> |
| 1093 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1094 | <div class="paragraph"><p>here the first <tt><path></tt> is the source location and the second |
| Junio C Hamano | c0ea7c6 | 2007-07-15 07:19:06 | [diff] [blame] | 1095 | <tt><path></tt> is the destination. See <tt>filemodify</tt> above for a detailed |
| 1096 | description of what <tt><path></tt> may look like. To use a source path |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1097 | that contains SP the path must be quoted.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1098 | <div class="paragraph"><p>A <tt>filecopy</tt> command takes effect immediately. Once the source |
| Junio C Hamano | c0ea7c6 | 2007-07-15 07:19:06 | [diff] [blame] | 1099 | location has been copied to the destination any future commands |
| 1100 | applied to the source location will not impact the destination of |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1101 | the copy.</p></div> |
| 1102 | <h4 id="_tt_filerename_tt"><tt>filerename</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1103 | <div class="paragraph"><p>Renames an existing file or subdirectory to a different location |
| Junio C Hamano | 06216df | 2007-07-10 07:49:37 | [diff] [blame] | 1104 | within the branch. The existing file or directory must exist. If |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1105 | the destination exists it will be replaced by the source directory.</p></div> |
| Junio C Hamano | 06216df | 2007-07-10 07:49:37 | [diff] [blame] | 1106 | <div class="literalblock"> |
| 1107 | <div class="content"> |
| 1108 | <pre><tt> 'R' SP <path> SP <path> LF</tt></pre> |
| 1109 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1110 | <div class="paragraph"><p>here the first <tt><path></tt> is the source location and the second |
| Junio C Hamano | 06216df | 2007-07-10 07:49:37 | [diff] [blame] | 1111 | <tt><path></tt> is the destination. See <tt>filemodify</tt> above for a detailed |
| 1112 | description of what <tt><path></tt> may look like. To use a source path |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1113 | that contains SP the path must be quoted.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1114 | <div class="paragraph"><p>A <tt>filerename</tt> command takes effect immediately. Once the source |
| Junio C Hamano | 06216df | 2007-07-10 07:49:37 | [diff] [blame] | 1115 | location has been renamed to the destination any future commands |
| 1116 | applied to the source location will create new files there and not |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1117 | impact the destination of the rename.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1118 | <div class="paragraph"><p>Note that a <tt>filerename</tt> is the same as a <tt>filecopy</tt> followed by a |
| Junio C Hamano | c0ea7c6 | 2007-07-15 07:19:06 | [diff] [blame] | 1119 | <tt>filedelete</tt> of the source location. There is a slight performance |
| 1120 | advantage to using <tt>filerename</tt>, but the advantage is so small |
| 1121 | that it is never worth trying to convert a delete/add pair in |
| 1122 | source material into a rename for fast-import. This <tt>filerename</tt> |
| 1123 | command is provided just to simplify frontends that already have |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1124 | rename information and don’t want bother with decomposing it into a |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1125 | <tt>filecopy</tt> followed by a <tt>filedelete</tt>.</p></div> |
| 1126 | <h4 id="_tt_filedeleteall_tt"><tt>filedeleteall</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1127 | <div class="paragraph"><p>Included in a <tt>commit</tt> command to remove all files (and also all |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1128 | directories) from the branch. This command resets the internal |
| 1129 | branch structure to have no files in it, allowing the frontend |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1130 | to subsequently add all interesting files from scratch.</p></div> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1131 | <div class="literalblock"> |
| 1132 | <div class="content"> |
| 1133 | <pre><tt> 'deleteall' LF</tt></pre> |
| 1134 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1135 | <div class="paragraph"><p>This command is extremely useful if the frontend does not know |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1136 | (or does not care to know) what files are currently on the branch, |
| 1137 | and therefore cannot generate the proper <tt>filedelete</tt> commands to |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1138 | update the content.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1139 | <div class="paragraph"><p>Issuing a <tt>filedeleteall</tt> followed by the needed <tt>filemodify</tt> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1140 | commands to set the correct content will produce the same results |
| 1141 | as sending only the needed <tt>filemodify</tt> and <tt>filedelete</tt> commands. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1142 | The <tt>filedeleteall</tt> approach may however require fast-import to use slightly |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1143 | more memory per active branch (less than 1 MiB for even most large |
| 1144 | projects); so frontends that can easily obtain only the affected |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1145 | paths for a commit are encouraged to do so.</p></div> |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1146 | <h4 id="_tt_notemodify_tt"><tt>notemodify</tt></h4> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1147 | <div class="paragraph"><p>Included in a <tt>commit</tt> command to add a new note (annotating a given |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1148 | commit) or change the content of an existing note. This command has |
| 1149 | two different means of specifying the content of the note.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1150 | <div class="dlist"><dl> |
| 1151 | <dt class="hdlist1"> |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1152 | External data format |
| 1153 | </dt> |
| 1154 | <dd> |
| 1155 | <p> |
| 1156 | The data content for the note was already supplied by a prior |
| 1157 | <tt>blob</tt> command. The frontend just needs to connect it to the |
| 1158 | commit that is to be annotated. |
| 1159 | </p> |
| 1160 | <div class="literalblock"> |
| 1161 | <div class="content"> |
| 1162 | <pre><tt> 'N' SP <dataref> SP <committish> LF</tt></pre> |
| 1163 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1164 | <div class="paragraph"><p>Here <tt><dataref></tt> can be either a mark reference (<tt>:<idnum></tt>) |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1165 | set by a prior <tt>blob</tt> command, or a full 40-byte SHA-1 of an |
| 1166 | existing Git blob object.</p></div> |
| 1167 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1168 | <dt class="hdlist1"> |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1169 | Inline data format |
| 1170 | </dt> |
| 1171 | <dd> |
| 1172 | <p> |
| 1173 | The data content for the note has not been supplied yet. |
| 1174 | The frontend wants to supply it as part of this modify |
| 1175 | command. |
| 1176 | </p> |
| 1177 | <div class="literalblock"> |
| 1178 | <div class="content"> |
| 1179 | <pre><tt> 'N' SP 'inline' SP <committish> LF |
| 1180 | data</tt></pre> |
| 1181 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1182 | <div class="paragraph"><p>See below for a detailed description of the <tt>data</tt> command.</p></div> |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1183 | </dd> |
| 1184 | </dl></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1185 | <div class="paragraph"><p>In both formats <tt><committish></tt> is any of the commit specification |
| Junio C Hamano | 3b70d3c | 2009-11-21 17:37:37 | [diff] [blame] | 1186 | expressions also accepted by <tt>from</tt> (see above).</p></div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1187 | <h3 id="_tt_mark_tt"><tt>mark</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1188 | <div class="paragraph"><p>Arranges for fast-import to save a reference to the current object, allowing |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1189 | the frontend to recall this object at a future point in time, without |
| 1190 | knowing its SHA-1. Here the current object is the object creation |
| 1191 | command the <tt>mark</tt> command appears within. This can be <tt>commit</tt>, |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1192 | <tt>tag</tt>, and <tt>blob</tt>, but <tt>commit</tt> is the most common usage.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1193 | <div class="literalblock"> |
| 1194 | <div class="content"> |
| 1195 | <pre><tt> 'mark' SP ':' <idnum> LF</tt></pre> |
| 1196 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1197 | <div class="paragraph"><p>where <tt><idnum></tt> is the number assigned by the frontend to this mark. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1198 | The value of <tt><idnum></tt> is expressed as an ASCII decimal integer. |
| 1199 | The value 0 is reserved and cannot be used as |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1200 | a mark. Only values greater than or equal to 1 may be used as marks.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1201 | <div class="paragraph"><p>New marks are created automatically. Existing marks can be moved |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1202 | to another object simply by reusing the same <tt><idnum></tt> in another |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1203 | <tt>mark</tt> command.</p></div> |
| 1204 | <h3 id="_tt_tag_tt"><tt>tag</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1205 | <div class="paragraph"><p>Creates an annotated tag referring to a specific commit. To create |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1206 | lightweight (non-annotated) tags see the <tt>reset</tt> command below.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1207 | <div class="literalblock"> |
| 1208 | <div class="content"> |
| 1209 | <pre><tt> 'tag' SP <name> LF |
| 1210 | 'from' SP <committish> LF |
| Junio C Hamano | 6d325df | 2010-01-01 00:02:47 | [diff] [blame] | 1211 | 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF |
| Junio C Hamano | ea5dae6 | 2007-05-10 23:25:08 | [diff] [blame] | 1212 | data</tt></pre> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1213 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1214 | <div class="paragraph"><p>where <tt><name></tt> is the name of the tag to create.</p></div> |
| 1215 | <div class="paragraph"><p>Tag names are automatically prefixed with <tt>refs/tags/</tt> when stored |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1216 | in Git, so importing the CVS branch symbol <tt>RELENG-1_0-FINAL</tt> would |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1217 | use just <tt>RELENG-1_0-FINAL</tt> for <tt><name></tt>, and fast-import will write the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1218 | corresponding ref as <tt>refs/tags/RELENG-1_0-FINAL</tt>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1219 | <div class="paragraph"><p>The value of <tt><name></tt> must be a valid refname in Git and therefore |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1220 | may contain forward slashes. As <tt>LF</tt> is not valid in a Git refname, |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1221 | no quoting or escaping syntax is supported here.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1222 | <div class="paragraph"><p>The <tt>from</tt> command is the same as in the <tt>commit</tt> command; see |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1223 | above for details.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1224 | <div class="paragraph"><p>The <tt>tagger</tt> command uses the same format as <tt>committer</tt> within |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1225 | <tt>commit</tt>; again see above for details.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1226 | <div class="paragraph"><p>The <tt>data</tt> command following <tt>tagger</tt> must supply the annotated tag |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1227 | message (see below for <tt>data</tt> command syntax). To import an empty |
| 1228 | tag message use a 0 length data. Tag messages are free-form and are |
| 1229 | not interpreted by Git. Currently they must be encoded in UTF-8, |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1230 | as fast-import does not permit other encodings to be specified.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1231 | <div class="paragraph"><p>Signing annotated tags during import from within fast-import is not |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1232 | supported. Trying to include your own PGP/GPG signature is not |
| 1233 | recommended, as the frontend does not (easily) have access to the |
| 1234 | complete set of bytes which normally goes into such a signature. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1235 | If signing is required, create lightweight tags from within fast-import with |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1236 | <tt>reset</tt>, then create the annotated versions of those tags offline |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 1237 | with the standard <em>git tag</em> process.</p></div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1238 | <h3 id="_tt_reset_tt"><tt>reset</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1239 | <div class="paragraph"><p>Creates (or recreates) the named branch, optionally starting from |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1240 | a specific revision. The reset command allows a frontend to issue |
| 1241 | a new <tt>from</tt> command for an existing branch, or to create a new |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1242 | branch from an existing commit without creating a new commit.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1243 | <div class="literalblock"> |
| 1244 | <div class="content"> |
| 1245 | <pre><tt> 'reset' SP <ref> LF |
| 1246 | ('from' SP <committish> LF)? |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1247 | LF?</tt></pre> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1248 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1249 | <div class="paragraph"><p>For a detailed description of <tt><ref></tt> and <tt><committish></tt> see above |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1250 | under <tt>commit</tt> and <tt>from</tt>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1251 | <div class="paragraph"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div> |
| 1252 | <div class="paragraph"><p>The <tt>reset</tt> command can also be used to create lightweight |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1253 | (non-annotated) tags. For example:</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1254 | <div class="exampleblock"> |
| 1255 | <div class="exampleblock-content"> |
| 1256 | <div class="literalblock"> |
| 1257 | <div class="content"> |
| 1258 | <pre><tt>reset refs/tags/938 |
| 1259 | from :938</tt></pre> |
| 1260 | </div></div> |
| 1261 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1262 | <div class="paragraph"><p>would create the lightweight tag <tt>refs/tags/938</tt> referring to |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1263 | whatever commit mark <tt>:938</tt> references.</p></div> |
| 1264 | <h3 id="_tt_blob_tt"><tt>blob</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1265 | <div class="paragraph"><p>Requests writing one file revision to the packfile. The revision |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1266 | is not connected to any commit; this connection must be formed in |
| 1267 | a subsequent <tt>commit</tt> command by referencing the blob through an |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1268 | assigned mark.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1269 | <div class="literalblock"> |
| 1270 | <div class="content"> |
| 1271 | <pre><tt> 'blob' LF |
| 1272 | mark? |
| 1273 | data</tt></pre> |
| 1274 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1275 | <div class="paragraph"><p>The mark command is optional here as some frontends have chosen |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1276 | to generate the Git SHA-1 for the blob on their own, and feed that |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1277 | directly to <tt>commit</tt>. This is typically more work than it’s worth |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1278 | however, as marks are inexpensive to store and easy to use.</p></div> |
| 1279 | <h3 id="_tt_data_tt"><tt>data</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1280 | <div class="paragraph"><p>Supplies raw data (for use as blob/file content, commit messages, or |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1281 | annotated tag messages) to fast-import. Data can be supplied using an exact |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1282 | byte count or delimited with a terminating line. Real frontends |
| 1283 | intended for production-quality conversions should always use the |
| 1284 | exact byte count format, as it is more robust and performs better. |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1285 | The delimited format is intended primarily for testing fast-import.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1286 | <div class="paragraph"><p>Comment lines appearing within the <tt><raw></tt> part of <tt>data</tt> commands |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1287 | are always taken to be part of the body of the data and are therefore |
| 1288 | never ignored by fast-import. This makes it safe to import any |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1289 | file/message content whose lines might start with <tt>#</tt>.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1290 | <div class="dlist"><dl> |
| 1291 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1292 | Exact byte count format |
| 1293 | </dt> |
| 1294 | <dd> |
| 1295 | <p> |
| 1296 | The frontend must specify the number of bytes of data. |
| 1297 | </p> |
| 1298 | <div class="literalblock"> |
| 1299 | <div class="content"> |
| 1300 | <pre><tt> 'data' SP <count> LF |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1301 | <raw> LF?</tt></pre> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1302 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1303 | <div class="paragraph"><p>where <tt><count></tt> is the exact number of bytes appearing within |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1304 | <tt><raw></tt>. The value of <tt><count></tt> is expressed as an ASCII decimal |
| 1305 | integer. The <tt>LF</tt> on either side of <tt><raw></tt> is not |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1306 | included in <tt><count></tt> and will not be included in the imported data.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1307 | <div class="paragraph"><p>The <tt>LF</tt> after <tt><raw></tt> is optional (it used to be required) but |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1308 | recommended. Always including it makes debugging a fast-import |
| 1309 | stream easier as the next command always starts in column 0 |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1310 | of the next line, even if <tt><raw></tt> did not end with an <tt>LF</tt>.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1311 | </dd> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1312 | <dt class="hdlist1"> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1313 | Delimited format |
| 1314 | </dt> |
| 1315 | <dd> |
| 1316 | <p> |
| 1317 | A delimiter string is used to mark the end of the data. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1318 | fast-import will compute the length by searching for the delimiter. |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 1319 | This format is primarily useful for testing and is not |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1320 | recommended for real data. |
| 1321 | </p> |
| 1322 | <div class="literalblock"> |
| 1323 | <div class="content"> |
| 1324 | <pre><tt> 'data' SP '<<' <delim> LF |
| 1325 | <raw> LF |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1326 | <delim> LF |
| 1327 | LF?</tt></pre> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1328 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1329 | <div class="paragraph"><p>where <tt><delim></tt> is the chosen delimiter string. The string <tt><delim></tt> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1330 | must not appear on a line by itself within <tt><raw></tt>, as otherwise |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1331 | fast-import will think the data ends earlier than it really does. The <tt>LF</tt> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1332 | immediately trailing <tt><raw></tt> is part of <tt><raw></tt>. This is one of |
| 1333 | the limitations of the delimited format, it is impossible to supply |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1334 | a data chunk which does not have an LF as its last byte.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1335 | <div class="paragraph"><p>The <tt>LF</tt> after <tt><delim> LF</tt> is optional (it used to be required).</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1336 | </dd> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1337 | </dl></div> |
| 1338 | <h3 id="_tt_checkpoint_tt"><tt>checkpoint</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1339 | <div class="paragraph"><p>Forces fast-import to close the current packfile, start a new one, and to |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1340 | save out all current branch refs, tags and marks.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1341 | <div class="literalblock"> |
| 1342 | <div class="content"> |
| 1343 | <pre><tt> 'checkpoint' LF |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1344 | LF?</tt></pre> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1345 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1346 | <div class="paragraph"><p>Note that fast-import automatically switches packfiles when the current |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1347 | packfile reaches --max-pack-size, or 4 GiB, whichever limit is |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1348 | smaller. During an automatic packfile switch fast-import does not update |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1349 | the branch refs, tags or marks.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1350 | <div class="paragraph"><p>As a <tt>checkpoint</tt> can require a significant amount of CPU time and |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1351 | disk IO (to compute the overall pack SHA-1 checksum, generate the |
| 1352 | corresponding index file, and update the refs) it can easily take |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1353 | several minutes for a single <tt>checkpoint</tt> command to complete.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1354 | <div class="paragraph"><p>Frontends may choose to issue checkpoints during extremely large |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1355 | and long running imports, or when they need to allow another Git |
| 1356 | process access to a branch. However given that a 30 GiB Subversion |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1357 | repository can be loaded into Git through fast-import in about 3 hours, |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1358 | explicit checkpointing may not be necessary.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1359 | <div class="paragraph"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1360 | <h3 id="_tt_progress_tt"><tt>progress</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1361 | <div class="paragraph"><p>Causes fast-import to print the entire <tt>progress</tt> line unmodified to |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1362 | its standard output channel (file descriptor 1) when the command is |
| 1363 | processed from the input stream. The command otherwise has no impact |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1364 | on the current import, or on any of fast-import’s internal state.</p></div> |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1365 | <div class="literalblock"> |
| 1366 | <div class="content"> |
| 1367 | <pre><tt> 'progress' SP <any> LF |
| 1368 | LF?</tt></pre> |
| 1369 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1370 | <div class="paragraph"><p>The <tt><any></tt> part of the command may contain any sequence of bytes |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1371 | that does not contain <tt>LF</tt>. The <tt>LF</tt> after the command is optional. |
| 1372 | Callers may wish to process the output through a tool such as sed to |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1373 | remove the leading part of the line, for example:</p></div> |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1374 | <div class="exampleblock"> |
| 1375 | <div class="exampleblock-content"> |
| 1376 | <div class="literalblock"> |
| 1377 | <div class="content"> |
| Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 1378 | <pre><tt>frontend | git fast-import | sed 's/^progress //'</tt></pre> |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1379 | </div></div> |
| 1380 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1381 | <div class="paragraph"><p>Placing a <tt>progress</tt> command immediately after a <tt>checkpoint</tt> will |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1382 | inform the reader when the <tt>checkpoint</tt> has been completed and it |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1383 | can safely access the refs that fast-import updated.</p></div> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1384 | <h3 id="_tt_feature_tt"><tt>feature</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1385 | <div class="paragraph"><p>Require that fast-import supports the specified feature, or abort if |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1386 | it does not.</p></div> |
| 1387 | <div class="literalblock"> |
| 1388 | <div class="content"> |
| 1389 | <pre><tt> 'feature' SP <feature> LF</tt></pre> |
| 1390 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1391 | <div class="paragraph"><p>The <feature> part of the command may be any string matching |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1392 | ^[a-zA-Z][a-zA-Z-]*$ and should be understood by fast-import.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1393 | <div class="paragraph"><p>Feature work identical as their option counterparts with the |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1394 | exception of the import-marks feature, see below.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1395 | <div class="paragraph"><p>The following features are currently supported:</p></div> |
| 1396 | <div class="ulist"><ul> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1397 | <li> |
| 1398 | <p> |
| 1399 | date-format |
| 1400 | </p> |
| 1401 | </li> |
| 1402 | <li> |
| 1403 | <p> |
| 1404 | import-marks |
| 1405 | </p> |
| 1406 | </li> |
| 1407 | <li> |
| 1408 | <p> |
| 1409 | export-marks |
| 1410 | </p> |
| 1411 | </li> |
| 1412 | <li> |
| 1413 | <p> |
| 1414 | relative-marks |
| 1415 | </p> |
| 1416 | </li> |
| 1417 | <li> |
| 1418 | <p> |
| 1419 | no-relative-marks |
| 1420 | </p> |
| 1421 | </li> |
| 1422 | <li> |
| 1423 | <p> |
| 1424 | force |
| 1425 | </p> |
| 1426 | </li> |
| 1427 | </ul></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1428 | <div class="paragraph"><p>The import-marks behaves differently from when it is specified as |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1429 | commandline option in that only one "feature import-marks" is allowed |
| 1430 | per stream. Also, any --import-marks= specified on the commandline |
| 1431 | will override those from the stream (if any).</p></div> |
| 1432 | <h3 id="_tt_option_tt"><tt>option</tt></h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1433 | <div class="paragraph"><p>Processes the specified option so that git fast-import behaves in a |
| 1434 | way that suits the frontend’s needs. |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1435 | Note that options specified by the frontend are overridden by any |
| 1436 | options the user may specify to git fast-import itself.</p></div> |
| 1437 | <div class="literalblock"> |
| 1438 | <div class="content"> |
| 1439 | <pre><tt> 'option' SP <option> LF</tt></pre> |
| 1440 | </div></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1441 | <div class="paragraph"><p>The <tt><option></tt> part of the command may contain any of the options |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1442 | listed in the OPTIONS section that do not change import semantics, |
| 1443 | without the leading <em>--</em> and is treated in the same way.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1444 | <div class="paragraph"><p>Option commands must be the first commands on the input (not counting |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1445 | feature commands), to give an option command after any non-option |
| 1446 | command is an error.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1447 | <div class="paragraph"><p>The following commandline options change import semantics and may therefore |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1448 | not be passed as option:</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1449 | <div class="ulist"><ul> |
| Junio C Hamano | 6ce6b6c | 2010-01-18 01:25:50 | [diff] [blame] | 1450 | <li> |
| 1451 | <p> |
| 1452 | date-format |
| 1453 | </p> |
| 1454 | </li> |
| 1455 | <li> |
| 1456 | <p> |
| 1457 | import-marks |
| 1458 | </p> |
| 1459 | </li> |
| 1460 | <li> |
| 1461 | <p> |
| 1462 | export-marks |
| 1463 | </p> |
| 1464 | </li> |
| 1465 | <li> |
| 1466 | <p> |
| 1467 | force |
| 1468 | </p> |
| 1469 | </li> |
| 1470 | </ul></div> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1471 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1472 | <h2 id="_crash_reports">Crash Reports</h2> |
| Junio C Hamano | 2139193 | 2008-02-16 10:02:54 | [diff] [blame] | 1473 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1474 | <div class="paragraph"><p>If fast-import is supplied invalid input it will terminate with a |
| Junio C Hamano | 2139193 | 2008-02-16 10:02:54 | [diff] [blame] | 1475 | non-zero exit status and create a crash report in the top level of |
| 1476 | the Git repository it was importing into. Crash reports contain |
| 1477 | a snapshot of the internal fast-import state as well as the most |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1478 | recent commands that lead up to the crash.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1479 | <div class="paragraph"><p>All recent commands (including stream comments, file changes and |
| Junio C Hamano | 2139193 | 2008-02-16 10:02:54 | [diff] [blame] | 1480 | progress commands) are shown in the command history within the crash |
| 1481 | report, but raw file data and commit messages are excluded from the |
| 1482 | crash report. This exclusion saves space within the report file |
| 1483 | and reduces the amount of buffering that fast-import must perform |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1484 | during execution.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1485 | <div class="paragraph"><p>After writing a crash report fast-import will close the current |
| Junio C Hamano | 2139193 | 2008-02-16 10:02:54 | [diff] [blame] | 1486 | packfile and export the marks table. This allows the frontend |
| 1487 | developer to inspect the repository state and resume the import from |
| 1488 | the point where it crashed. The modified branches and tags are not |
| 1489 | updated during a crash, as the import did not complete successfully. |
| 1490 | Branch and tag information can be found in the crash report and |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1491 | must be applied manually if the update is needed.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1492 | <div class="paragraph"><p>An example crash:</p></div> |
| Junio C Hamano | 2139193 | 2008-02-16 10:02:54 | [diff] [blame] | 1493 | <div class="exampleblock"> |
| 1494 | <div class="exampleblock-content"> |
| 1495 | <div class="literalblock"> |
| 1496 | <div class="content"> |
| 1497 | <pre><tt>$ cat >in <<END_OF_INPUT |
| 1498 | # my very first test commit |
| 1499 | commit refs/heads/master |
| 1500 | committer Shawn O. Pearce <spearce> 19283 -0400 |
| 1501 | # who is that guy anyway? |
| 1502 | data <<EOF |
| 1503 | this is my commit |
| 1504 | EOF |
| 1505 | M 644 inline .gitignore |
| 1506 | data <<EOF |
| 1507 | .gitignore |
| 1508 | EOF |
| 1509 | M 777 inline bob |
| 1510 | END_OF_INPUT</tt></pre> |
| 1511 | </div></div> |
| 1512 | <div class="literalblock"> |
| 1513 | <div class="content"> |
| Junio C Hamano | fce7c7e | 2008-07-02 03:06:38 | [diff] [blame] | 1514 | <pre><tt>$ git fast-import <in |
| Junio C Hamano | 2139193 | 2008-02-16 10:02:54 | [diff] [blame] | 1515 | fatal: Corrupt mode: M 777 inline bob |
| 1516 | fast-import: dumping crash report to .git/fast_import_crash_8434</tt></pre> |
| 1517 | </div></div> |
| 1518 | <div class="literalblock"> |
| 1519 | <div class="content"> |
| 1520 | <pre><tt>$ cat .git/fast_import_crash_8434 |
| 1521 | fast-import crash report: |
| 1522 | fast-import process: 8434 |
| 1523 | parent process : 1391 |
| 1524 | at Sat Sep 1 00:58:12 2007</tt></pre> |
| 1525 | </div></div> |
| 1526 | <div class="literalblock"> |
| 1527 | <div class="content"> |
| 1528 | <pre><tt>fatal: Corrupt mode: M 777 inline bob</tt></pre> |
| 1529 | </div></div> |
| 1530 | <div class="literalblock"> |
| 1531 | <div class="content"> |
| 1532 | <pre><tt>Most Recent Commands Before Crash |
| 1533 | --------------------------------- |
| 1534 | # my very first test commit |
| 1535 | commit refs/heads/master |
| 1536 | committer Shawn O. Pearce <spearce> 19283 -0400 |
| 1537 | # who is that guy anyway? |
| 1538 | data <<EOF |
| 1539 | M 644 inline .gitignore |
| 1540 | data <<EOF |
| 1541 | * M 777 inline bob</tt></pre> |
| 1542 | </div></div> |
| 1543 | <div class="literalblock"> |
| 1544 | <div class="content"> |
| 1545 | <pre><tt>Active Branch LRU |
| 1546 | ----------------- |
| 1547 | active_branches = 1 cur, 5 max</tt></pre> |
| 1548 | </div></div> |
| 1549 | <div class="literalblock"> |
| 1550 | <div class="content"> |
| 1551 | <pre><tt>pos clock name |
| 1552 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1553 | 1) 0 refs/heads/master</tt></pre> |
| 1554 | </div></div> |
| 1555 | <div class="literalblock"> |
| 1556 | <div class="content"> |
| 1557 | <pre><tt>Inactive Branches |
| 1558 | ----------------- |
| 1559 | refs/heads/master: |
| 1560 | status : active loaded dirty |
| 1561 | tip commit : 0000000000000000000000000000000000000000 |
| 1562 | old tree : 0000000000000000000000000000000000000000 |
| 1563 | cur tree : 0000000000000000000000000000000000000000 |
| 1564 | commit clock: 0 |
| 1565 | last pack :</tt></pre> |
| 1566 | </div></div> |
| 1567 | <div class="literalblock"> |
| 1568 | <div class="content"> |
| 1569 | <pre><tt>------------------- |
| 1570 | END OF CRASH REPORT</tt></pre> |
| 1571 | </div></div> |
| 1572 | </div></div> |
| 1573 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1574 | <h2 id="_tips_and_tricks">Tips and Tricks</h2> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1575 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1576 | <div class="paragraph"><p>The following tips and tricks have been collected from various |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1577 | users of fast-import, and are offered here as suggestions.</p></div> |
| 1578 | <h3 id="_use_one_mark_per_commit">Use One Mark Per Commit</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1579 | <div class="paragraph"><p>When doing a repository conversion, use a unique mark per commit |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1580 | (<tt>mark :<n></tt>) and supply the --export-marks option on the command |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1581 | line. fast-import will dump a file which lists every mark and the Git |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1582 | object SHA-1 that corresponds to it. If the frontend can tie |
| 1583 | the marks back to the source repository, it is easy to verify the |
| 1584 | accuracy and completeness of the import by comparing each Git |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1585 | commit to the corresponding source revision.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1586 | <div class="paragraph"><p>Coming from a system such as Perforce or Subversion this should be |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1587 | quite simple, as the fast-import mark can also be the Perforce changeset |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1588 | number or the Subversion revision number.</p></div> |
| 1589 | <h3 id="_freely_skip_around_branches">Freely Skip Around Branches</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1590 | <div class="paragraph"><p>Don’t bother trying to optimize the frontend to stick to one branch |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1591 | at a time during an import. Although doing so might be slightly |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1592 | faster for fast-import, it tends to increase the complexity of the frontend |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1593 | code considerably.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1594 | <div class="paragraph"><p>The branch LRU builtin to fast-import tends to behave very well, and the |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1595 | cost of activating an inactive branch is so low that bouncing around |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1596 | between branches has virtually no impact on import performance.</p></div> |
| 1597 | <h3 id="_handling_renames">Handling Renames</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1598 | <div class="paragraph"><p>When importing a renamed file or directory, simply delete the old |
| Junio C Hamano | 9dd8bb0 | 2007-02-12 07:15:35 | [diff] [blame] | 1599 | name(s) and modify the new name(s) during the corresponding commit. |
| 1600 | Git performs rename detection after-the-fact, rather than explicitly |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1601 | during a commit.</p></div> |
| 1602 | <h3 id="_use_tag_fixup_branches">Use Tag Fixup Branches</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1603 | <div class="paragraph"><p>Some other SCM systems let the user create a tag from multiple |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1604 | files which are not from the same commit/changeset. Or to create |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1605 | tags which are a subset of the files available in the repository.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1606 | <div class="paragraph"><p>Importing these tags as-is in Git is impossible without making at |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1607 | least one commit which “fixes up” the files to match the content |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1608 | of the tag. Use fast-import’s <tt>reset</tt> command to reset a dummy branch |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1609 | outside of your normal branch space to the base commit for the tag, |
| 1610 | then commit one or more file fixup commits, and finally tag the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1611 | dummy branch.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1612 | <div class="paragraph"><p>For example since all normal branches are stored under <tt>refs/heads/</tt> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1613 | name the tag fixup branch <tt>TAG_FIXUP</tt>. This way it is impossible for |
| 1614 | the fixup branch used by the importer to have namespace conflicts |
| 1615 | with real branches imported from the source (the name <tt>TAG_FIXUP</tt> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1616 | is not <tt>refs/heads/TAG_FIXUP</tt>).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1617 | <div class="paragraph"><p>When committing fixups, consider using <tt>merge</tt> to connect the |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1618 | commit(s) which are supplying file revisions to the fixup branch. |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 1619 | Doing so will allow tools such as <em>git blame</em> to track |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1620 | through the real commit history and properly annotate the source |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1621 | files.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1622 | <div class="paragraph"><p>After fast-import terminates the frontend will need to do <tt>rm .git/TAG_FIXUP</tt> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1623 | to remove the dummy branch.</p></div> |
| 1624 | <h3 id="_import_now_repack_later">Import Now, Repack Later</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1625 | <div class="paragraph"><p>As soon as fast-import completes the Git repository is completely valid |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 1626 | and ready for use. Typically this takes only a very short time, |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1627 | even for considerably large projects (100,000+ commits).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1628 | <div class="paragraph"><p>However repacking the repository is necessary to improve data |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1629 | locality and access performance. It can also take hours on extremely |
| 1630 | large projects (especially if -f and a large --window parameter is |
| 1631 | used). Since repacking is safe to run alongside readers and writers, |
| 1632 | run the repack in the background and let it finish when it finishes. |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1633 | There is no reason to wait to explore your new Git project!</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1634 | <div class="paragraph"><p>If you choose to wait for the repack, don’t try to run benchmarks |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1635 | or performance tests until repacking is completed. fast-import outputs |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1636 | suboptimal packfiles that are simply never seen in real use |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1637 | situations.</p></div> |
| 1638 | <h3 id="_repacking_historical_data">Repacking Historical Data</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1639 | <div class="paragraph"><p>If you are repacking very old imported data (e.g. older than the |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1640 | last year), consider expending some extra CPU time and supplying |
| Junio C Hamano | 1aa40d2 | 2010-01-21 17:46:43 | [diff] [blame] | 1641 | --window=50 (or higher) when you run <em>git repack</em>. |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1642 | This will take longer, but will also produce a smaller packfile. |
| 1643 | You only need to expend the effort once, and everyone using your |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1644 | project will benefit from the smaller repository.</p></div> |
| 1645 | <h3 id="_include_some_progress_messages">Include Some Progress Messages</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1646 | <div class="paragraph"><p>Every once in a while have your frontend emit a <tt>progress</tt> message |
| Junio C Hamano | e52cf78 | 2007-08-19 19:15:52 | [diff] [blame] | 1647 | to fast-import. The contents of the messages are entirely free-form, |
| 1648 | so one suggestion would be to output the current month and year |
| 1649 | each time the current commit date moves into the next month. |
| 1650 | Your users will feel better knowing how much of the data stream |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1651 | has been processed.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1652 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1653 | <h2 id="_packfile_optimization">Packfile Optimization</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1654 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1655 | <div class="paragraph"><p>When packing a blob fast-import always attempts to deltify against the last |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1656 | blob written. Unless specifically arranged for by the frontend, |
| 1657 | this will probably not be a prior version of the same file, so the |
| 1658 | generated delta will not be the smallest possible. The resulting |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1659 | packfile will be compressed, but will not be optimal.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1660 | <div class="paragraph"><p>Frontends which have efficient access to all revisions of a |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1661 | single file (for example reading an RCS/CVS ,v file) can choose |
| 1662 | to supply all revisions of that file as a sequence of consecutive |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1663 | <tt>blob</tt> commands. This allows fast-import to deltify the different file |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1664 | revisions against each other, saving space in the final packfile. |
| 1665 | Marks can be used to later identify individual file revisions during |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1666 | a sequence of <tt>commit</tt> commands.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1667 | <div class="paragraph"><p>The packfile(s) created by fast-import do not encourage good disk access |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1668 | patterns. This is caused by fast-import writing the data in the order |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1669 | it is received on standard input, while Git typically organizes |
| 1670 | data within packfiles to make the most recent (current tip) data |
| 1671 | appear before historical data. Git also clusters commits together, |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1672 | speeding up revision traversal through better cache locality.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1673 | <div class="paragraph"><p>For this reason it is strongly recommended that users repack the |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1674 | repository with <tt>git repack -a -d</tt> after fast-import completes, allowing |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1675 | Git to reorganize the packfiles for faster data access. If blob |
| 1676 | deltas are suboptimal (see above) then also adding the <tt>-f</tt> option |
| 1677 | to force recomputation of all deltas can significantly reduce the |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1678 | final packfile size (30-50% smaller can be quite typical).</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1679 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1680 | <h2 id="_memory_utilization">Memory Utilization</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1681 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1682 | <div class="paragraph"><p>There are a number of factors which affect how much memory fast-import |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1683 | requires to perform an import. Like critical sections of core |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 1684 | Git, fast-import uses its own memory allocators to amortize any overheads |
| 1685 | associated with malloc. In practice fast-import tends to amortize any |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1686 | malloc overheads to 0, due to its use of large block allocations.</p></div> |
| 1687 | <h3 id="_per_object">per object</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1688 | <div class="paragraph"><p>fast-import maintains an in-memory structure for every object written in |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1689 | this execution. On a 32 bit system the structure is 32 bytes, |
| 1690 | on a 64 bit system the structure is 40 bytes (due to the larger |
| 1691 | pointer sizes). Objects in the table are not deallocated until |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1692 | fast-import terminates. Importing 2 million objects on a 32 bit system |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1693 | will require approximately 64 MiB of memory.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1694 | <div class="paragraph"><p>The object table is actually a hashtable keyed on the object name |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1695 | (the unique SHA-1). This storage configuration allows fast-import to reuse |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1696 | an existing or already written object and avoid writing duplicates |
| 1697 | to the output packfile. Duplicate blobs are surprisingly common |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1698 | in an import, typically due to branch merges in the source.</p></div> |
| 1699 | <h3 id="_per_mark">per mark</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1700 | <div class="paragraph"><p>Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1701 | bytes, depending on pointer size) per mark. Although the array |
| 1702 | is sparse, frontends are still strongly encouraged to use marks |
| 1703 | between 1 and n, where n is the total number of marks required for |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1704 | this import.</p></div> |
| 1705 | <h3 id="_per_branch">per branch</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1706 | <div class="paragraph"><p>Branches are classified as active and inactive. The memory usage |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1707 | of the two classes is significantly different.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1708 | <div class="paragraph"><p>Inactive branches are stored in a structure which uses 96 or 120 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1709 | bytes (32 bit or 64 bit systems, respectively), plus the length of |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1710 | the branch name (typically under 200 bytes), per branch. fast-import will |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1711 | easily handle as many as 10,000 inactive branches in under 2 MiB |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1712 | of memory.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1713 | <div class="paragraph"><p>Active branches have the same overhead as inactive branches, but |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1714 | also contain copies of every tree that has been recently modified on |
| 1715 | that branch. If subtree <tt>include</tt> has not been modified since the |
| 1716 | branch became active, its contents will not be loaded into memory, |
| 1717 | but if subtree <tt>src</tt> has been modified by a commit since the branch |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1718 | became active, then its contents will be loaded in memory.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1719 | <div class="paragraph"><p>As active branches store metadata about the files contained on that |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1720 | branch, their in-memory storage size can grow to a considerable size |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1721 | (see below).</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1722 | <div class="paragraph"><p>fast-import automatically moves active branches to inactive status based on |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1723 | a simple least-recently-used algorithm. The LRU chain is updated on |
| 1724 | each <tt>commit</tt> command. The maximum number of active branches can be |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1725 | increased or decreased on the command line with --active-branches=.</p></div> |
| 1726 | <h3 id="_per_active_tree">per active tree</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1727 | <div class="paragraph"><p>Trees (aka directories) use just 12 bytes of memory on top of the |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1728 | memory required for their entries (see “per active file” below). |
| Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 1729 | The cost of a tree is virtually 0, as its overhead amortizes out |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1730 | over the individual file entries.</p></div> |
| 1731 | <h3 id="_per_active_file_entry">per active file entry</h3><div style="clear:left"></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1732 | <div class="paragraph"><p>Files (and pointers to subtrees) within active trees require 52 or 64 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1733 | bytes (32/64 bit platforms) per entry. To conserve space, file and |
| 1734 | tree names are pooled in a common string table, allowing the filename |
| 1735 | “Makefile” to use just 16 bytes (after including the string header |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1736 | overhead) no matter how many times it occurs within the project.</p></div> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1737 | <div class="paragraph"><p>The active branch LRU, when coupled with the filename string pool |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1738 | and lazy loading of subtrees, allows fast-import to efficiently import |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1739 | projects with 2,000+ branches and 45,114+ files in a very limited |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1740 | memory footprint (less than 2.7 MiB per active branch).</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1741 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1742 | <h2 id="_author">Author</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1743 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1744 | <div class="paragraph"><p>Written by Shawn O. Pearce <<a href="mailto:spearce@spearce.org">spearce@spearce.org</a>>.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1745 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1746 | <h2 id="_documentation">Documentation</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1747 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1748 | <div class="paragraph"><p>Documentation by Shawn O. Pearce <<a href="mailto:spearce@spearce.org">spearce@spearce.org</a>>.</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1749 | </div> |
| Junio C Hamano | ba4b928 | 2008-07-06 05:20:31 | [diff] [blame] | 1750 | <h2 id="_git">GIT</h2> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1751 | <div class="sectionbody"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1752 | <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1753 | </div> |
| 1754 | <div id="footer"> |
| 1755 | <div id="footer-text"> |
| Junio C Hamano | 68cf15a | 2010-11-06 01:01:59 | [diff] [blame] | 1756 | Last updated 2010-11-06 00:41:57 UTC |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1757 | </div> |
| 1758 | </div> |
| 1759 | </body> |
| 1760 | </html> |
