git-merge.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
   6 <meta name="generator" content="AsciiDoc 7.0.1" />\r
   7 <style type="text/css">\r
   8 /* Debug borders */\r
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
  10 /*\r
  11   border: 1px solid red;\r
  12 */\r
  13 }\r
  14 \r
  15 body {\r
  16   margin: 1em 5% 1em 5%;\r
  17 }\r
  18 \r
  19 a { color: blue; }\r
  20 a:visited { color: fuchsia; }\r
  21 \r
  22 em {\r
  23   font-style: italic;\r
  24 }\r
  25 \r
  26 strong {\r
  27   font-weight: bold;\r
  28 }\r
  29 \r
  30 tt {\r
  31   color: navy;\r
  32 }\r
  33 \r
  34 h1, h2, h3, h4, h5, h6 {\r
  35   color: #527bbd;\r
  36   font-family: sans-serif;\r
  37   margin-top: 1.2em;\r
  38   margin-bottom: 0.5em;\r
  39   line-height: 1.3;\r
  40 }\r
  41 \r
  42 h1 {\r
  43   border-bottom: 2px solid silver;\r
  44 }\r
  45 h2 {\r
  46   border-bottom: 2px solid silver;\r
  47   padding-top: 0.5em;\r
  48 }\r
  49 \r
  50 div.sectionbody {\r
  51   font-family: serif;\r
  52   margin-left: 0;\r
  53 }\r
  54 \r
  55 hr {\r
  56   border: 1px solid silver;\r
  57 }\r
  58 \r
  59 p {\r
  60   margin-top: 0.5em;\r
  61   margin-bottom: 0.5em;\r
  62 }\r
  63 \r
  64 pre {\r
  65   padding: 0;\r
  66   margin: 0;\r
  67 }\r
  68 \r
  69 span#author {\r
  70   color: #527bbd;\r
  71   font-family: sans-serif;\r
  72   font-weight: bold;\r
  73   font-size: 1.2em;\r
  74 }\r
  75 span#email {\r
  76 }\r
  77 span#revision {\r
  78   font-family: sans-serif;\r
  79 }\r
  80 \r
  81 div#footer {\r
  82   font-family: sans-serif;\r
  83   font-size: small;\r
  84   border-top: 2px solid silver;\r
  85   padding-top: 0.5em;\r
  86   margin-top: 4.0em;\r
  87 }\r
  88 div#footer-text {\r
  89   float: left;\r
  90   padding-bottom: 0.5em;\r
  91 }\r
  92 div#footer-badges {\r
  93   float: right;\r
  94   padding-bottom: 0.5em;\r
  95 }\r
  96 \r
  97 div#preamble,\r
  98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
  99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
 100 div.admonitionblock {\r
 101   margin-right: 10%;\r
 102   margin-top: 1.5em;\r
 103   margin-bottom: 1.5em;\r
 104 }\r
 105 div.admonitionblock {\r
 106   margin-top: 2.5em;\r
 107   margin-bottom: 2.5em;\r
 108 }\r
 109 \r
 110 div.content { /* Block element content. */\r
 111   padding: 0;\r
 112 }\r
 113 \r
 114 /* Block element titles. */\r
 115 div.title, caption.title {\r
 116   font-family: sans-serif;\r
 117   font-weight: bold;\r
 118   text-align: left;\r
 119   margin-top: 1.0em;\r
 120   margin-bottom: 0.5em;\r
 121 }\r
 122 div.title + * {\r
 123   margin-top: 0;\r
 124 }\r
 125 \r
 126 td div.title:first-child {\r
 127   margin-top: 0.0em;\r
 128 }\r
 129 div.content div.title:first-child {\r
 130   margin-top: 0.0em;\r
 131 }\r
 132 div.content + div.title {\r
 133   margin-top: 0.0em;\r
 134 }\r
 135 \r
 136 div.sidebarblock > div.content {\r
 137   background: #ffffee;\r
 138   border: 1px solid silver;\r
 139   padding: 0.5em;\r
 140 }\r
 141 \r
 142 div.listingblock > div.content {\r
 143   border: 1px solid silver;\r
 144   background: #f4f4f4;\r
 145   padding: 0.5em;\r
 146 }\r
 147 \r
 148 div.quoteblock > div.content {\r
 149   padding-left: 2.0em;\r
 150 }\r
 151 div.quoteblock .attribution {\r
 152   text-align: right;\r
 153 }\r
 154 \r
 155 div.admonitionblock .icon {\r
 156   vertical-align: top;\r
 157   font-size: 1.1em;\r
 158   font-weight: bold;\r
 159   text-decoration: underline;\r
 160   color: #527bbd;\r
 161   padding-right: 0.5em;\r
 162 }\r
 163 div.admonitionblock td.content {\r
 164   padding-left: 0.5em;\r
 165   border-left: 2px solid silver;\r
 166 }\r
 167 \r
 168 div.exampleblock > div.content {\r
 169   border-left: 2px solid silver;\r
 170   padding: 0.5em;\r
 171 }\r
 172 \r
 173 div.verseblock div.content {\r
 174   white-space: pre;\r
 175 }\r
 176 \r
 177 div.imageblock div.content { padding-left: 0; }\r
 178 div.imageblock img { border: 1px solid silver; }\r
 179 span.image img { border-style: none; }\r
 180 \r
 181 dl {\r
 182   margin-top: 0.8em;\r
 183   margin-bottom: 0.8em;\r
 184 }\r
 185 dt {\r
 186   margin-top: 0.5em;\r
 187   margin-bottom: 0;\r
 188   font-style: italic;\r
 189 }\r
 190 dd > *:first-child {\r
 191   margin-top: 0;\r
 192 }\r
 193 \r
 194 ul, ol {\r
 195     list-style-position: outside;\r
 196 }\r
 197 ol.olist2 {\r
 198   list-style-type: lower-alpha;\r
 199 }\r
 200 \r
 201 div.tableblock > table {\r
 202   border-color: #527bbd;\r
 203   border-width: 3px;\r
 204 }\r
 205 thead {\r
 206   font-family: sans-serif;\r
 207   font-weight: bold;\r
 208 }\r
 209 tfoot {\r
 210   font-weight: bold;\r
 211 }\r
 212 \r
 213 div.hlist {\r
 214   margin-top: 0.8em;\r
 215   margin-bottom: 0.8em;\r
 216 }\r
 217 td.hlist1 {\r
 218   vertical-align: top;\r
 219   font-style: italic;\r
 220   padding-right: 0.8em;\r
 221 }\r
 222 td.hlist2 {\r
 223   vertical-align: top;\r
 224 }\r
 225 \r
 226 @media print {\r
 227   div#footer-badges { display: none; }\r
 228 }\r
 229 include::./stylesheets/xhtml11-manpage.css[]\r
 230 /* Workarounds for IE6's broken and incomplete CSS2. */\r
 231 \r
 232 div.sidebar-content {\r
 233   background: #ffffee;\r
 234   border: 1px solid silver;\r
 235   padding: 0.5em;\r
 236 }\r
 237 div.sidebar-title, div.image-title {\r
 238   font-family: sans-serif;\r
 239   font-weight: bold;\r
 240   margin-top: 0.0em;\r
 241   margin-bottom: 0.5em;\r
 242 }\r
 243 \r
 244 div.listingblock div.content {\r
 245   border: 1px solid silver;\r
 246   background: #f4f4f4;\r
 247   padding: 0.5em;\r
 248 }\r
 249 \r
 250 div.quoteblock-content {\r
 251   padding-left: 2.0em;\r
 252 }\r
 253 \r
 254 div.exampleblock-content {\r
 255   border-left: 2px solid silver;\r
 256   padding-left: 0.5em;\r
 257 }\r
 258 </style>\r
 259 <title>git-merge(1)</title>\r
 260 </head>\r
 261 <body>\r
 262 <div id="header">\r
 263 <h1>\r
 264 git-merge(1) Manual Page\r
 265 </h1>\r
 266 <h2>NAME</h2>\r
 267 <div class="sectionbody">\r
 268 <p>git-merge -\r
 269    Grand Unified Merge Driver\r
 270 </p>\r
 271 </div>\r
 272 </div>\r
 273 <h2>SYNOPSIS</h2>\r
 274 <div class="sectionbody">\r
 275 <p><em>git-merge</em> [-n] [--no-commit] [-s &lt;strategy&gt;]&#8230; &lt;msg&gt; &lt;head&gt; &lt;remote&gt; &lt;remote&gt;&#8230;</p>\r
 276 </div>\r
 277 <h2>DESCRIPTION</h2>\r
 278 <div class="sectionbody">\r
 279 <p>This is the top-level user interface to the merge machinery\r
 280 which drives multiple merge strategy scripts.</p>\r
 281 </div>\r
 282 <h2>OPTIONS</h2>\r
 283 <div class="sectionbody">\r
 284 <dl>\r
 285 <dt>\r
 286 -n, --no-summary\r
 287 </dt>\r
 288 <dd>\r
 289 <p>\r
 290         Do not show diffstat at the end of the merge.\r
 291 </p>\r
 292 </dd>\r
 293 <dt>\r
 294 --no-commit\r
 295 </dt>\r
 296 <dd>\r
 297 <p>\r
 298         Perform the merge but pretend the merge failed and do\r
 299         not autocommit, to give the user a chance to inspect and\r
 300         further tweak the merge result before committing.\r
 301 </p>\r
 302 </dd>\r
 303 <dt>\r
 304 -s &lt;strategy&gt;, --strategy=&lt;strategy&gt;\r
 305 </dt>\r
 306 <dd>\r
 307 <p>\r
 308         Use the given merge strategy; can be supplied more than\r
 309         once to specify them in the order they should be tried.\r
 310         If there is no <tt>-s</tt> option, a built-in list of strategies\r
 311         is used instead (<tt>git-merge-recursive</tt> when merging a single\r
 312         head, <tt>git-merge-octopus</tt> otherwise).\r
 313 </p>\r
 314 </dd>\r
 315 <dt>\r
 316 &lt;msg&gt;\r
 317 </dt>\r
 318 <dd>\r
 319 <p>\r
 320         The commit message to be used for the merge commit (in case\r
 321         it is created). The <tt>git-fmt-merge-msg</tt> script can be used\r
 322         to give a good default for automated <tt>git-merge</tt> invocations.\r
 323 </p>\r
 324 </dd>\r
 325 <dt>\r
 326 &lt;head&gt;\r
 327 </dt>\r
 328 <dd>\r
 329 <p>\r
 330         our branch head commit.\r
 331 </p>\r
 332 </dd>\r
 333 <dt>\r
 334 &lt;remote&gt;\r
 335 </dt>\r
 336 <dd>\r
 337 <p>\r
 338         other branch head merged into our branch.  You need at\r
 339         least one &lt;remote&gt;.  Specifying more than one &lt;remote&gt;\r
 340         obviously means you are trying an Octopus.\r
 341 </p>\r
 342 </dd>\r
 343 </dl>\r
 344 </div>\r
 345 <h2>MERGE STRATEGIES</h2>\r
 346 <div class="sectionbody">\r
 347 <dl>\r
 348 <dt>\r
 349 resolve\r
 350 </dt>\r
 351 <dd>\r
 352 <p>\r
 353         This can only resolve two heads (i.e. the current branch\r
 354         and another branch you pulled from) using 3-way merge\r
 355         algorithm.  It tries to carefully detect criss-cross\r
 356         merge ambiguities and is considered generally safe and\r
 357         fast.\r
 358 </p>\r
 359 </dd>\r
 360 <dt>\r
 361 recursive\r
 362 </dt>\r
 363 <dd>\r
 364 <p>\r
 365         This can only resolve two heads using 3-way merge\r
 366         algorithm.  When there are more than one common\r
 367         ancestors that can be used for 3-way merge, it creates a\r
 368         merged tree of the common ancestors and uses that as\r
 369         the reference tree for the 3-way merge.  This has been\r
 370         reported to result in fewer merge conflicts without\r
 371         causing mis-merges by tests done on actual merge commits\r
 372         taken from Linux 2.6 kernel development history.\r
 373         Additionally this can detect and handle merges involving\r
 374         renames.  This is the default merge strategy when\r
 375         pulling or merging one branch.\r
 376 </p>\r
 377 </dd>\r
 378 <dt>\r
 379 octopus\r
 380 </dt>\r
 381 <dd>\r
 382 <p>\r
 383         This resolves more than two-head case, but refuses to do\r
 384         complex merge that needs manual resolution.  It is\r
 385         primarily meant to be used for bundling topic branch\r
 386         heads together.  This is the default merge strategy when\r
 387         pulling or merging more than one branches.\r
 388 </p>\r
 389 </dd>\r
 390 <dt>\r
 391 ours\r
 392 </dt>\r
 393 <dd>\r
 394 <p>\r
 395         This resolves any number of heads, but the result of the\r
 396         merge is always the current branch head.  It is meant to\r
 397         be used to supersede old development history of side\r
 398         branches.\r
 399 </p>\r
 400 </dd>\r
 401 </dl>\r
 402 <p>If you tried a merge which resulted in a complex conflicts and\r
 403 would want to start over, you can recover with\r
 404 <a href="git-reset.html">git-reset(1)</a>.</p>\r
 405 </div>\r
 406 <h2>HOW MERGE WORKS</h2>\r
 407 <div class="sectionbody">\r
 408 <p>A merge is always between the current <tt>HEAD</tt> and one or more\r
 409 remote branch heads, and the index file must exactly match the\r
 410 tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) when\r
 411 it happens.  In other words, <tt>git-diff --cached HEAD</tt> must\r
 412 report no changes.</p>\r
 413 <div class="admonitionblock">\r
 414 <table><tr>\r
 415 <td class="icon">\r
 416 <div class="title">Note</div>\r
 417 </td>\r
 418 <td class="content">This is a bit of lie.  In certain special cases, your index are\r
 419 allowed to be different from the tree of <tt>HEAD</tt> commit.  The most\r
 420 notable case is when your <tt>HEAD</tt> commit is already ahead of what\r
 421 is being merged, in which case your index can have arbitrary\r
 422 difference from your <tt>HEAD</tt> commit.  Otherwise, your index entries\r
 423 are allowed have differences from your <tt>HEAD</tt> commit that match\r
 424 the result of trivial merge (e.g. you received the same patch\r
 425 from external source to produce the same result as what you are\r
 426 merging).  For example, if a path did not exist in the common\r
 427 ancestor and your head commit but exists in the tree you are\r
 428 merging into your repository, and if you already happen to have\r
 429 that path exactly in your index, the merge does not have to\r
 430 fail.</td>\r
 431 </tr></table>\r
 432 </div>\r
 433 <p>Otherwise, merge will refuse to do any harm to your repository\r
 434 (that is, it may fetch the objects from remote, and it may even\r
 435 update the local branch used to keep track of the remote branch\r
 436 with <tt>git pull remote rbranch:lbranch</tt>, but your working tree,\r
 437 <tt>.git/HEAD</tt> pointer and index file are left intact).</p>\r
 438 <p>You may have local modifications in the working tree files.  In\r
 439 other words, <tt>git-diff</tt> is allowed to report changes.\r
 440 However, the merge uses your working tree as the working area,\r
 441 and in order to prevent the merge operation from losing such\r
 442 changes, it makes sure that they do not interfere with the\r
 443 merge. Those complex tables in read-tree documentation define\r
 444 what it means for a path to "interfere with the merge".  And if\r
 445 your local modifications interfere with the merge, again, it\r
 446 stops before touching anything.</p>\r
 447 <p>So in the above two "failed merge" case, you do not have to\r
 448 worry about lossage of data --- you simply were not ready to do\r
 449 a merge, so no merge happened at all.  You may want to finish\r
 450 whatever you were in the middle of doing, and retry the same\r
 451 pull after you are done and ready.</p>\r
 452 <p>When things cleanly merge, these things happen:</p>\r
 453 <ol>\r
 454 <li>\r
 455 <p>\r
 456 the results are updated both in the index file and in your\r
 457    working tree,\r
 458 </p>\r
 459 </li>\r
 460 <li>\r
 461 <p>\r
 462 index file is written out as a tree,\r
 463 </p>\r
 464 </li>\r
 465 <li>\r
 466 <p>\r
 467 the tree gets committed, and\r
 468 </p>\r
 469 </li>\r
 470 <li>\r
 471 <p>\r
 472 the <tt>HEAD</tt> pointer gets advanced.\r
 473 </p>\r
 474 </li>\r
 475 </ol>\r
 476 <p>Because of 2., we require that the original state of the index\r
 477 file to match exactly the current <tt>HEAD</tt> commit; otherwise we\r
 478 will write out your local changes already registered in your\r
 479 index file along with the merge result, which is not good.\r
 480 Because 1. involves only the paths different between your\r
 481 branch and the remote branch you are pulling from during the\r
 482 merge (which is typically a fraction of the whole tree), you can\r
 483 have local modifications in your working tree as long as they do\r
 484 not overlap with what the merge updates.</p>\r
 485 <p>When there are conflicts, these things happen:</p>\r
 486 <ol>\r
 487 <li>\r
 488 <p>\r
 489 <tt>HEAD</tt> stays the same.\r
 490 </p>\r
 491 </li>\r
 492 <li>\r
 493 <p>\r
 494 Cleanly merged paths are updated both in the index file and\r
 495    in your working tree.\r
 496 </p>\r
 497 </li>\r
 498 <li>\r
 499 <p>\r
 500 For conflicting paths, the index file records up to three\r
 501    versions; stage1 stores the version from the common ancestor,\r
 502    stage2 from <tt>HEAD</tt>, and stage3 from the remote branch (you\r
 503    can inspect the stages with <tt>git-ls-files -u</tt>).  The working\r
 504    tree files have the result of "merge" program; i.e. 3-way\r
 505    merge result with familiar conflict markers <tt>&lt;&lt;&lt; === &gt;&gt;&gt;</tt>.\r
 506 </p>\r
 507 </li>\r
 508 <li>\r
 509 <p>\r
 510 No other changes are done.  In particular, the local\r
 511    modifications you had before you started merge will stay the\r
 512    same and the index entries for them stay as they were,\r
 513    i.e. matching <tt>HEAD</tt>.\r
 514 </p>\r
 515 </li>\r
 516 </ol>\r
 517 <p>After seeing a conflict, you can do two things:</p>\r
 518 <ul>\r
 519 <li>\r
 520 <p>\r
 521 Decide not to merge.  The only clean-up you need are to reset\r
 522    the index file to the <tt>HEAD</tt> commit to reverse 2. and to clean\r
 523    up working tree changes made by 2. and 3.; <tt>git-reset</tt> can\r
 524    be used for this.\r
 525 </p>\r
 526 </li>\r
 527 <li>\r
 528 <p>\r
 529 Resolve the conflicts.  <tt>git-diff</tt> would report only the\r
 530    conflicting paths because of the above 2. and 3..  Edit the\r
 531    working tree files into a desirable shape, <tt>git-update-index</tt>\r
 532    them, to make the index file contain what the merge result\r
 533    should be, and run <tt>git-commit</tt> to commit the result.\r
 534 </p>\r
 535 </li>\r
 536 </ul>\r
 537 </div>\r
 538 <h2>SEE ALSO</h2>\r
 539 <div class="sectionbody">\r
 540 <p><a href="git-fmt-merge-msg.html">git-fmt-merge-msg(1)</a>, <a href="git-pull.html">git-pull(1)</a></p>\r
 541 </div>\r
 542 <h2>Author</h2>\r
 543 <div class="sectionbody">\r
 544 <p>Written by Junio C Hamano &lt;junkio@cox.net&gt;</p>\r
 545 </div>\r
 546 <h2>Documentation</h2>\r
 547 <div class="sectionbody">\r
 548 <p>Documentation by Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p>\r
 549 </div>\r
 550 <h2>GIT</h2>\r
 551 <div class="sectionbody">\r
 552 <p>Part of the <a href="git.html">git(7)</a> suite</p>\r
 553 </div>\r
 554 <div id="footer">\r
 555 <div id="footer-text">\r
 556 Last updated 27-Dec-2005 00:16:22 PDT\r
 557 </div>\r
 558 </div>\r
 559 </body>\r
 560 </html>\r