| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [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 | 5f32776 | 2006-03-02 09:14:51 | [diff] [blame] | 6 | <meta name="generator" content="AsciiDoc 7.0.2" /> |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 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-read-tree(1)</title> |
| 260 | </head> |
| 261 | <body> |
| 262 | <div id="header"> |
| 263 | <h1> |
| 264 | git-read-tree(1) Manual Page |
| 265 | </h1> |
| 266 | <h2>NAME</h2> |
| 267 | <div class="sectionbody"> |
| 268 | <p>git-read-tree - |
| 269 | Reads tree information into the index |
| 270 | </p> |
| 271 | </div> |
| 272 | </div> |
| 273 | <h2>SYNOPSIS</h2> |
| 274 | <div class="sectionbody"> |
| Junio C Hamano | ee695f2 | 2007-06-21 00:35:36 | [diff] [blame] | 275 | <p><em>git-read-tree</em> (<tree-ish> | [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]])</p> |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 276 | </div> |
| 277 | <h2>DESCRIPTION</h2> |
| 278 | <div class="sectionbody"> |
| 279 | <p>Reads the tree information given by <tree-ish> into the index, |
| 280 | but does not actually <strong>update</strong> any of the files it "caches". (see: |
| 281 | <a href="git-checkout-index.html">git-checkout-index(1)</a>)</p> |
| 282 | <p>Optionally, it can merge a tree into the index, perform a |
| 283 | fast-forward (i.e. 2-way) merge, or a 3-way merge, with the <tt>-m</tt> |
| 284 | flag. When used with <tt>-m</tt>, the <tt>-u</tt> flag causes it to also update |
| 285 | the files in the work tree with the result of the merge.</p> |
| 286 | <p>Trivial merges are done by <tt>git-read-tree</tt> itself. Only conflicting paths |
| 287 | will be in unmerged state when <tt>git-read-tree</tt> returns.</p> |
| 288 | </div> |
| 289 | <h2>OPTIONS</h2> |
| 290 | <div class="sectionbody"> |
| 291 | <dl> |
| 292 | <dt> |
| 293 | -m |
| 294 | </dt> |
| 295 | <dd> |
| 296 | <p> |
| 297 | Perform a merge, not just a read. The command will |
| 298 | refuse to run if your index file has unmerged entries, |
| 299 | indicating that you have not finished previous merge you |
| 300 | started. |
| 301 | </p> |
| 302 | </dd> |
| 303 | <dt> |
| 304 | --reset |
| 305 | </dt> |
| 306 | <dd> |
| 307 | <p> |
| 308 | Same as -m, except that unmerged entries are discarded |
| 309 | instead of failing. |
| 310 | </p> |
| 311 | </dd> |
| 312 | <dt> |
| 313 | -u |
| 314 | </dt> |
| 315 | <dd> |
| 316 | <p> |
| 317 | After a successful merge, update the files in the work |
| 318 | tree with the result of the merge. |
| 319 | </p> |
| 320 | </dd> |
| 321 | <dt> |
| 322 | -i |
| 323 | </dt> |
| 324 | <dd> |
| 325 | <p> |
| 326 | Usually a merge requires the index file as well as the |
| 327 | files in the working tree are up to date with the |
| 328 | current head commit, in order not to lose local |
| 329 | changes. This flag disables the check with the working |
| 330 | tree and is meant to be used when creating a merge of |
| 331 | trees that are not directly related to the current |
| 332 | working tree status into a temporary index file. |
| 333 | </p> |
| 334 | </dd> |
| 335 | <dt> |
| Junio C Hamano | ee695f2 | 2007-06-21 00:35:36 | [diff] [blame] | 336 | --trivial |
| 337 | </dt> |
| 338 | <dd> |
| 339 | <p> |
| 340 | Restrict three-way merge by <tt>git-read-tree</tt> to happen |
| 341 | only if there is no file-level merging required, instead |
| 342 | of resolving merge for trivial cases and leaving |
| 343 | conflicting files unresolved in the index. |
| 344 | </p> |
| 345 | </dd> |
| 346 | <dt> |
| Junio C Hamano | 5f32776 | 2006-03-02 09:14:51 | [diff] [blame] | 347 | --aggressive |
| 348 | </dt> |
| 349 | <dd> |
| 350 | <p> |
| 351 | Usually a three-way merge by <tt>git-read-tree</tt> resolves |
| 352 | the merge for really trivial cases and leaves other |
| 353 | cases unresolved in the index, so that Porcelains can |
| 354 | implement different merge policies. This flag makes the |
| 355 | command to resolve a few more cases internally: |
| 356 | </p> |
| 357 | <ul> |
| 358 | <li> |
| 359 | <p> |
| 360 | when one side removes a path and the other side leaves the path |
| 361 | unmodified. The resolution is to remove that path. |
| 362 | </p> |
| 363 | </li> |
| 364 | <li> |
| 365 | <p> |
| 366 | when both sides remove a path. The resolution is to remove that path. |
| 367 | </p> |
| 368 | </li> |
| 369 | <li> |
| 370 | <p> |
| 371 | when both sides adds a path identically. The resolution |
| 372 | is to add that path. |
| 373 | </p> |
| 374 | </li> |
| 375 | </ul> |
| 376 | </dd> |
| 377 | <dt> |
| Junio C Hamano | ad8c643 | 2006-06-18 09:26:43 | [diff] [blame] | 378 | --prefix=<prefix>/ |
| 379 | </dt> |
| 380 | <dd> |
| 381 | <p> |
| 382 | Keep the current index contents, and read the contents |
| 383 | of named tree-ish under directory at <tt><prefix></tt>. The |
| 384 | original index file cannot have anything at the path |
| 385 | <tt><prefix></tt> itself, and have nothing in <tt><prefix>/</tt> |
| 386 | directory. Note that the <tt><prefix>/</tt> value must end |
| 387 | with a slash. |
| 388 | </p> |
| 389 | </dd> |
| 390 | <dt> |
| Junio C Hamano | e7935c4 | 2006-12-13 21:32:17 | [diff] [blame] | 391 | --exclude-per-directory=<gitignore> |
| 392 | </dt> |
| 393 | <dd> |
| 394 | <p> |
| 395 | When running the command with <tt>-u</tt> and <tt>-m</tt> options, the |
| 396 | merge result may need to overwrite paths that are not |
| 397 | tracked in the current branch. The command usually |
| 398 | refuses to proceed with the merge to avoid losing such a |
| 399 | path. However this safety valve sometimes gets in the |
| 400 | way. For example, it often happens that the other |
| 401 | branch added a file that used to be a generated file in |
| 402 | your branch, and the safety valve triggers when you try |
| 403 | to switch to that branch after you ran <tt>make</tt> but before |
| 404 | running <tt>make clean</tt> to remove the generated file. This |
| 405 | option tells the command to read per-directory exclude |
| 406 | file (usually <em>.gitignore</em>) and allows such an untracked |
| 407 | but explicitly ignored file to be overwritten. |
| 408 | </p> |
| 409 | </dd> |
| 410 | <dt> |
| Junio C Hamano | 12a3a23 | 2007-04-07 10:18:10 | [diff] [blame] | 411 | --index-output=<file> |
| 412 | </dt> |
| 413 | <dd> |
| 414 | <p> |
| 415 | Instead of writing the results out to <tt>$GIT_INDEX_FILE</tt>, |
| 416 | write the resulting index in the named file. While the |
| 417 | command is operating, the original index file is locked |
| 418 | with the same mechanism as usual. The file must allow |
| 419 | to be rename(2)ed into from a temporary file that is |
| 420 | created next to the usual index file; typically this |
| 421 | means it needs to be on the same filesystem as the index |
| 422 | file itself, and you need write permission to the |
| 423 | directories the index file and index output file are |
| 424 | located in. |
| 425 | </p> |
| 426 | </dd> |
| 427 | <dt> |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 428 | <tree-ish#> |
| 429 | </dt> |
| 430 | <dd> |
| 431 | <p> |
| 432 | The id of the tree object(s) to be read/merged. |
| 433 | </p> |
| 434 | </dd> |
| 435 | </dl> |
| 436 | </div> |
| 437 | <h2>Merging</h2> |
| 438 | <div class="sectionbody"> |
| 439 | <p>If <tt>-m</tt> is specified, <tt>git-read-tree</tt> can perform 3 kinds of |
| 440 | merge, a single tree merge if only 1 tree is given, a |
| 441 | fast-forward merge with 2 trees, or a 3-way merge if 3 trees are |
| 442 | provided.</p> |
| 443 | <h3>Single Tree Merge</h3> |
| 444 | <p>If only 1 tree is specified, git-read-tree operates as if the user did not |
| 445 | specify <tt>-m</tt>, except that if the original index has an entry for a |
| 446 | given pathname, and the contents of the path matches with the tree |
| 447 | being read, the stat info from the index is used. (In other words, the |
| 448 | index's stat()s take precedence over the merged tree's).</p> |
| 449 | <p>That means that if you do a <tt>git-read-tree -m <newtree></tt> followed by a |
| 450 | <tt>git-checkout-index -f -u -a</tt>, the <tt>git-checkout-index</tt> only checks out |
| 451 | the stuff that really changed.</p> |
| 452 | <p>This is used to avoid unnecessary false hits when <tt>git-diff-files</tt> is |
| 453 | run after <tt>git-read-tree</tt>.</p> |
| 454 | <h3>Two Tree Merge</h3> |
| 455 | <p>Typically, this is invoked as <tt>git-read-tree -m $H $M</tt>, where $H |
| 456 | is the head commit of the current repository, and $M is the head |
| 457 | of a foreign tree, which is simply ahead of $H (i.e. we are in a |
| 458 | fast forward situation).</p> |
| 459 | <p>When two trees are specified, the user is telling git-read-tree |
| 460 | the following:</p> |
| 461 | <ol> |
| 462 | <li> |
| 463 | <p> |
| 464 | The current index and work tree is derived from $H, but |
| 465 | the user may have local changes in them since $H; |
| 466 | </p> |
| 467 | </li> |
| 468 | <li> |
| 469 | <p> |
| 470 | The user wants to fast-forward to $M. |
| 471 | </p> |
| 472 | </li> |
| 473 | </ol> |
| 474 | <p>In this case, the <tt>git-read-tree -m $H $M</tt> command makes sure |
| 475 | that no local change is lost as the result of this "merge". |
| 476 | Here are the "carry forward" rules:</p> |
| 477 | <div class="literalblock"> |
| 478 | <div class="content"> |
| 479 | <pre><tt> I (index) H M Result |
| 480 | ------------------------------------------------------- |
| 481 | 0 nothing nothing nothing (does not happen) |
| 482 | 1 nothing nothing exists use M |
| 483 | 2 nothing exists nothing remove path from index |
| 484 | 3 nothing exists exists use M</tt></pre> |
| 485 | </div></div> |
| 486 | <div class="literalblock"> |
| 487 | <div class="content"> |
| 488 | <pre><tt> clean I==H I==M |
| 489 | ------------------ |
| 490 | 4 yes N/A N/A nothing nothing keep index |
| 491 | 5 no N/A N/A nothing nothing keep index</tt></pre> |
| 492 | </div></div> |
| 493 | <div class="literalblock"> |
| 494 | <div class="content"> |
| 495 | <pre><tt>6 yes N/A yes nothing exists keep index |
| 496 | 7 no N/A yes nothing exists keep index |
| 497 | 8 yes N/A no nothing exists fail |
| 498 | 9 no N/A no nothing exists fail</tt></pre> |
| 499 | </div></div> |
| 500 | <div class="literalblock"> |
| 501 | <div class="content"> |
| 502 | <pre><tt>10 yes yes N/A exists nothing remove path from index |
| 503 | 11 no yes N/A exists nothing fail |
| 504 | 12 yes no N/A exists nothing fail |
| 505 | 13 no no N/A exists nothing fail</tt></pre> |
| 506 | </div></div> |
| 507 | <div class="literalblock"> |
| 508 | <div class="content"> |
| 509 | <pre><tt> clean (H=M) |
| 510 | ------ |
| 511 | 14 yes exists exists keep index |
| 512 | 15 no exists exists keep index</tt></pre> |
| 513 | </div></div> |
| 514 | <div class="literalblock"> |
| 515 | <div class="content"> |
| 516 | <pre><tt> clean I==H I==M (H!=M) |
| 517 | ------------------ |
| 518 | 16 yes no no exists exists fail |
| 519 | 17 no no no exists exists fail |
| 520 | 18 yes no yes exists exists keep index |
| 521 | 19 no no yes exists exists keep index |
| 522 | 20 yes yes no exists exists use M |
| 523 | 21 no yes no exists exists fail</tt></pre> |
| 524 | </div></div> |
| 525 | <p>In all "keep index" cases, the index entry stays as in the |
| 526 | original index file. If the entry were not up to date, |
| 527 | git-read-tree keeps the copy in the work tree intact when |
| 528 | operating under the -u flag.</p> |
| 529 | <p>When this form of git-read-tree returns successfully, you can |
| 530 | see what "local changes" you made are carried forward by running |
| 531 | <tt>git-diff-index --cached $M</tt>. Note that this does not |
| 532 | necessarily match <tt>git-diff-index --cached $H</tt> would have |
| 533 | produced before such a two tree merge. This is because of cases |
| 534 | 18 and 19 --- if you already had the changes in $M (e.g. maybe |
| 535 | you picked it up via e-mail in a patch form), <tt>git-diff-index |
| 536 | --cached $H</tt> would have told you about the change before this |
| 537 | merge, but it would not show in <tt>git-diff-index --cached $M</tt> |
| 538 | output after two-tree merge.</p> |
| 539 | <h3>3-Way Merge</h3> |
| 540 | <p>Each "index" entry has two bits worth of "stage" state. stage 0 is the |
| 541 | normal one, and is the only one you'd see in any kind of normal use.</p> |
| 542 | <p>However, when you do <tt>git-read-tree</tt> with three trees, the "stage" |
| 543 | starts out at 1.</p> |
| 544 | <p>This means that you can do</p> |
| 545 | <div class="listingblock"> |
| 546 | <div class="content"> |
| 547 | <pre><tt>$ git-read-tree -m <tree1> <tree2> <tree3></tt></pre> |
| 548 | </div></div> |
| 549 | <p>and you will end up with an index with all of the <tree1> entries in |
| 550 | "stage1", all of the <tree2> entries in "stage2" and all of the |
| 551 | <tree3> entries in "stage3". When performing a merge of another |
| 552 | branch into the current branch, we use the common ancestor tree |
| 553 | as <tree1>, the current branch head as <tree2>, and the other |
| 554 | branch head as <tree3>.</p> |
| 555 | <p>Furthermore, <tt>git-read-tree</tt> has special-case logic that says: if you see |
| 556 | a file that matches in all respects in the following states, it |
| 557 | "collapses" back to "stage0":</p> |
| 558 | <ul> |
| 559 | <li> |
| 560 | <p> |
| 561 | stage 2 and 3 are the same; take one or the other (it makes no |
| 562 | difference - the same work has been done on our branch in |
| 563 | stage 2 and their branch in stage 3) |
| 564 | </p> |
| 565 | </li> |
| 566 | <li> |
| 567 | <p> |
| 568 | stage 1 and stage 2 are the same and stage 3 is different; take |
| 569 | stage 3 (our branch in stage 2 did not do anything since the |
| 570 | ancestor in stage 1 while their branch in stage 3 worked on |
| 571 | it) |
| 572 | </p> |
| 573 | </li> |
| 574 | <li> |
| 575 | <p> |
| 576 | stage 1 and stage 3 are the same and stage 2 is different take |
| 577 | stage 2 (we did something while they did nothing) |
| 578 | </p> |
| 579 | </li> |
| 580 | </ul> |
| 581 | <p>The <tt>git-write-tree</tt> command refuses to write a nonsensical tree, and it |
| 582 | will complain about unmerged entries if it sees a single entry that is not |
| 583 | stage 0.</p> |
| Junio C Hamano | 341071d | 2006-06-04 07:24:48 | [diff] [blame] | 584 | <p>OK, this all sounds like a collection of totally nonsensical rules, |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 585 | but it's actually exactly what you want in order to do a fast |
| 586 | merge. The different stages represent the "result tree" (stage 0, aka |
| 587 | "merged"), the original tree (stage 1, aka "orig"), and the two trees |
| 588 | you are trying to merge (stage 2 and 3 respectively).</p> |
| 589 | <p>The order of stages 1, 2 and 3 (hence the order of three |
| 590 | <tree-ish> command line arguments) are significant when you |
| 591 | start a 3-way merge with an index file that is already |
| 592 | populated. Here is an outline of how the algorithm works:</p> |
| 593 | <ul> |
| 594 | <li> |
| 595 | <p> |
| 596 | if a file exists in identical format in all three trees, it will |
| 597 | automatically collapse to "merged" state by git-read-tree. |
| 598 | </p> |
| 599 | </li> |
| 600 | <li> |
| 601 | <p> |
| 602 | a file that has _any_ difference what-so-ever in the three trees |
| 603 | will stay as separate entries in the index. It's up to "porcelain |
| 604 | policy" to determine how to remove the non-0 stages, and insert a |
| 605 | merged version. |
| 606 | </p> |
| 607 | </li> |
| 608 | <li> |
| 609 | <p> |
| 610 | the index file saves and restores with all this information, so you |
| 611 | can merge things incrementally, but as long as it has entries in |
| Junio C Hamano | 341071d | 2006-06-04 07:24:48 | [diff] [blame] | 612 | stages 1/2/3 (i.e., "unmerged entries") you can't write the result. So |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 613 | now the merge algorithm ends up being really simple: |
| 614 | </p> |
| 615 | <ul> |
| 616 | <li> |
| 617 | <p> |
| 618 | you walk the index in order, and ignore all entries of stage 0, |
| 619 | since they've already been done. |
| 620 | </p> |
| 621 | </li> |
| 622 | <li> |
| 623 | <p> |
| 624 | if you find a "stage1", but no matching "stage2" or "stage3", you |
| 625 | know it's been removed from both trees (it only existed in the |
| 626 | original tree), and you remove that entry. |
| 627 | </p> |
| 628 | </li> |
| 629 | <li> |
| 630 | <p> |
| 631 | if you find a matching "stage2" and "stage3" tree, you remove one |
| 632 | of them, and turn the other into a "stage0" entry. Remove any |
| 633 | matching "stage1" entry if it exists too. .. all the normal |
| 634 | trivial rules .. |
| 635 | </p> |
| 636 | </li> |
| 637 | </ul> |
| 638 | </li> |
| 639 | </ul> |
| 640 | <p>You would normally use <tt>git-merge-index</tt> with supplied |
| 641 | <tt>git-merge-one-file</tt> to do this last step. The script updates |
| 642 | the files in the working tree as it merges each path and at the |
| 643 | end of a successful merge.</p> |
| 644 | <p>When you start a 3-way merge with an index file that is already |
| 645 | populated, it is assumed that it represents the state of the |
| 646 | files in your work tree, and you can even have files with |
| 647 | changes unrecorded in the index file. It is further assumed |
| 648 | that this state is "derived" from the stage 2 tree. The 3-way |
| 649 | merge refuses to run if it finds an entry in the original index |
| 650 | file that does not match stage 2.</p> |
| 651 | <p>This is done to prevent you from losing your work-in-progress |
| 652 | changes, and mixing your random changes in an unrelated merge |
| 653 | commit. To illustrate, suppose you start from what has been |
| Junio C Hamano | 33db437 | 2006-06-07 19:51:45 | [diff] [blame] | 654 | committed last to your repository:</p> |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 655 | <div class="listingblock"> |
| 656 | <div class="content"> |
| 657 | <pre><tt>$ JC=`git-rev-parse --verify "HEAD^0"` |
| 658 | $ git-checkout-index -f -u -a $JC</tt></pre> |
| 659 | </div></div> |
| 660 | <p>You do random edits, without running git-update-index. And then |
| 661 | you notice that the tip of your "upstream" tree has advanced |
| 662 | since you pulled from him:</p> |
| 663 | <div class="listingblock"> |
| 664 | <div class="content"> |
| 665 | <pre><tt>$ git-fetch git://.... linus |
| 666 | $ LT=`cat .git/FETCH_HEAD`</tt></pre> |
| 667 | </div></div> |
| 668 | <p>Your work tree is still based on your HEAD ($JC), but you have |
| 669 | some edits since. Three-way merge makes sure that you have not |
| 670 | added or modified index entries since $JC, and if you haven't, |
| 671 | then does the right thing. So with the following sequence:</p> |
| 672 | <div class="listingblock"> |
| 673 | <div class="content"> |
| 674 | <pre><tt>$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT |
| 675 | $ git-merge-index git-merge-one-file -a |
| 676 | $ echo "Merge with Linus" | \ |
| 677 | git-commit-tree `git-write-tree` -p $JC -p $LT</tt></pre> |
| 678 | </div></div> |
| 679 | <p>what you would commit is a pure merge between $JC and $LT without |
| 680 | your work-in-progress changes, and your work tree would be |
| 681 | updated to the result of the merge.</p> |
| 682 | <p>However, if you have local changes in the working tree that |
| 683 | would be overwritten by this merge,<tt>git-read-tree</tt> will refuse |
| 684 | to run to prevent your changes from being lost.</p> |
| 685 | <p>In other words, there is no need to worry about what exists only |
| 686 | in the working tree. When you have local changes in a part of |
| 687 | the project that is not involved in the merge, your changes do |
| 688 | not interfere with the merge, and are kept intact. When they |
| 689 | <strong>do</strong> interfere, the merge does not even start (<tt>git-read-tree</tt> |
| 690 | complains loudly and fails without modifying anything). In such |
| 691 | a case, you can simply continue doing what you were in the |
| 692 | middle of doing, and when your working tree is ready (i.e. you |
| 693 | have finished your work-in-progress), attempt the merge again.</p> |
| 694 | </div> |
| 695 | <h2>See Also</h2> |
| 696 | <div class="sectionbody"> |
| Junio C Hamano | 679d22d | 2007-06-02 21:13:44 | [diff] [blame] | 697 | <p><a href="git-write-tree.html">git-write-tree(1)</a>; <a href="git-ls-files.html">git-ls-files(1)</a>; |
| 698 | <a href="gitignore.html">gitignore(5)</a></p> |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 699 | </div> |
| 700 | <h2>Author</h2> |
| 701 | <div class="sectionbody"> |
| 702 | <p>Written by Linus Torvalds <torvalds@osdl.org></p> |
| 703 | </div> |
| 704 | <h2>Documentation</h2> |
| 705 | <div class="sectionbody"> |
| 706 | <p>Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.</p> |
| 707 | </div> |
| 708 | <h2>GIT</h2> |
| 709 | <div class="sectionbody"> |
| 710 | <p>Part of the <a href="git.html">git(7)</a> suite</p> |
| 711 | </div> |
| 712 | <div id="footer"> |
| 713 | <div id="footer-text"> |
| Junio C Hamano | bb6e078 | 2007-07-19 02:14:50 | [diff] [blame] | 714 | Last updated 19-Jul-2007 02:09:50 UTC |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 715 | </div> |
| 716 | </div> |
| 717 | </body> |
| 718 | </html> |
