| 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" /> |
| 6 | <meta name="generator" content="AsciiDoc 7.0.2" /> |
| 7 | <style type="text/css"> |
| 8 | /* Debug borders */ |
| 9 | p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { |
| 10 | /* |
| 11 | border: 1px solid red; |
| 12 | */ |
| 13 | } |
| 14 | |
| 15 | body { |
| 16 | margin: 1em 5% 1em 5%; |
| 17 | } |
| 18 | |
| 19 | a { color: blue; } |
| 20 | a:visited { color: fuchsia; } |
| 21 | |
| 22 | em { |
| 23 | font-style: italic; |
| 24 | } |
| 25 | |
| 26 | strong { |
| 27 | font-weight: bold; |
| 28 | } |
| 29 | |
| 30 | tt { |
| 31 | color: navy; |
| 32 | } |
| 33 | |
| 34 | h1, h2, h3, h4, h5, h6 { |
| 35 | color: #527bbd; |
| 36 | font-family: sans-serif; |
| 37 | margin-top: 1.2em; |
| 38 | margin-bottom: 0.5em; |
| 39 | line-height: 1.3; |
| 40 | } |
| 41 | |
| 42 | h1 { |
| 43 | border-bottom: 2px solid silver; |
| 44 | } |
| 45 | h2 { |
| 46 | border-bottom: 2px solid silver; |
| 47 | padding-top: 0.5em; |
| 48 | } |
| 49 | |
| 50 | div.sectionbody { |
| 51 | font-family: serif; |
| 52 | margin-left: 0; |
| 53 | } |
| 54 | |
| 55 | hr { |
| 56 | border: 1px solid silver; |
| 57 | } |
| 58 | |
| 59 | p { |
| 60 | margin-top: 0.5em; |
| 61 | margin-bottom: 0.5em; |
| 62 | } |
| 63 | |
| 64 | pre { |
| 65 | padding: 0; |
| 66 | margin: 0; |
| 67 | } |
| 68 | |
| 69 | span#author { |
| 70 | color: #527bbd; |
| 71 | font-family: sans-serif; |
| 72 | font-weight: bold; |
| 73 | font-size: 1.2em; |
| 74 | } |
| 75 | span#email { |
| 76 | } |
| 77 | span#revision { |
| 78 | font-family: sans-serif; |
| 79 | } |
| 80 | |
| 81 | div#footer { |
| 82 | font-family: sans-serif; |
| 83 | font-size: small; |
| 84 | border-top: 2px solid silver; |
| 85 | padding-top: 0.5em; |
| 86 | margin-top: 4.0em; |
| 87 | } |
| 88 | div#footer-text { |
| 89 | float: left; |
| 90 | padding-bottom: 0.5em; |
| 91 | } |
| 92 | div#footer-badges { |
| 93 | float: right; |
| 94 | padding-bottom: 0.5em; |
| 95 | } |
| 96 | |
| 97 | div#preamble, |
| 98 | div.tableblock, div.imageblock, div.exampleblock, div.verseblock, |
| 99 | div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, |
| 100 | div.admonitionblock { |
| 101 | margin-right: 10%; |
| 102 | margin-top: 1.5em; |
| 103 | margin-bottom: 1.5em; |
| 104 | } |
| 105 | div.admonitionblock { |
| 106 | margin-top: 2.5em; |
| 107 | margin-bottom: 2.5em; |
| 108 | } |
| 109 | |
| 110 | div.content { /* Block element content. */ |
| 111 | padding: 0; |
| 112 | } |
| 113 | |
| 114 | /* Block element titles. */ |
| 115 | div.title, caption.title { |
| 116 | font-family: sans-serif; |
| 117 | font-weight: bold; |
| 118 | text-align: left; |
| 119 | margin-top: 1.0em; |
| 120 | margin-bottom: 0.5em; |
| 121 | } |
| 122 | div.title + * { |
| 123 | margin-top: 0; |
| 124 | } |
| 125 | |
| 126 | td div.title:first-child { |
| 127 | margin-top: 0.0em; |
| 128 | } |
| 129 | div.content div.title:first-child { |
| 130 | margin-top: 0.0em; |
| 131 | } |
| 132 | div.content + div.title { |
| 133 | margin-top: 0.0em; |
| 134 | } |
| 135 | |
| 136 | div.sidebarblock > div.content { |
| 137 | background: #ffffee; |
| 138 | border: 1px solid silver; |
| 139 | padding: 0.5em; |
| 140 | } |
| 141 | |
| 142 | div.listingblock > div.content { |
| 143 | border: 1px solid silver; |
| 144 | background: #f4f4f4; |
| 145 | padding: 0.5em; |
| 146 | } |
| 147 | |
| 148 | div.quoteblock > div.content { |
| 149 | padding-left: 2.0em; |
| 150 | } |
| 151 | div.quoteblock .attribution { |
| 152 | text-align: right; |
| 153 | } |
| 154 | |
| 155 | div.admonitionblock .icon { |
| 156 | vertical-align: top; |
| 157 | font-size: 1.1em; |
| 158 | font-weight: bold; |
| 159 | text-decoration: underline; |
| 160 | color: #527bbd; |
| 161 | padding-right: 0.5em; |
| 162 | } |
| 163 | div.admonitionblock td.content { |
| 164 | padding-left: 0.5em; |
| 165 | border-left: 2px solid silver; |
| 166 | } |
| 167 | |
| 168 | div.exampleblock > div.content { |
| 169 | border-left: 2px solid silver; |
| 170 | padding: 0.5em; |
| 171 | } |
| 172 | |
| 173 | div.verseblock div.content { |
| 174 | white-space: pre; |
| 175 | } |
| 176 | |
| 177 | div.imageblock div.content { padding-left: 0; } |
| 178 | div.imageblock img { border: 1px solid silver; } |
| 179 | span.image img { border-style: none; } |
| 180 | |
| 181 | dl { |
| 182 | margin-top: 0.8em; |
| 183 | margin-bottom: 0.8em; |
| 184 | } |
| 185 | dt { |
| 186 | margin-top: 0.5em; |
| 187 | margin-bottom: 0; |
| 188 | font-style: italic; |
| 189 | } |
| 190 | dd > *:first-child { |
| 191 | margin-top: 0; |
| 192 | } |
| 193 | |
| 194 | ul, ol { |
| 195 | list-style-position: outside; |
| 196 | } |
| 197 | ol.olist2 { |
| 198 | list-style-type: lower-alpha; |
| 199 | } |
| 200 | |
| 201 | div.tableblock > table { |
| 202 | border-color: #527bbd; |
| 203 | border-width: 3px; |
| 204 | } |
| 205 | thead { |
| 206 | font-family: sans-serif; |
| 207 | font-weight: bold; |
| 208 | } |
| 209 | tfoot { |
| 210 | font-weight: bold; |
| 211 | } |
| 212 | |
| 213 | div.hlist { |
| 214 | margin-top: 0.8em; |
| 215 | margin-bottom: 0.8em; |
| 216 | } |
| 217 | td.hlist1 { |
| 218 | vertical-align: top; |
| 219 | font-style: italic; |
| 220 | padding-right: 0.8em; |
| 221 | } |
| 222 | td.hlist2 { |
| 223 | vertical-align: top; |
| 224 | } |
| 225 | |
| 226 | @media print { |
| 227 | div#footer-badges { display: none; } |
| 228 | } |
| 229 | include::./stylesheets/xhtml11-manpage.css[] |
| 230 | /* Workarounds for IE6's broken and incomplete CSS2. */ |
| 231 | |
| 232 | div.sidebar-content { |
| 233 | background: #ffffee; |
| 234 | border: 1px solid silver; |
| 235 | padding: 0.5em; |
| 236 | } |
| 237 | div.sidebar-title, div.image-title { |
| 238 | font-family: sans-serif; |
| 239 | font-weight: bold; |
| 240 | margin-top: 0.0em; |
| 241 | margin-bottom: 0.5em; |
| 242 | } |
| 243 | |
| 244 | div.listingblock div.content { |
| 245 | border: 1px solid silver; |
| 246 | background: #f4f4f4; |
| 247 | padding: 0.5em; |
| 248 | } |
| 249 | |
| 250 | div.quoteblock-content { |
| 251 | padding-left: 2.0em; |
| 252 | } |
| 253 | |
| 254 | div.exampleblock-content { |
| 255 | border-left: 2px solid silver; |
| 256 | padding-left: 0.5em; |
| 257 | } |
| 258 | </style> |
| 259 | <title>git-fast-import(1)</title> |
| 260 | </head> |
| 261 | <body> |
| 262 | <div id="header"> |
| 263 | <h1> |
| 264 | git-fast-import(1) Manual Page |
| 265 | </h1> |
| 266 | <h2>NAME</h2> |
| 267 | <div class="sectionbody"> |
| 268 | <p>git-fast-import - |
| Junio C Hamano | 053827f | 2007-02-14 07:23:58 | [diff] [blame] | 269 | Backend for fast Git data importers |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 270 | </p> |
| 271 | </div> |
| 272 | </div> |
| 273 | <h2>SYNOPSIS</h2> |
| 274 | <div class="sectionbody"> |
| 275 | <p>frontend | <em>git-fast-import</em> [options]</p> |
| 276 | </div> |
| 277 | <h2>DESCRIPTION</h2> |
| 278 | <div class="sectionbody"> |
| 279 | <p>This program is usually not what the end user wants to run directly. |
| 280 | Most end users want to use one of the existing frontend programs, |
| 281 | which parses a specific type of foreign source and feeds the contents |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 282 | stored there to git-fast-import.</p> |
| 283 | <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] | 284 | writes one or more packfiles directly into the current repository. |
| 285 | When EOF is received on standard input, fast import writes out |
| 286 | updated branch and tag refs, fully updating the current repository |
| 287 | with the newly imported data.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 288 | <p>The fast-import backend itself can import into an empty repository (one that |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 289 | has already been initialized by <a href="git-init.html">git-init(1)</a>) or incrementally |
| 290 | update an existing populated repository. Whether or not incremental |
| 291 | imports are supported from a particular foreign source depends on |
| 292 | the frontend program in use.</p> |
| 293 | </div> |
| 294 | <h2>OPTIONS</h2> |
| 295 | <div class="sectionbody"> |
| 296 | <dl> |
| 297 | <dt> |
| 298 | --date-format=<fmt> |
| 299 | </dt> |
| 300 | <dd> |
| 301 | <p> |
| 302 | Specify the type of dates the frontend will supply to |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 303 | 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] | 304 | See “Date Formats” below for details about which formats |
| 305 | are supported, and their syntax. |
| 306 | </p> |
| 307 | </dd> |
| 308 | <dt> |
| 309 | --force |
| 310 | </dt> |
| 311 | <dd> |
| 312 | <p> |
| 313 | Force updating modified existing branches, even if doing |
| 314 | so would cause commits to be lost (as the new commit does |
| 315 | not contain the old commit). |
| 316 | </p> |
| 317 | </dd> |
| 318 | <dt> |
| 319 | --max-pack-size=<n> |
| 320 | </dt> |
| 321 | <dd> |
| 322 | <p> |
| 323 | Maximum size of each output packfile, expressed in MiB. |
| 324 | The default is 4096 (4 GiB) as that is the maximum allowed |
| 325 | packfile size (due to file format limitations). Some |
| 326 | importers may wish to lower this, such as to ensure the |
| 327 | resulting packfiles fit on CDs. |
| 328 | </p> |
| 329 | </dd> |
| 330 | <dt> |
| 331 | --depth=<n> |
| 332 | </dt> |
| 333 | <dd> |
| 334 | <p> |
| 335 | Maximum delta depth, for blob and tree deltification. |
| 336 | Default is 10. |
| 337 | </p> |
| 338 | </dd> |
| 339 | <dt> |
| 340 | --active-branches=<n> |
| 341 | </dt> |
| 342 | <dd> |
| 343 | <p> |
| 344 | Maximum number of branches to maintain active at once. |
| 345 | See “Memory Utilization” below for details. Default is 5. |
| 346 | </p> |
| 347 | </dd> |
| 348 | <dt> |
| 349 | --export-marks=<file> |
| 350 | </dt> |
| 351 | <dd> |
| 352 | <p> |
| 353 | Dumps the internal marks table to <file> when complete. |
| 354 | Marks are written one per line as <tt>:markid SHA-1</tt>. |
| 355 | Frontends can use this file to validate imports after they |
| Junio C Hamano | d15328a | 2007-03-09 09:06:40 | [diff] [blame] | 356 | have been completed, or to save the marks table across |
| 357 | incremental runs. As <file> is only opened and truncated |
| 358 | at checkpoint (or completion) the same path can also be |
| 359 | safely given to --import-marks. |
| 360 | </p> |
| 361 | </dd> |
| 362 | <dt> |
| 363 | --import-marks=<file> |
| 364 | </dt> |
| 365 | <dd> |
| 366 | <p> |
| 367 | Before processing any input, load the marks specified in |
| 368 | <file>. The input file must exist, must be readable, and |
| 369 | must use the same format as produced by --export-marks. |
| 370 | Multiple options may be supplied to import more than one |
| 371 | set of marks. If a mark is defined to different values, |
| 372 | the last file wins. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 373 | </p> |
| 374 | </dd> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 375 | <dt> |
| Junio C Hamano | 9dd8bb0 | 2007-02-12 07:15:35 | [diff] [blame] | 376 | --export-pack-edges=<file> |
| 377 | </dt> |
| 378 | <dd> |
| 379 | <p> |
| 380 | After creating a packfile, print a line of data to |
| 381 | <file> listing the filename of the packfile and the last |
| 382 | commit on each branch that was written to that packfile. |
| 383 | This information may be useful after importing projects |
| 384 | whose total object set exceeds the 4 GiB packfile limit, |
| 385 | as these commits can be used as edge points during calls |
| 386 | to <a href="git-pack-objects.html">git-pack-objects(1)</a>. |
| 387 | </p> |
| 388 | </dd> |
| 389 | <dt> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 390 | --quiet |
| 391 | </dt> |
| 392 | <dd> |
| 393 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 394 | Disable all non-fatal output, making fast-import silent when it |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 395 | is successful. This option disables the output shown by |
| 396 | --stats. |
| 397 | </p> |
| 398 | </dd> |
| 399 | <dt> |
| 400 | --stats |
| 401 | </dt> |
| 402 | <dd> |
| 403 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 404 | Display some basic statistics about the objects fast-import has |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 405 | created, the packfiles they were stored into, and the |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 406 | memory used by fast-import during this run. Showing this output |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 407 | is currently the default, but can be disabled with --quiet. |
| 408 | </p> |
| 409 | </dd> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 410 | </dl> |
| 411 | </div> |
| 412 | <h2>Performance</h2> |
| 413 | <div class="sectionbody"> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 414 | <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] | 415 | amount of memory usage and processing time. Assuming the frontend |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 416 | 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] | 417 | import times for projects holding 10+ years of history and containing |
| 418 | 100,000+ individual commits are generally completed in just 1-2 |
| 419 | hours on quite modest (~$2,000 USD) hardware.</p> |
| 420 | <p>Most bottlenecks appear to be in foreign source data access (the |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 421 | source just cannot extract revisions fast enough) or disk IO (fast-import |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 422 | writes as fast as the disk will take the data). Imports will run |
| 423 | faster if the source data is stored on a different drive than the |
| 424 | destination Git repository (due to less IO contention).</p> |
| 425 | </div> |
| 426 | <h2>Development Cost</h2> |
| 427 | <div class="sectionbody"> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 428 | <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] | 429 | lines of Perl/Python/Ruby code. Most developers have been able to |
| 430 | create working importers in just a couple of hours, even though it |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 431 | 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] | 432 | an ideal situation, given that most conversion tools are throw-away |
| 433 | (use once, and never look back).</p> |
| 434 | </div> |
| 435 | <h2>Parallel Operation</h2> |
| 436 | <div class="sectionbody"> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 437 | <p>Like <tt>git-push</tt> or <tt>git-fetch</tt>, imports handled by fast-import are safe to |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 438 | run alongside parallel <tt>git repack -a -d</tt> or <tt>git gc</tt> invocations, |
| 439 | or any other Git operation (including <tt>git prune</tt>, as loose objects |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 440 | are never used by fast-import).</p> |
| 441 | <p>fast-import does not lock the branch or tag refs it is actively importing. |
| 442 | After the import, during its ref update phase, fast-import tests each |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 443 | existing branch ref to verify the update will be a fast-forward |
| 444 | update (the commit stored in the ref is contained in the new |
| 445 | 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] | 446 | fast-forward update, fast-import will skip updating that ref and instead |
| 447 | prints a warning message. fast-import will always attempt to update all |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 448 | branch refs, and does not stop on the first failure.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 449 | <p>Branch updates can be forced with --force, but its recommended that |
| 450 | this only be used on an otherwise quiet repository. Using --force |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 451 | is not necessary for an initial import into an empty repository.</p> |
| 452 | </div> |
| 453 | <h2>Technical Discussion</h2> |
| 454 | <div class="sectionbody"> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 455 | <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] | 456 | or modified at any point during the import process by sending a |
| 457 | <tt>commit</tt> command on the input stream. This design allows a frontend |
| 458 | program to process an unlimited number of branches simultaneously, |
| 459 | generating commits in the order they are available from the source |
| 460 | data. It also simplifies the frontend programs considerably.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 461 | <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] | 462 | file within it. (It does however update the current Git repository, |
| 463 | as referenced by <tt>GIT_DIR</tt>.) Therefore an import frontend may use |
| 464 | the working directory for its own purposes, such as extracting file |
| 465 | revisions from the foreign source. This ignorance of the working |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 466 | 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] | 467 | need to perform any costly file update operations when switching |
| 468 | between branches.</p> |
| 469 | </div> |
| 470 | <h2>Input Format</h2> |
| 471 | <div class="sectionbody"> |
| 472 | <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] | 473 | the fast-import input format is text (ASCII) based. This text based |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 474 | format simplifies development and debugging of frontend programs, |
| 475 | especially when a higher level language such as Perl, Python or |
| 476 | Ruby is being used.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 477 | <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] | 478 | <strong>exactly</strong> one space. Likewise LF means one (and only one) linefeed. |
| 479 | Supplying additional whitespace characters will cause unexpected |
| 480 | results, such as branch names or file names with leading or trailing |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 481 | spaces in their name, or early termination of fast-import when it encounters |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 482 | unexpected input.</p> |
| 483 | <h3>Date Formats</h3> |
| 484 | <p>The following date formats are supported. A frontend should select |
| 485 | the format it will use for this import by passing the format name |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 486 | in the --date-format=<fmt> command line option.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 487 | <dl> |
| 488 | <dt> |
| 489 | <tt>raw</tt> |
| 490 | </dt> |
| 491 | <dd> |
| 492 | <p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 493 | This is the Git native format and is <tt><time> SP <offutc></tt>. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 494 | It is also fast-import's default format, if --date-format was |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 495 | not specified. |
| 496 | </p> |
| 497 | <p>The time of the event is specified by <tt><time></tt> as the number of |
| 498 | seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is |
| 499 | written as an ASCII decimal integer.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 500 | <p>The local offset is specified by <tt><offutc></tt> as a positive or negative |
| 501 | offset from UTC. For example EST (which is 5 hours behind UTC) |
| 502 | would be expressed in <tt><tz></tt> by “-0500” while UTC is “+0000”. |
| 503 | The local offset does not affect <tt><time></tt>; it is used only as an |
| 504 | advisement to help formatting routines display the timestamp.</p> |
| 505 | <p>If the local offset is not available in the source material, use |
| 506 | “+0000”, or the most common local offset. For example many |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 507 | organizations have a CVS repository which has only ever been accessed |
| 508 | by users who are located in the same location and timezone. In this |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 509 | case a reasonable offset from UTC could be assumed.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 510 | <p>Unlike the <tt>rfc2822</tt> format, this format is very strict. Any |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 511 | variation in formatting will cause fast-import to reject the value.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 512 | </dd> |
| 513 | <dt> |
| 514 | <tt>rfc2822</tt> |
| 515 | </dt> |
| 516 | <dd> |
| 517 | <p> |
| 518 | This is the standard email format as described by RFC 2822. |
| 519 | </p> |
| 520 | <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] | 521 | parser is accurate, but a little on the lenient side. It is the |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 522 | same parser used by <a href="git-am.html">git-am(1)</a> when applying patches |
| 523 | received from email.</p> |
| 524 | <p>Some malformed strings may be accepted as valid dates. In some of |
| 525 | these cases Git will still be able to obtain the correct date from |
| 526 | the malformed string. There are also some types of malformed |
| 527 | strings which Git will parse wrong, and yet consider valid. |
| 528 | Seriously malformed strings will be rejected.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 529 | <p>Unlike the <tt>raw</tt> format above, the timezone/UTC offset information |
| 530 | contained in an RFC 2822 date string is used to adjust the date |
| 531 | value to UTC prior to storage. Therefore it is important that |
| 532 | this information be as accurate as possible.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 533 | <p>If the source material uses RFC 2822 style dates, |
| 534 | the frontend should let fast-import handle the parsing and conversion |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 535 | (rather than attempting to do it itself) as the Git parser has |
| 536 | been well tested in the wild.</p> |
| 537 | <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] | 538 | already uses UNIX-epoch format, can be coaxed to give dates in that |
| 539 | format, or its format is easiliy convertible to it, as there is no |
| 540 | ambiguity in parsing.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 541 | </dd> |
| 542 | <dt> |
| 543 | <tt>now</tt> |
| 544 | </dt> |
| 545 | <dd> |
| 546 | <p> |
| 547 | Always use the current time and timezone. The literal |
| 548 | <tt>now</tt> must always be supplied for <tt><when></tt>. |
| 549 | </p> |
| 550 | <p>This is a toy format. The current time and timezone of this system |
| 551 | 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] | 552 | created by fast-import. There is no way to specify a different time or |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 553 | timezone.</p> |
| 554 | <p>This particular format is supplied as its short to implement and |
| 555 | may be useful to a process that wants to create a new commit |
| 556 | right now, without needing to use a working directory or |
| 557 | <a href="git-update-index.html">git-update-index(1)</a>.</p> |
| 558 | <p>If separate <tt>author</tt> and <tt>committer</tt> commands are used in a <tt>commit</tt> |
| 559 | the timestamps may not match, as the system clock will be polled |
| 560 | twice (once for each command). The only way to ensure that both |
| 561 | author and committer identity information has the same timestamp |
| 562 | is to omit <tt>author</tt> (thus copying from <tt>committer</tt>) or to use a |
| 563 | date format other than <tt>now</tt>.</p> |
| 564 | </dd> |
| 565 | </dl> |
| 566 | <h3>Commands</h3> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 567 | <p>fast-import accepts several commands to update the current repository |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 568 | and control the current import process. More detailed discussion |
| 569 | (with examples) of each command follows later.</p> |
| 570 | <dl> |
| 571 | <dt> |
| 572 | <tt>commit</tt> |
| 573 | </dt> |
| 574 | <dd> |
| 575 | <p> |
| 576 | Creates a new branch or updates an existing branch by |
| 577 | creating a new commit and updating the branch to point at |
| 578 | the newly created commit. |
| 579 | </p> |
| 580 | </dd> |
| 581 | <dt> |
| 582 | <tt>tag</tt> |
| 583 | </dt> |
| 584 | <dd> |
| 585 | <p> |
| 586 | Creates an annotated tag object from an existing commit or |
| 587 | branch. Lightweight tags are not supported by this command, |
| 588 | as they are not recommended for recording meaningful points |
| 589 | in time. |
| 590 | </p> |
| 591 | </dd> |
| 592 | <dt> |
| 593 | <tt>reset</tt> |
| 594 | </dt> |
| 595 | <dd> |
| 596 | <p> |
| 597 | Reset an existing branch (or a new branch) to a specific |
| 598 | revision. This command must be used to change a branch to |
| 599 | a specific revision without making a commit on it. |
| 600 | </p> |
| 601 | </dd> |
| 602 | <dt> |
| 603 | <tt>blob</tt> |
| 604 | </dt> |
| 605 | <dd> |
| 606 | <p> |
| 607 | Convert raw file data into a blob, for future use in a |
| 608 | <tt>commit</tt> command. This command is optional and is not |
| 609 | needed to perform an import. |
| 610 | </p> |
| 611 | </dd> |
| 612 | <dt> |
| 613 | <tt>checkpoint</tt> |
| 614 | </dt> |
| 615 | <dd> |
| 616 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 617 | Forces fast-import to close the current packfile, generate its |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 618 | unique SHA-1 checksum and index, and start a new packfile. |
| 619 | This command is optional and is not needed to perform |
| 620 | an import. |
| 621 | </p> |
| 622 | </dd> |
| 623 | </dl> |
| 624 | <h3><tt>commit</tt></h3> |
| 625 | <p>Create or update a branch with a new commit, recording one logical |
| 626 | change to the project.</p> |
| 627 | <div class="literalblock"> |
| 628 | <div class="content"> |
| 629 | <pre><tt> 'commit' SP <ref> LF |
| 630 | mark? |
| 631 | ('author' SP <name> SP LT <email> GT SP <when> LF)? |
| 632 | 'committer' SP <name> SP LT <email> GT SP <when> LF |
| 633 | data |
| 634 | ('from' SP <committish> LF)? |
| 635 | ('merge' SP <committish> LF)? |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 636 | (filemodify | filedelete | filedeleteall)* |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 637 | LF</tt></pre> |
| 638 | </div></div> |
| 639 | <p>where <tt><ref></tt> is the name of the branch to make the commit on. |
| 640 | Typically branch names are prefixed with <tt>refs/heads/</tt> in |
| 641 | Git, so importing the CVS branch symbol <tt>RELENG-1_0</tt> would use |
| 642 | <tt>refs/heads/RELENG-1_0</tt> for the value of <tt><ref></tt>. The value of |
| 643 | <tt><ref></tt> must be a valid refname in Git. As <tt>LF</tt> is not valid in |
| 644 | a Git refname, no quoting or escaping syntax is supported here.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 645 | <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] | 646 | reference to the newly created commit for future use by the frontend |
| 647 | (see below for format). It is very common for frontends to mark |
| 648 | every commit they create, thereby allowing future branch creation |
| 649 | from any imported commit.</p> |
| 650 | <p>The <tt>data</tt> command following <tt>committer</tt> must supply the commit |
| 651 | message (see below for <tt>data</tt> command syntax). To import an empty |
| 652 | commit message use a 0 length data. Commit messages are free-form |
| 653 | and are not interpreted by Git. Currently they must be encoded in |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 654 | UTF-8, as fast-import does not permit other encodings to be specified.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 655 | <p>Zero or more <tt>filemodify</tt>, <tt>filedelete</tt> and <tt>filedeleteall</tt> commands |
| 656 | may be included to update the contents of the branch prior to |
| 657 | creating the commit. These commands may be supplied in any order. |
| 658 | However it is recommended that a <tt>filedeleteall</tt> command preceed |
| 659 | all <tt>filemodify</tt> commands in the same commit, as <tt>filedeleteall</tt> |
| 660 | wipes the branch clean (see below).</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 661 | <h4><tt>author</tt></h4> |
| 662 | <p>An <tt>author</tt> command may optionally appear, if the author information |
| 663 | might differ from the committer information. If <tt>author</tt> is omitted |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 664 | then fast-import will automatically use the committer's information for |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 665 | the author portion of the commit. See below for a description of |
| 666 | the fields in <tt>author</tt>, as they are identical to <tt>committer</tt>.</p> |
| 667 | <h4><tt>committer</tt></h4> |
| 668 | <p>The <tt>committer</tt> command indicates who made this commit, and when |
| 669 | they made it.</p> |
| 670 | <p>Here <tt><name></tt> is the person's display name (for example |
| 671 | “Com M Itter”) and <tt><email></tt> is the person's email address |
| 672 | (“cm@example.com”). <tt>LT</tt> and <tt>GT</tt> are the literal less-than (\x3c) |
| 673 | and greater-than (\x3e) symbols. These are required to delimit |
| 674 | the email address from the other fields in the line. Note that |
| 675 | <tt><name></tt> is free-form and may contain any sequence of bytes, except |
| 676 | <tt>LT</tt> and <tt>LF</tt>. It is typically UTF-8 encoded.</p> |
| 677 | <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] | 678 | that was selected by the --date-format=<fmt> command line option. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 679 | See “Date Formats” above for the set of supported formats, and |
| 680 | their syntax.</p> |
| 681 | <h4><tt>from</tt></h4> |
| Junio C Hamano | 5dad083 | 2007-02-13 05:16:23 | [diff] [blame] | 682 | <p>The <tt>from</tt> command is used to specify the commit to initialize |
| 683 | this branch from. This revision will be the first ancestor of the |
| 684 | new commit.</p> |
| 685 | <p>Omitting the <tt>from</tt> command in the first commit of a new branch |
| 686 | will cause fast-import to create that commit with no ancestor. This |
| 687 | tends to be desired only for the initial commit of a project. |
| 688 | Omitting the <tt>from</tt> command on existing branches is usually desired, |
| 689 | as the current commit on that branch is automatically assumed to |
| 690 | be the first ancestor of the new commit.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 691 | <p>As <tt>LF</tt> is not valid in a Git refname or SHA-1 expression, no |
| 692 | quoting or escaping syntax is supported within <tt><committish></tt>.</p> |
| 693 | <p>Here <tt><committish></tt> is any of the following:</p> |
| 694 | <ul> |
| 695 | <li> |
| 696 | <p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 697 | The name of an existing branch already in fast-import's internal branch |
| 698 | table. If fast-import doesn't know the name, its treated as a SHA-1 |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 699 | expression. |
| 700 | </p> |
| 701 | </li> |
| 702 | <li> |
| 703 | <p> |
| 704 | A mark reference, <tt>:<idnum></tt>, where <tt><idnum></tt> is the mark number. |
| 705 | </p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 706 | <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] | 707 | is not legal in a Git branch name. The leading <tt>:</tt> makes it easy |
| 708 | to distingush between the mark 42 (<tt>:42</tt>) and the branch 42 (<tt>42</tt> |
| 709 | or <tt>refs/heads/42</tt>), or an abbreviated SHA-1 which happened to |
| 710 | consist only of base-10 digits.</p> |
| 711 | <p>Marks must be declared (via <tt>mark</tt>) before they can be used.</p> |
| 712 | </li> |
| 713 | <li> |
| 714 | <p> |
| 715 | A complete 40 byte or abbreviated commit SHA-1 in hex. |
| 716 | </p> |
| 717 | </li> |
| 718 | <li> |
| 719 | <p> |
| 720 | Any valid Git SHA-1 expression that resolves to a commit. See |
| 721 | “SPECIFYING REVISIONS” in <a href="git-rev-parse.html">git-rev-parse(1)</a> for details. |
| 722 | </p> |
| 723 | </li> |
| 724 | </ul> |
| 725 | <p>The special case of restarting an incremental import from the |
| 726 | current branch value should be written as:</p> |
| 727 | <div class="listingblock"> |
| 728 | <div class="content"> |
| 729 | <pre><tt> from refs/heads/branch^0</tt></pre> |
| 730 | </div></div> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 731 | <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] | 732 | start from itself, and the branch is created in memory before the |
| 733 | <tt>from</tt> command is even read from the input. Adding <tt>^0</tt> will force |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 734 | fast-import to resolve the commit through Git's revision parsing library, |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 735 | rather than its internal branch table, thereby loading in the |
| 736 | existing value of the branch.</p> |
| 737 | <h4><tt>merge</tt></h4> |
| 738 | <p>Includes one additional ancestor commit, and makes the current |
| 739 | commit a merge commit. An unlimited number of <tt>merge</tt> commands per |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 740 | commit are permitted by fast-import, thereby establishing an n-way merge. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 741 | However Git's other tools never create commits with more than 15 |
| 742 | additional ancestors (forming a 16-way merge). For this reason |
| 743 | it is suggested that frontends do not use more than 15 <tt>merge</tt> |
| 744 | commands per commit.</p> |
| 745 | <p>Here <tt><committish></tt> is any of the commit specification expressions |
| 746 | also accepted by <tt>from</tt> (see above).</p> |
| 747 | <h4><tt>filemodify</tt></h4> |
| 748 | <p>Included in a <tt>commit</tt> command to add a new file or change the |
| 749 | content of an existing file. This command has two different means |
| 750 | of specifying the content of the file.</p> |
| 751 | <dl> |
| 752 | <dt> |
| 753 | External data format |
| 754 | </dt> |
| 755 | <dd> |
| 756 | <p> |
| 757 | The data content for the file was already supplied by a prior |
| 758 | <tt>blob</tt> command. The frontend just needs to connect it. |
| 759 | </p> |
| 760 | <div class="literalblock"> |
| 761 | <div class="content"> |
| 762 | <pre><tt> 'M' SP <mode> SP <dataref> SP <path> LF</tt></pre> |
| 763 | </div></div> |
| 764 | <p>Here <tt><dataref></tt> can be either a mark reference (<tt>:<idnum></tt>) |
| 765 | set by a prior <tt>blob</tt> command, or a full 40-byte SHA-1 of an |
| 766 | existing Git blob object.</p> |
| 767 | </dd> |
| 768 | <dt> |
| 769 | Inline data format |
| 770 | </dt> |
| 771 | <dd> |
| 772 | <p> |
| 773 | The data content for the file has not been supplied yet. |
| 774 | The frontend wants to supply it as part of this modify |
| 775 | command. |
| 776 | </p> |
| 777 | <div class="literalblock"> |
| 778 | <div class="content"> |
| 779 | <pre><tt> 'M' SP <mode> SP 'inline' SP <path> LF |
| 780 | data</tt></pre> |
| 781 | </div></div> |
| 782 | <p>See below for a detailed description of the <tt>data</tt> command.</p> |
| 783 | </dd> |
| 784 | </dl> |
| 785 | <p>In both formats <tt><mode></tt> is the type of file entry, specified |
| 786 | in octal. Git only supports the following modes:</p> |
| 787 | <ul> |
| 788 | <li> |
| 789 | <p> |
| 790 | <tt>100644</tt> or <tt>644</tt>: A normal (not-executable) file. The majority |
| 791 | of files in most projects use this mode. If in doubt, this is |
| 792 | what you want. |
| 793 | </p> |
| 794 | </li> |
| 795 | <li> |
| 796 | <p> |
| 797 | <tt>100755</tt> or <tt>755</tt>: A normal, but executable, file. |
| 798 | </p> |
| 799 | </li> |
| 800 | <li> |
| 801 | <p> |
| 802 | <tt>120000</tt>: A symlink, the content of the file will be the link target. |
| 803 | </p> |
| 804 | </li> |
| 805 | </ul> |
| 806 | <p>In both formats <tt><path></tt> is the complete path of the file to be added |
| 807 | (if not already existing) or modified (if already existing).</p> |
| Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame^] | 808 | <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] | 809 | slash <tt>/</tt>), may contain any byte other than <tt>LF</tt>, and must not |
| 810 | start with double quote (<tt>"</tt>).</p> |
| 811 | <p>If an <tt>LF</tt> or double quote must be encoded into <tt><path></tt> shell-style |
| 812 | quoting should be used, e.g. <tt>"path/with\n and \" in it"</tt>.</p> |
| 813 | <p>The value of <tt><path></tt> must be in canoncial form. That is it must not:</p> |
| 814 | <ul> |
| 815 | <li> |
| 816 | <p> |
| 817 | contain an empty directory component (e.g. <tt>foo//bar</tt> is invalid), |
| 818 | </p> |
| 819 | </li> |
| 820 | <li> |
| 821 | <p> |
| Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame^] | 822 | end with a directory separator (e.g. <tt>foo/</tt> is invalid), |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 823 | </p> |
| 824 | </li> |
| 825 | <li> |
| 826 | <p> |
| Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame^] | 827 | start with a directory separator (e.g. <tt>/foo</tt> is invalid), |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 828 | </p> |
| 829 | </li> |
| 830 | <li> |
| 831 | <p> |
| 832 | contain the special component <tt>.</tt> or <tt>..</tt> (e.g. <tt>foo/./bar</tt> and |
| 833 | <tt>foo/../bar</tt> are invalid). |
| 834 | </p> |
| 835 | </li> |
| 836 | </ul> |
| 837 | <p>It is recommended that <tt><path></tt> always be encoded using UTF-8.</p> |
| 838 | <h4><tt>filedelete</tt></h4> |
| 839 | <p>Included in a <tt>commit</tt> command to remove a file from the branch. |
| 840 | If the file removal makes its directory empty, the directory will |
| 841 | be automatically removed too. This cascades up the tree until the |
| 842 | first non-empty directory or the root is reached.</p> |
| 843 | <div class="literalblock"> |
| 844 | <div class="content"> |
| 845 | <pre><tt> 'D' SP <path> LF</tt></pre> |
| 846 | </div></div> |
| 847 | <p>here <tt><path></tt> is the complete path of the file to be removed. |
| 848 | See <tt>filemodify</tt> above for a detailed description of <tt><path></tt>.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 849 | <h4><tt>filedeleteall</tt></h4> |
| 850 | <p>Included in a <tt>commit</tt> command to remove all files (and also all |
| 851 | directories) from the branch. This command resets the internal |
| 852 | branch structure to have no files in it, allowing the frontend |
| 853 | to subsequently add all interesting files from scratch.</p> |
| 854 | <div class="literalblock"> |
| 855 | <div class="content"> |
| 856 | <pre><tt> 'deleteall' LF</tt></pre> |
| 857 | </div></div> |
| 858 | <p>This command is extremely useful if the frontend does not know |
| 859 | (or does not care to know) what files are currently on the branch, |
| 860 | and therefore cannot generate the proper <tt>filedelete</tt> commands to |
| 861 | update the content.</p> |
| 862 | <p>Issuing a <tt>filedeleteall</tt> followed by the needed <tt>filemodify</tt> |
| 863 | commands to set the correct content will produce the same results |
| 864 | 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] | 865 | 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] | 866 | more memory per active branch (less than 1 MiB for even most large |
| 867 | projects); so frontends that can easily obtain only the affected |
| 868 | paths for a commit are encouraged to do so.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 869 | <h3><tt>mark</tt></h3> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 870 | <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] | 871 | the frontend to recall this object at a future point in time, without |
| 872 | knowing its SHA-1. Here the current object is the object creation |
| 873 | command the <tt>mark</tt> command appears within. This can be <tt>commit</tt>, |
| 874 | <tt>tag</tt>, and <tt>blob</tt>, but <tt>commit</tt> is the most common usage.</p> |
| 875 | <div class="literalblock"> |
| 876 | <div class="content"> |
| 877 | <pre><tt> 'mark' SP ':' <idnum> LF</tt></pre> |
| 878 | </div></div> |
| 879 | <p>where <tt><idnum></tt> is the number assigned by the frontend to this mark. |
| 880 | The value of <tt><idnum></tt> is expressed as an ASCII decimal integer. |
| 881 | The value 0 is reserved and cannot be used as |
| 882 | a mark. Only values greater than or equal to 1 may be used as marks.</p> |
| 883 | <p>New marks are created automatically. Existing marks can be moved |
| 884 | to another object simply by reusing the same <tt><idnum></tt> in another |
| 885 | <tt>mark</tt> command.</p> |
| 886 | <h3><tt>tag</tt></h3> |
| 887 | <p>Creates an annotated tag referring to a specific commit. To create |
| 888 | lightweight (non-annotated) tags see the <tt>reset</tt> command below.</p> |
| 889 | <div class="literalblock"> |
| 890 | <div class="content"> |
| 891 | <pre><tt> 'tag' SP <name> LF |
| 892 | 'from' SP <committish> LF |
| 893 | 'tagger' SP <name> SP LT <email> GT SP <when> LF |
| 894 | data |
| 895 | LF</tt></pre> |
| 896 | </div></div> |
| 897 | <p>where <tt><name></tt> is the name of the tag to create.</p> |
| 898 | <p>Tag names are automatically prefixed with <tt>refs/tags/</tt> when stored |
| 899 | 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] | 900 | use just <tt>RELENG-1_0-FINAL</tt> for <tt><name></tt>, and fast-import will write the |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 901 | corresponding ref as <tt>refs/tags/RELENG-1_0-FINAL</tt>.</p> |
| 902 | <p>The value of <tt><name></tt> must be a valid refname in Git and therefore |
| 903 | may contain forward slashes. As <tt>LF</tt> is not valid in a Git refname, |
| 904 | no quoting or escaping syntax is supported here.</p> |
| 905 | <p>The <tt>from</tt> command is the same as in the <tt>commit</tt> command; see |
| 906 | above for details.</p> |
| 907 | <p>The <tt>tagger</tt> command uses the same format as <tt>committer</tt> within |
| 908 | <tt>commit</tt>; again see above for details.</p> |
| 909 | <p>The <tt>data</tt> command following <tt>tagger</tt> must supply the annotated tag |
| 910 | message (see below for <tt>data</tt> command syntax). To import an empty |
| 911 | tag message use a 0 length data. Tag messages are free-form and are |
| 912 | not interpreted by Git. Currently they must be encoded in UTF-8, |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 913 | as fast-import does not permit other encodings to be specified.</p> |
| 914 | <p>Signing annotated tags during import from within fast-import is not |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 915 | supported. Trying to include your own PGP/GPG signature is not |
| 916 | recommended, as the frontend does not (easily) have access to the |
| 917 | complete set of bytes which normally goes into such a signature. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 918 | If signing is required, create lightweight tags from within fast-import with |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 919 | <tt>reset</tt>, then create the annotated versions of those tags offline |
| 920 | with the standard <a href="git-tag.html">git-tag(1)</a> process.</p> |
| 921 | <h3><tt>reset</tt></h3> |
| 922 | <p>Creates (or recreates) the named branch, optionally starting from |
| 923 | a specific revision. The reset command allows a frontend to issue |
| 924 | a new <tt>from</tt> command for an existing branch, or to create a new |
| 925 | branch from an existing commit without creating a new commit.</p> |
| 926 | <div class="literalblock"> |
| 927 | <div class="content"> |
| 928 | <pre><tt> 'reset' SP <ref> LF |
| 929 | ('from' SP <committish> LF)? |
| 930 | LF</tt></pre> |
| 931 | </div></div> |
| 932 | <p>For a detailed description of <tt><ref></tt> and <tt><committish></tt> see above |
| 933 | under <tt>commit</tt> and <tt>from</tt>.</p> |
| 934 | <p>The <tt>reset</tt> command can also be used to create lightweight |
| 935 | (non-annotated) tags. For example:</p> |
| 936 | <div class="exampleblock"> |
| 937 | <div class="exampleblock-content"> |
| 938 | <div class="literalblock"> |
| 939 | <div class="content"> |
| 940 | <pre><tt>reset refs/tags/938 |
| 941 | from :938</tt></pre> |
| 942 | </div></div> |
| 943 | </div></div> |
| 944 | <p>would create the lightweight tag <tt>refs/tags/938</tt> referring to |
| 945 | whatever commit mark <tt>:938</tt> references.</p> |
| 946 | <h3><tt>blob</tt></h3> |
| 947 | <p>Requests writing one file revision to the packfile. The revision |
| 948 | is not connected to any commit; this connection must be formed in |
| 949 | a subsequent <tt>commit</tt> command by referencing the blob through an |
| 950 | assigned mark.</p> |
| 951 | <div class="literalblock"> |
| 952 | <div class="content"> |
| 953 | <pre><tt> 'blob' LF |
| 954 | mark? |
| 955 | data</tt></pre> |
| 956 | </div></div> |
| 957 | <p>The mark command is optional here as some frontends have chosen |
| 958 | to generate the Git SHA-1 for the blob on their own, and feed that |
| 959 | directly to <tt>commit</tt>. This is typically more work than its worth |
| 960 | however, as marks are inexpensive to store and easy to use.</p> |
| 961 | <h3><tt>data</tt></h3> |
| 962 | <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] | 963 | 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] | 964 | byte count or delimited with a terminating line. Real frontends |
| 965 | intended for production-quality conversions should always use the |
| 966 | exact byte count format, as it is more robust and performs better. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 967 | The delimited format is intended primarily for testing fast-import.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 968 | <dl> |
| 969 | <dt> |
| 970 | Exact byte count format |
| 971 | </dt> |
| 972 | <dd> |
| 973 | <p> |
| 974 | The frontend must specify the number of bytes of data. |
| 975 | </p> |
| 976 | <div class="literalblock"> |
| 977 | <div class="content"> |
| 978 | <pre><tt> 'data' SP <count> LF |
| 979 | <raw> LF</tt></pre> |
| 980 | </div></div> |
| 981 | <p>where <tt><count></tt> is the exact number of bytes appearing within |
| 982 | <tt><raw></tt>. The value of <tt><count></tt> is expressed as an ASCII decimal |
| 983 | integer. The <tt>LF</tt> on either side of <tt><raw></tt> is not |
| 984 | included in <tt><count></tt> and will not be included in the imported data.</p> |
| 985 | </dd> |
| 986 | <dt> |
| 987 | Delimited format |
| 988 | </dt> |
| 989 | <dd> |
| 990 | <p> |
| 991 | A delimiter string is used to mark the end of the data. |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 992 | fast-import will compute the length by searching for the delimiter. |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 993 | This format is primarly useful for testing and is not |
| 994 | recommended for real data. |
| 995 | </p> |
| 996 | <div class="literalblock"> |
| 997 | <div class="content"> |
| 998 | <pre><tt> 'data' SP '<<' <delim> LF |
| 999 | <raw> LF |
| 1000 | <delim> LF</tt></pre> |
| 1001 | </div></div> |
| 1002 | <p>where <tt><delim></tt> is the chosen delimiter string. The string <tt><delim></tt> |
| 1003 | 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] | 1004 | 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] | 1005 | immediately trailing <tt><raw></tt> is part of <tt><raw></tt>. This is one of |
| 1006 | the limitations of the delimited format, it is impossible to supply |
| 1007 | a data chunk which does not have an LF as its last byte.</p> |
| 1008 | </dd> |
| 1009 | </dl> |
| 1010 | <h3><tt>checkpoint</tt></h3> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1011 | <p>Forces fast-import to close the current packfile, start a new one, and to |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1012 | save out all current branch refs, tags and marks.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1013 | <div class="literalblock"> |
| 1014 | <div class="content"> |
| 1015 | <pre><tt> 'checkpoint' LF |
| 1016 | LF</tt></pre> |
| 1017 | </div></div> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1018 | <p>Note that fast-import automatically switches packfiles when the current |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1019 | packfile reaches --max-pack-size, or 4 GiB, whichever limit is |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1020 | smaller. During an automatic packfile switch fast-import does not update |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1021 | the branch refs, tags or marks.</p> |
| 1022 | <p>As a <tt>checkpoint</tt> can require a significant amount of CPU time and |
| 1023 | disk IO (to compute the overall pack SHA-1 checksum, generate the |
| 1024 | corresponding index file, and update the refs) it can easily take |
| 1025 | several minutes for a single <tt>checkpoint</tt> command to complete.</p> |
| 1026 | <p>Frontends may choose to issue checkpoints during extremely large |
| 1027 | and long running imports, or when they need to allow another Git |
| 1028 | process access to a branch. However given that a 30 GiB Subversion |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1029 | repository can be loaded into Git through fast-import in about 3 hours, |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1030 | explicit checkpointing may not be necessary.</p> |
| 1031 | </div> |
| 1032 | <h2>Tips and Tricks</h2> |
| 1033 | <div class="sectionbody"> |
| 1034 | <p>The following tips and tricks have been collected from various |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1035 | users of fast-import, and are offered here as suggestions.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1036 | <h3>Use One Mark Per Commit</h3> |
| 1037 | <p>When doing a repository conversion, use a unique mark per commit |
| 1038 | (<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] | 1039 | 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] | 1040 | object SHA-1 that corresponds to it. If the frontend can tie |
| 1041 | the marks back to the source repository, it is easy to verify the |
| 1042 | accuracy and completeness of the import by comparing each Git |
| 1043 | commit to the corresponding source revision.</p> |
| 1044 | <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] | 1045 | quite simple, as the fast-import mark can also be the Perforce changeset |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1046 | number or the Subversion revision number.</p> |
| 1047 | <h3>Freely Skip Around Branches</h3> |
| 1048 | <p>Don't bother trying to optimize the frontend to stick to one branch |
| 1049 | at a time during an import. Although doing so might be slightly |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1050 | faster for fast-import, it tends to increase the complexity of the frontend |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1051 | code considerably.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1052 | <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] | 1053 | cost of activating an inactive branch is so low that bouncing around |
| 1054 | between branches has virtually no impact on import performance.</p> |
| Junio C Hamano | 9dd8bb0 | 2007-02-12 07:15:35 | [diff] [blame] | 1055 | <h3>Handling Renames</h3> |
| 1056 | <p>When importing a renamed file or directory, simply delete the old |
| 1057 | name(s) and modify the new name(s) during the corresponding commit. |
| 1058 | Git performs rename detection after-the-fact, rather than explicitly |
| 1059 | during a commit.</p> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1060 | <h3>Use Tag Fixup Branches</h3> |
| 1061 | <p>Some other SCM systems let the user create a tag from multiple |
| 1062 | files which are not from the same commit/changeset. Or to create |
| 1063 | tags which are a subset of the files available in the repository.</p> |
| 1064 | <p>Importing these tags as-is in Git is impossible without making at |
| 1065 | least one commit which “fixes up” the files to match the content |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1066 | 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] | 1067 | outside of your normal branch space to the base commit for the tag, |
| 1068 | then commit one or more file fixup commits, and finally tag the |
| 1069 | dummy branch.</p> |
| 1070 | <p>For example since all normal branches are stored under <tt>refs/heads/</tt> |
| 1071 | name the tag fixup branch <tt>TAG_FIXUP</tt>. This way it is impossible for |
| 1072 | the fixup branch used by the importer to have namespace conflicts |
| 1073 | with real branches imported from the source (the name <tt>TAG_FIXUP</tt> |
| 1074 | is not <tt>refs/heads/TAG_FIXUP</tt>).</p> |
| 1075 | <p>When committing fixups, consider using <tt>merge</tt> to connect the |
| 1076 | commit(s) which are supplying file revisions to the fixup branch. |
| 1077 | Doing so will allow tools such as <a href="git-blame.html">git-blame(1)</a> to track |
| 1078 | through the real commit history and properly annotate the source |
| 1079 | files.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1080 | <p>After fast-import terminates the frontend will need to do <tt>rm .git/TAG_FIXUP</tt> |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1081 | to remove the dummy branch.</p> |
| 1082 | <h3>Import Now, Repack Later</h3> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1083 | <p>As soon as fast-import completes the Git repository is completely valid |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1084 | and ready for use. Typicallly this takes only a very short time, |
| 1085 | even for considerably large projects (100,000+ commits).</p> |
| 1086 | <p>However repacking the repository is necessary to improve data |
| 1087 | locality and access performance. It can also take hours on extremely |
| 1088 | large projects (especially if -f and a large --window parameter is |
| 1089 | used). Since repacking is safe to run alongside readers and writers, |
| 1090 | run the repack in the background and let it finish when it finishes. |
| 1091 | There is no reason to wait to explore your new Git project!</p> |
| 1092 | <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] | 1093 | or performance tests until repacking is completed. fast-import outputs |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1094 | suboptimal packfiles that are simply never seen in real use |
| 1095 | situations.</p> |
| 1096 | <h3>Repacking Historical Data</h3> |
| 1097 | <p>If you are repacking very old imported data (e.g. older than the |
| 1098 | last year), consider expending some extra CPU time and supplying |
| 1099 | --window=50 (or higher) when you run <a href="git-repack.html">git-repack(1)</a>. |
| 1100 | This will take longer, but will also produce a smaller packfile. |
| 1101 | You only need to expend the effort once, and everyone using your |
| 1102 | project will benefit from the smaller repository.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1103 | </div> |
| 1104 | <h2>Packfile Optimization</h2> |
| 1105 | <div class="sectionbody"> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1106 | <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] | 1107 | blob written. Unless specifically arranged for by the frontend, |
| 1108 | this will probably not be a prior version of the same file, so the |
| 1109 | generated delta will not be the smallest possible. The resulting |
| 1110 | packfile will be compressed, but will not be optimal.</p> |
| 1111 | <p>Frontends which have efficient access to all revisions of a |
| 1112 | single file (for example reading an RCS/CVS ,v file) can choose |
| 1113 | to supply all revisions of that file as a sequence of consecutive |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1114 | <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] | 1115 | revisions against each other, saving space in the final packfile. |
| 1116 | Marks can be used to later identify individual file revisions during |
| 1117 | a sequence of <tt>commit</tt> commands.</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1118 | <p>The packfile(s) created by fast-import do not encourage good disk access |
| 1119 | 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] | 1120 | it is received on standard input, while Git typically organizes |
| 1121 | data within packfiles to make the most recent (current tip) data |
| 1122 | appear before historical data. Git also clusters commits together, |
| 1123 | speeding up revision traversal through better cache locality.</p> |
| 1124 | <p>For this reason it is strongly recommended that users repack the |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1125 | 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] | 1126 | Git to reorganize the packfiles for faster data access. If blob |
| 1127 | deltas are suboptimal (see above) then also adding the <tt>-f</tt> option |
| 1128 | to force recomputation of all deltas can significantly reduce the |
| 1129 | final packfile size (30-50% smaller can be quite typical).</p> |
| 1130 | </div> |
| 1131 | <h2>Memory Utilization</h2> |
| 1132 | <div class="sectionbody"> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1133 | <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] | 1134 | requires to perform an import. Like critical sections of core |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1135 | Git, fast-import uses its own memory allocators to ammortize any overheads |
| 1136 | associated with malloc. In practice fast-import tends to ammoritize any |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1137 | malloc overheads to 0, due to its use of large block allocations.</p> |
| 1138 | <h3>per object</h3> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1139 | <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] | 1140 | this execution. On a 32 bit system the structure is 32 bytes, |
| 1141 | on a 64 bit system the structure is 40 bytes (due to the larger |
| 1142 | pointer sizes). Objects in the table are not deallocated until |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1143 | fast-import terminates. Importing 2 million objects on a 32 bit system |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1144 | will require approximately 64 MiB of memory.</p> |
| 1145 | <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] | 1146 | (the unique SHA-1). This storage configuration allows fast-import to reuse |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1147 | an existing or already written object and avoid writing duplicates |
| 1148 | to the output packfile. Duplicate blobs are surprisingly common |
| 1149 | in an import, typically due to branch merges in the source.</p> |
| 1150 | <h3>per mark</h3> |
| 1151 | <p>Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 |
| 1152 | bytes, depending on pointer size) per mark. Although the array |
| 1153 | is sparse, frontends are still strongly encouraged to use marks |
| 1154 | between 1 and n, where n is the total number of marks required for |
| 1155 | this import.</p> |
| 1156 | <h3>per branch</h3> |
| 1157 | <p>Branches are classified as active and inactive. The memory usage |
| 1158 | of the two classes is significantly different.</p> |
| 1159 | <p>Inactive branches are stored in a structure which uses 96 or 120 |
| 1160 | bytes (32 bit or 64 bit systems, respectively), plus the length of |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1161 | the branch name (typically under 200 bytes), per branch. fast-import will |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1162 | easily handle as many as 10,000 inactive branches in under 2 MiB |
| 1163 | of memory.</p> |
| 1164 | <p>Active branches have the same overhead as inactive branches, but |
| 1165 | also contain copies of every tree that has been recently modified on |
| 1166 | that branch. If subtree <tt>include</tt> has not been modified since the |
| 1167 | branch became active, its contents will not be loaded into memory, |
| 1168 | but if subtree <tt>src</tt> has been modified by a commit since the branch |
| 1169 | became active, then its contents will be loaded in memory.</p> |
| 1170 | <p>As active branches store metadata about the files contained on that |
| 1171 | branch, their in-memory storage size can grow to a considerable size |
| 1172 | (see below).</p> |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1173 | <p>fast-import automatically moves active branches to inactive status based on |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1174 | a simple least-recently-used algorithm. The LRU chain is updated on |
| 1175 | each <tt>commit</tt> command. The maximum number of active branches can be |
| Junio C Hamano | dfc4ce7 | 2007-02-07 23:17:29 | [diff] [blame] | 1176 | increased or decreased on the command line with --active-branches=.</p> |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1177 | <h3>per active tree</h3> |
| 1178 | <p>Trees (aka directories) use just 12 bytes of memory on top of the |
| 1179 | memory required for their entries (see “per active file” below). |
| 1180 | The cost of a tree is virtually 0, as its overhead ammortizes out |
| 1181 | over the individual file entries.</p> |
| 1182 | <h3>per active file entry</h3> |
| 1183 | <p>Files (and pointers to subtrees) within active trees require 52 or 64 |
| 1184 | bytes (32/64 bit platforms) per entry. To conserve space, file and |
| 1185 | tree names are pooled in a common string table, allowing the filename |
| 1186 | “Makefile” to use just 16 bytes (after including the string header |
| 1187 | overhead) no matter how many times it occurs within the project.</p> |
| 1188 | <p>The active branch LRU, when coupled with the filename string pool |
| Junio C Hamano | d333998 | 2007-02-09 08:38:48 | [diff] [blame] | 1189 | and lazy loading of subtrees, allows fast-import to efficiently import |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1190 | projects with 2,000+ branches and 45,114+ files in a very limited |
| 1191 | memory footprint (less than 2.7 MiB per active branch).</p> |
| 1192 | </div> |
| 1193 | <h2>Author</h2> |
| 1194 | <div class="sectionbody"> |
| 1195 | <p>Written by Shawn O. Pearce <spearce@spearce.org>.</p> |
| 1196 | </div> |
| 1197 | <h2>Documentation</h2> |
| 1198 | <div class="sectionbody"> |
| 1199 | <p>Documentation by Shawn O. Pearce <spearce@spearce.org>.</p> |
| 1200 | </div> |
| 1201 | <h2>GIT</h2> |
| 1202 | <div class="sectionbody"> |
| 1203 | <p>Part of the <a href="git.html">git(7)</a> suite</p> |
| 1204 | </div> |
| 1205 | <div id="footer"> |
| 1206 | <div id="footer-text"> |
| Junio C Hamano | c51fede | 2007-03-12 07:29:20 | [diff] [blame^] | 1207 | Last updated 12-Mar-2007 07:28:53 UTC |
| Junio C Hamano | df60f44 | 2007-02-07 05:52:37 | [diff] [blame] | 1208 | </div> |
| 1209 | </div> |
| 1210 | </body> |
| 1211 | </html> |
