doc/source/en/TortoiseGit/git_doc/git-merge.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-merge(1)">\r
   5 <articleinfo>\r
   6     <title>git-merge(1)</title>\r
   7 <indexterm>\r
   8 <primary>git-merge(1)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-merge - Join two or more development histories together</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git merge</emphasis> [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\r
  19         [-s &lt;strategy&gt;] [-X &lt;strategy-option&gt;]\r
  20         [--[no-]rerere-autoupdate] [-m &lt;msg&gt;] [&lt;commit&gt;&#8230;]\r
  21 <emphasis>git merge</emphasis> &lt;msg&gt; HEAD &lt;commit&gt;&#8230;\r
  22 <emphasis>git merge</emphasis> --abort</literallayout>\r
  23 </blockquote>\r
  24 </simplesect>\r
  25 <simplesect id="_description">\r
  26 <title>DESCRIPTION</title>\r
  27 <simpara>Incorporates changes from the named commits (since the time their\r
  28 histories diverged from the current branch) into the current\r
  29 branch.  This command is used by <emphasis>git pull</emphasis> to incorporate changes\r
  30 from another repository and can be used by hand to merge changes\r
  31 from one branch into another.</simpara>\r
  32 <simpara>Assume the following history exists and the current branch is\r
  33 "<emphasis>master</emphasis>":</simpara>\r
  34 <screen>          A---B---C topic\r
  35          /\r
  36     D---E---F---G master</screen>\r
  37 <simpara>Then "<emphasis>git merge topic</emphasis>" will replay the changes made on the\r
  38 <emphasis>topic</emphasis> branch since it diverged from <emphasis>master</emphasis> (i.e., <emphasis>E</emphasis>) until\r
  39 its current commit (<emphasis>C</emphasis>) on top of <emphasis>master</emphasis>, and record the result\r
  40 in a new commit along with the names of the two parent commits and\r
  41 a log message from the user describing the changes.</simpara>\r
  42 <screen>          A---B---C topic\r
  43          /         \\r
  44     D---E---F---G---H master</screen>\r
  45 <simpara>The second syntax (&lt;msg&gt; <emphasis>HEAD</emphasis> &lt;commit&gt;&#8230;) is supported for\r
  46 historical reasons.  Do not use it from the command line or in\r
  47 new scripts.  It is the same as <emphasis>git merge -m &lt;msg&gt; &lt;commit&gt;...</emphasis>.</simpara>\r
  48 <simpara>The third syntax ("<emphasis>git merge --abort</emphasis>") can only be run after the\r
  49 merge has resulted in conflicts. <emphasis>git merge --abort</emphasis> will abort the\r
  50 merge process and try to reconstruct the pre-merge state. However,\r
  51 if there were uncommitted changes when the merge started (and\r
  52 especially if those changes were further modified after the merge\r
  53 was started), <emphasis>git merge --abort</emphasis> will in some cases be unable to\r
  54 reconstruct the original (pre-merge) changes. Therefore:</simpara>\r
  55 <simpara><emphasis role="strong">Warning</emphasis>: Running <emphasis>git merge</emphasis> with uncommitted changes is\r
  56 discouraged: while possible, it leaves you in a state that is hard to\r
  57 back out of in the case of a conflict.</simpara>\r
  58 </simplesect>\r
  59 <simplesect id="_options">\r
  60 <title>OPTIONS</title>\r
  61 <variablelist>\r
  62 <varlistentry>\r
  63 <term>\r
  64 --commit\r
  65 </term>\r
  66 <term>\r
  67 --no-commit\r
  68 </term>\r
  69 <listitem>\r
  70 <simpara>\r
  71         Perform the merge and commit the result. This option can\r
  72         be used to override --no-commit.\r
  73 </simpara>\r
  74 <simpara>With --no-commit perform the merge but pretend the merge\r
  75 failed and do not autocommit, to give the user a chance to\r
  76 inspect and further tweak the merge result before committing.</simpara>\r
  77 </listitem>\r
  78 </varlistentry>\r
  79 <varlistentry>\r
  80 <term>\r
  81 --edit\r
  82 </term>\r
  83 <term>\r
  84 --no-edit\r
  85 </term>\r
  86 <listitem>\r
  87 <simpara>\r
  88         Invoke an editor before committing successful mechanical merge to\r
  89         further edit the auto-generated merge message, so that the user\r
  90         can explain and justify the merge. The <emphasis>--no-edit</emphasis> option can be\r
  91         used to accept the auto-generated message (this is generally\r
  92         discouraged). The <emphasis>--edit</emphasis> option is still useful if you are\r
  93         giving a draft message with the <emphasis>-m</emphasis> option from the command line\r
  94         and want to edit it in the editor.\r
  95 </simpara>\r
  96 <simpara>Older scripts may depend on the historical behaviour of not allowing the\r
  97 user to edit the merge log message. They will see an editor opened when\r
  98 they run <emphasis>git merge</emphasis>. To make it easier to adjust such scripts to the\r
  99 updated behaviour, the environment variable <emphasis>GIT_MERGE_AUTOEDIT</emphasis> can be\r
 100 set to <emphasis>no</emphasis> at the beginning of them.</simpara>\r
 101 </listitem>\r
 102 </varlistentry>\r
 103 <varlistentry>\r
 104 <term>\r
 105 --ff\r
 106 </term>\r
 107 <listitem>\r
 108 <simpara>\r
 109         When the merge resolves as a fast-forward, only update the branch\r
 110         pointer, without creating a merge commit.  This is the default\r
 111         behavior.\r
 112 </simpara>\r
 113 </listitem>\r
 114 </varlistentry>\r
 115 <varlistentry>\r
 116 <term>\r
 117 --no-ff\r
 118 </term>\r
 119 <listitem>\r
 120 <simpara>\r
 121         Create a merge commit even when the merge resolves as a\r
 122         fast-forward.\r
 123 </simpara>\r
 124 </listitem>\r
 125 </varlistentry>\r
 126 <varlistentry>\r
 127 <term>\r
 128 --ff-only\r
 129 </term>\r
 130 <listitem>\r
 131 <simpara>\r
 132         Refuse to merge and exit with a non-zero status unless the\r
 133         current <emphasis>HEAD</emphasis> is already up-to-date or the merge can be\r
 134         resolved as a fast-forward.\r
 135 </simpara>\r
 136 </listitem>\r
 137 </varlistentry>\r
 138 <varlistentry>\r
 139 <term>\r
 140 --log[=&lt;n&gt;]\r
 141 </term>\r
 142 <term>\r
 143 --no-log\r
 144 </term>\r
 145 <listitem>\r
 146 <simpara>\r
 147         In addition to branch names, populate the log message with\r
 148         one-line descriptions from at most &lt;n&gt; actual commits that are being\r
 149         merged. See also <xref linkend="git-fmt-merge-msg(1)" />.\r
 150 </simpara>\r
 151 <simpara>With --no-log do not list one-line descriptions from the\r
 152 actual commits being merged.</simpara>\r
 153 </listitem>\r
 154 </varlistentry>\r
 155 <varlistentry>\r
 156 <term>\r
 157 --stat\r
 158 </term>\r
 159 <term>\r
 160 -n\r
 161 </term>\r
 162 <term>\r
 163 --no-stat\r
 164 </term>\r
 165 <listitem>\r
 166 <simpara>\r
 167         Show a diffstat at the end of the merge. The diffstat is also\r
 168         controlled by the configuration option merge.stat.\r
 169 </simpara>\r
 170 <simpara>With -n or --no-stat do not show a diffstat at the end of the\r
 171 merge.</simpara>\r
 172 </listitem>\r
 173 </varlistentry>\r
 174 <varlistentry>\r
 175 <term>\r
 176 --squash\r
 177 </term>\r
 178 <term>\r
 179 --no-squash\r
 180 </term>\r
 181 <listitem>\r
 182 <simpara>\r
 183         Produce the working tree and index state as if a real\r
 184         merge happened (except for the merge information),\r
 185         but do not actually make a commit or\r
 186         move the <emphasis>HEAD</emphasis>, nor record <emphasis>$GIT_DIR/MERGE_HEAD</emphasis> to\r
 187         cause the next <emphasis>git commit</emphasis> command to create a merge\r
 188         commit.  This allows you to create a single commit on\r
 189         top of the current branch whose effect is the same as\r
 190         merging another branch (or more in case of an octopus).\r
 191 </simpara>\r
 192 <simpara>With --no-squash perform the merge and commit the result. This\r
 193 option can be used to override --squash.</simpara>\r
 194 </listitem>\r
 195 </varlistentry>\r
 196 <varlistentry>\r
 197 <term>\r
 198 -s &lt;strategy&gt;\r
 199 </term>\r
 200 <term>\r
 201 --strategy=&lt;strategy&gt;\r
 202 </term>\r
 203 <listitem>\r
 204 <simpara>\r
 205         Use the given merge strategy; can be supplied more than\r
 206         once to specify them in the order they should be tried.\r
 207         If there is no <emphasis>-s</emphasis> option, a built-in list of strategies\r
 208         is used instead (<emphasis>git merge-recursive</emphasis> when merging a single\r
 209         head, <emphasis>git merge-octopus</emphasis> otherwise).\r
 210 </simpara>\r
 211 </listitem>\r
 212 </varlistentry>\r
 213 <varlistentry>\r
 214 <term>\r
 215 -X &lt;option&gt;\r
 216 </term>\r
 217 <term>\r
 218 --strategy-option=&lt;option&gt;\r
 219 </term>\r
 220 <listitem>\r
 221 <simpara>\r
 222         Pass merge strategy specific option through to the merge\r
 223         strategy.\r
 224 </simpara>\r
 225 </listitem>\r
 226 </varlistentry>\r
 227 <varlistentry>\r
 228 <term>\r
 229 --summary\r
 230 </term>\r
 231 <term>\r
 232 --no-summary\r
 233 </term>\r
 234 <listitem>\r
 235 <simpara>\r
 236         Synonyms to --stat and --no-stat; these are deprecated and will be\r
 237         removed in the future.\r
 238 </simpara>\r
 239 </listitem>\r
 240 </varlistentry>\r
 241 <varlistentry>\r
 242 <term>\r
 243 -q\r
 244 </term>\r
 245 <term>\r
 246 --quiet\r
 247 </term>\r
 248 <listitem>\r
 249 <simpara>\r
 250         Operate quietly. Implies --no-progress.\r
 251 </simpara>\r
 252 </listitem>\r
 253 </varlistentry>\r
 254 <varlistentry>\r
 255 <term>\r
 256 -v\r
 257 </term>\r
 258 <term>\r
 259 --verbose\r
 260 </term>\r
 261 <listitem>\r
 262 <simpara>\r
 263         Be verbose.\r
 264 </simpara>\r
 265 </listitem>\r
 266 </varlistentry>\r
 267 <varlistentry>\r
 268 <term>\r
 269 --progress\r
 270 </term>\r
 271 <term>\r
 272 --no-progress\r
 273 </term>\r
 274 <listitem>\r
 275 <simpara>\r
 276         Turn progress on/off explicitly. If neither is specified,\r
 277         progress is shown if standard error is connected to a terminal.\r
 278         Note that not all merge strategies may support progress\r
 279         reporting.\r
 280 </simpara>\r
 281 </listitem>\r
 282 </varlistentry>\r
 283 <varlistentry>\r
 284 <term>\r
 285 -m &lt;msg&gt;\r
 286 </term>\r
 287 <listitem>\r
 288 <simpara>\r
 289         Set the commit message to be used for the merge commit (in\r
 290         case one is created).\r
 291 </simpara>\r
 292 <simpara>If <emphasis>--log</emphasis> is specified, a shortlog of the commits being merged\r
 293 will be appended to the specified message.</simpara>\r
 294 <simpara>The <emphasis>git fmt-merge-msg</emphasis> command can be\r
 295 used to give a good default for automated <emphasis>git merge</emphasis>\r
 296 invocations.</simpara>\r
 297 </listitem>\r
 298 </varlistentry>\r
 299 <varlistentry>\r
 300 <term>\r
 301 --rerere-autoupdate\r
 302 </term>\r
 303 <term>\r
 304 --no-rerere-autoupdate\r
 305 </term>\r
 306 <listitem>\r
 307 <simpara>\r
 308         Allow the rerere mechanism to update the index with the\r
 309         result of auto-conflict resolution if possible.\r
 310 </simpara>\r
 311 </listitem>\r
 312 </varlistentry>\r
 313 <varlistentry>\r
 314 <term>\r
 315 --abort\r
 316 </term>\r
 317 <listitem>\r
 318 <simpara>\r
 319         Abort the current conflict resolution process, and\r
 320         try to reconstruct the pre-merge state.\r
 321 </simpara>\r
 322 <simpara>If there were uncommitted worktree changes present when the merge\r
 323 started, <emphasis>git merge --abort</emphasis> will in some cases be unable to\r
 324 reconstruct these changes. It is therefore recommended to always\r
 325 commit or stash your changes before running <emphasis>git merge</emphasis>.</simpara>\r
 326 <simpara><emphasis>git merge --abort</emphasis> is equivalent to <emphasis>git reset --merge</emphasis> when\r
 327 <emphasis>MERGE_HEAD</emphasis> is present.</simpara>\r
 328 </listitem>\r
 329 </varlistentry>\r
 330 <varlistentry>\r
 331 <term>\r
 332 &lt;commit&gt;&#8230;\r
 333 </term>\r
 334 <listitem>\r
 335 <simpara>\r
 336         Commits, usually other branch heads, to merge into our branch.\r
 337         Specifying more than one commit will create a merge with\r
 338         more than two parents (affectionately called an Octopus merge).\r
 339 </simpara>\r
 340 <simpara>If no commit is given from the command line, and if <emphasis>merge.defaultToUpstream</emphasis>\r
 341 configuration variable is set, merge the remote tracking branches\r
 342 that the current branch is configured to use as its upstream.\r
 343 See also the configuration section of this manual page.</simpara>\r
 344 </listitem>\r
 345 </varlistentry>\r
 346 </variablelist>\r
 347 </simplesect>\r
 348 <simplesect id="_pre_merge_checks">\r
 349 <title>PRE-MERGE CHECKS</title>\r
 350 <simpara>Before applying outside changes, you should get your own work in\r
 351 good shape and committed locally, so it will not be clobbered if\r
 352 there are conflicts.  See also <xref linkend="git-stash(1)" />.\r
 353 <emphasis>git pull</emphasis> and <emphasis>git merge</emphasis> will stop without doing anything when\r
 354 local uncommitted changes overlap with files that <emphasis>git pull</emphasis>/<emphasis>git\r
 355 merge</emphasis> may need to update.</simpara>\r
 356 <simpara>To avoid recording unrelated changes in the merge commit,\r
 357 <emphasis>git pull</emphasis> and <emphasis>git merge</emphasis> will also abort if there are any changes\r
 358 registered in the index relative to the <emphasis>HEAD</emphasis> commit.  (One\r
 359 exception is when the changed index entries are in the state that\r
 360 would result from the merge already.)</simpara>\r
 361 <simpara>If all named commits are already ancestors of <emphasis>HEAD</emphasis>, <emphasis>git merge</emphasis>\r
 362 will exit early with the message "Already up-to-date."</simpara>\r
 363 </simplesect>\r
 364 <simplesect id="_fast_forward_merge">\r
 365 <title>FAST-FORWARD MERGE</title>\r
 366 <simpara>Often the current branch head is an ancestor of the named commit.\r
 367 This is the most common case especially when invoked from <emphasis>git\r
 368 pull</emphasis>: you are tracking an upstream repository, you have committed\r
 369 no local changes, and now you want to update to a newer upstream\r
 370 revision.  In this case, a new commit is not needed to store the\r
 371 combined history; instead, the <emphasis>HEAD</emphasis> (along with the index) is\r
 372 updated to point at the named commit, without creating an extra\r
 373 merge commit.</simpara>\r
 374 <simpara>This behavior can be suppressed with the <emphasis>--no-ff</emphasis> option.</simpara>\r
 375 </simplesect>\r
 376 <simplesect id="_true_merge">\r
 377 <title>TRUE MERGE</title>\r
 378 <simpara>Except in a fast-forward merge (see above), the branches to be\r
 379 merged must be tied together by a merge commit that has both of them\r
 380 as its parents.</simpara>\r
 381 <simpara>A merged version reconciling the changes from all branches to be\r
 382 merged is committed, and your <emphasis>HEAD</emphasis>, index, and working tree are\r
 383 updated to it.  It is possible to have modifications in the working\r
 384 tree as long as they do not overlap; the update will preserve them.</simpara>\r
 385 <simpara>When it is not obvious how to reconcile the changes, the following\r
 386 happens:</simpara>\r
 387 <orderedlist numeration="arabic">\r
 388 <listitem>\r
 389 <simpara>\r
 390 The <emphasis>HEAD</emphasis> pointer stays the same.\r
 391 </simpara>\r
 392 </listitem>\r
 393 <listitem>\r
 394 <simpara>\r
 395 The <emphasis>MERGE_HEAD</emphasis> ref is set to point to the other branch head.\r
 396 </simpara>\r
 397 </listitem>\r
 398 <listitem>\r
 399 <simpara>\r
 400 Paths that merged cleanly are updated both in the index file and\r
 401    in your working tree.\r
 402 </simpara>\r
 403 </listitem>\r
 404 <listitem>\r
 405 <simpara>\r
 406 For conflicting paths, the index file records up to three\r
 407    versions: stage 1 stores the version from the common ancestor,\r
 408    stage 2 from <emphasis>HEAD</emphasis>, and stage 3 from <emphasis>MERGE_HEAD</emphasis> (you\r
 409    can inspect the stages with <emphasis>git ls-files -u</emphasis>).  The working\r
 410    tree files contain the result of the "merge" program; i.e. 3-way\r
 411    merge results with familiar conflict markers <emphasis>&lt;&lt;&lt;</emphasis> <emphasis>===</emphasis> <emphasis>&gt;&gt;&gt;</emphasis>.\r
 412 </simpara>\r
 413 </listitem>\r
 414 <listitem>\r
 415 <simpara>\r
 416 No other changes are made.  In particular, the local\r
 417    modifications you had before you started merge will stay the\r
 418    same and the index entries for them stay as they were,\r
 419    i.e. matching <emphasis>HEAD</emphasis>.\r
 420 </simpara>\r
 421 </listitem>\r
 422 </orderedlist>\r
 423 <simpara>If you tried a merge which resulted in complex conflicts and\r
 424 want to start over, you can recover with <emphasis>git merge --abort</emphasis>.</simpara>\r
 425 </simplesect>\r
 426 <simplesect id="_how_conflicts_are_presented">\r
 427 <title>HOW CONFLICTS ARE PRESENTED</title>\r
 428 <simpara>During a merge, the working tree files are updated to reflect the result\r
 429 of the merge.  Among the changes made to the common ancestor's version,\r
 430 non-overlapping ones (that is, you changed an area of the file while the\r
 431 other side left that area intact, or vice versa) are incorporated in the\r
 432 final result verbatim.  When both sides made changes to the same area,\r
 433 however, git cannot randomly pick one side over the other, and asks you to\r
 434 resolve it by leaving what both sides did to that area.</simpara>\r
 435 <simpara>By default, git uses the same style as that is used by "merge" program\r
 436 from the RCS suite to present such a conflicted hunk, like this:</simpara>\r
 437 <screen>Here are lines that are either unchanged from the common\r
 438 ancestor, or cleanly resolved because only one side changed.\r
 439 &lt;&lt;&lt;&lt;&lt;&lt;&lt; yours:sample.txt\r
 440 Conflict resolution is hard;\r
 441 let's go shopping.\r
 442 =======\r
 443 Git makes conflict resolution easy.\r
 444 &gt;&gt;&gt;&gt;&gt;&gt;&gt; theirs:sample.txt\r
 445 And here is another line that is cleanly resolved or unmodified.</screen>\r
 446 <simpara>The area where a pair of conflicting changes happened is marked with markers\r
 447 <emphasis>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</emphasis>, <emphasis>=======</emphasis>, and <emphasis>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</emphasis>.  The part before the <emphasis>=======</emphasis>\r
 448 is typically your side, and the part afterwards is typically their side.</simpara>\r
 449 <simpara>The default format does not show what the original said in the conflicting\r
 450 area.  You cannot tell how many lines are deleted and replaced with\r
 451 Barbie's remark on your side.  The only thing you can tell is that your\r
 452 side wants to say it is hard and you'd prefer to go shopping, while the\r
 453 other side wants to claim it is easy.</simpara>\r
 454 <simpara>An alternative style can be used by setting the "merge.conflictstyle"\r
 455 configuration variable to "diff3".  In "diff3" style, the above conflict\r
 456 may look like this:</simpara>\r
 457 <screen>Here are lines that are either unchanged from the common\r
 458 ancestor, or cleanly resolved because only one side changed.\r
 459 &lt;&lt;&lt;&lt;&lt;&lt;&lt; yours:sample.txt\r
 460 Conflict resolution is hard;\r
 461 let's go shopping.\r
 462 |||||||\r
 463 Conflict resolution is hard.\r
 464 =======\r
 465 Git makes conflict resolution easy.\r
 466 &gt;&gt;&gt;&gt;&gt;&gt;&gt; theirs:sample.txt\r
 467 And here is another line that is cleanly resolved or unmodified.</screen>\r
 468 <simpara>In addition to the <emphasis>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</emphasis>, <emphasis>=======</emphasis>, and <emphasis>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</emphasis> markers, it uses\r
 469 another <emphasis>|||||||</emphasis> marker that is followed by the original text.  You can\r
 470 tell that the original just stated a fact, and your side simply gave in to\r
 471 that statement and gave up, while the other side tried to have a more\r
 472 positive attitude.  You can sometimes come up with a better resolution by\r
 473 viewing the original.</simpara>\r
 474 </simplesect>\r
 475 <simplesect id="_how_to_resolve_conflicts">\r
 476 <title>HOW TO RESOLVE CONFLICTS</title>\r
 477 <simpara>After seeing a conflict, you can do two things:</simpara>\r
 478 <itemizedlist>\r
 479 <listitem>\r
 480 <simpara>\r
 481 Decide not to merge.  The only clean-ups you need are to reset\r
 482    the index file to the <emphasis>HEAD</emphasis> commit to reverse 2. and to clean\r
 483    up working tree changes made by 2. and 3.; <emphasis>git merge --abort</emphasis>\r
 484    can be used for this.\r
 485 </simpara>\r
 486 </listitem>\r
 487 <listitem>\r
 488 <simpara>\r
 489 Resolve the conflicts.  Git will mark the conflicts in\r
 490    the working tree.  Edit the files into shape and\r
 491    <emphasis>git add</emphasis> them to the index.  Use <emphasis>git commit</emphasis> to seal the deal.\r
 492 </simpara>\r
 493 </listitem>\r
 494 </itemizedlist>\r
 495 <simpara>You can work through the conflict with a number of tools:</simpara>\r
 496 <itemizedlist>\r
 497 <listitem>\r
 498 <simpara>\r
 499 Use a mergetool.  <emphasis>git mergetool</emphasis> to launch a graphical\r
 500    mergetool which will work you through the merge.\r
 501 </simpara>\r
 502 </listitem>\r
 503 <listitem>\r
 504 <simpara>\r
 505 Look at the diffs.  <emphasis>git diff</emphasis> will show a three-way diff,\r
 506    highlighting changes from both the <emphasis>HEAD</emphasis> and <emphasis>MERGE_HEAD</emphasis>\r
 507    versions.\r
 508 </simpara>\r
 509 </listitem>\r
 510 <listitem>\r
 511 <simpara>\r
 512 Look at the diffs from each branch. <emphasis>git log --merge -p &lt;path&gt;</emphasis>\r
 513    will show diffs first for the <emphasis>HEAD</emphasis> version and then the\r
 514    <emphasis>MERGE_HEAD</emphasis> version.\r
 515 </simpara>\r
 516 </listitem>\r
 517 <listitem>\r
 518 <simpara>\r
 519 Look at the originals.  <emphasis>git show :1:filename</emphasis> shows the\r
 520    common ancestor, <emphasis>git show :2:filename</emphasis> shows the <emphasis>HEAD</emphasis>\r
 521    version, and <emphasis>git show :3:filename</emphasis> shows the <emphasis>MERGE_HEAD</emphasis>\r
 522    version.\r
 523 </simpara>\r
 524 </listitem>\r
 525 </itemizedlist>\r
 526 </simplesect>\r
 527 <simplesect id="_examples">\r
 528 <title>EXAMPLES</title>\r
 529 <itemizedlist>\r
 530 <listitem>\r
 531 <simpara>\r
 532 Merge branches <emphasis>fixes</emphasis> and <emphasis>enhancements</emphasis> on top of\r
 533   the current branch, making an octopus merge:\r
 534 </simpara>\r
 535 <screen>$ git merge fixes enhancements</screen>\r
 536 </listitem>\r
 537 <listitem>\r
 538 <simpara>\r
 539 Merge branch <emphasis>obsolete</emphasis> into the current branch, using <emphasis>ours</emphasis>\r
 540   merge strategy:\r
 541 </simpara>\r
 542 <screen>$ git merge -s ours obsolete</screen>\r
 543 </listitem>\r
 544 <listitem>\r
 545 <simpara>\r
 546 Merge branch <emphasis>maint</emphasis> into the current branch, but do not make\r
 547   a new commit automatically:\r
 548 </simpara>\r
 549 <screen>$ git merge --no-commit maint</screen>\r
 550 <simpara>This can be used when you want to include further changes to the\r
 551 merge, or want to write your own merge commit message.</simpara>\r
 552 <simpara>You should refrain from abusing this option to sneak substantial\r
 553 changes into a merge commit.  Small fixups like bumping\r
 554 release/version name would be acceptable.</simpara>\r
 555 </listitem>\r
 556 </itemizedlist>\r
 557 </simplesect>\r
 558 <simplesect id="_merge_strategies">\r
 559 <title>MERGE STRATEGIES</title>\r
 560 <simpara>The merge mechanism (<emphasis>git-merge</emphasis> and <emphasis>git-pull</emphasis> commands) allows the\r
 561 backend <emphasis>merge strategies</emphasis> to be chosen with <emphasis>-s</emphasis> option.  Some strategies\r
 562 can also take their own options, which can be passed by giving <emphasis>-X&lt;option&gt;</emphasis>\r
 563 arguments to <emphasis>git-merge</emphasis> and/or <emphasis>git-pull</emphasis>.</simpara>\r
 564 <variablelist>\r
 565 <varlistentry>\r
 566 <term>\r
 567 resolve\r
 568 </term>\r
 569 <listitem>\r
 570 <simpara>\r
 571         This can only resolve two heads (i.e. the current branch\r
 572         and another branch you pulled from) using a 3-way merge\r
 573         algorithm.  It tries to carefully detect criss-cross\r
 574         merge ambiguities and is considered generally safe and\r
 575         fast.\r
 576 </simpara>\r
 577 </listitem>\r
 578 </varlistentry>\r
 579 <varlistentry>\r
 580 <term>\r
 581 recursive\r
 582 </term>\r
 583 <listitem>\r
 584 <simpara>\r
 585         This can only resolve two heads using a 3-way merge\r
 586         algorithm.  When there is more than one common\r
 587         ancestor that can be used for 3-way merge, it creates a\r
 588         merged tree of the common ancestors and uses that as\r
 589         the reference tree for the 3-way merge.  This has been\r
 590         reported to result in fewer merge conflicts without\r
 591         causing mis-merges by tests done on actual merge commits\r
 592         taken from Linux 2.6 kernel development history.\r
 593         Additionally this can detect and handle merges involving\r
 594         renames.  This is the default merge strategy when\r
 595         pulling or merging one branch.\r
 596 </simpara>\r
 597 <simpara>The <emphasis>recursive</emphasis> strategy can take the following options:</simpara>\r
 598 <variablelist>\r
 599 <varlistentry>\r
 600 <term>\r
 601 ours\r
 602 </term>\r
 603 <listitem>\r
 604 <simpara>\r
 605         This option forces conflicting hunks to be auto-resolved cleanly by\r
 606         favoring <emphasis>our</emphasis> version.  Changes from the other tree that do not\r
 607         conflict with our side are reflected to the merge result.\r
 608 </simpara>\r
 609 <simpara>This should not be confused with the <emphasis>ours</emphasis> merge strategy, which does not\r
 610 even look at what the other tree contains at all.  It discards everything\r
 611 the other tree did, declaring <emphasis>our</emphasis> history contains all that happened in it.</simpara>\r
 612 </listitem>\r
 613 </varlistentry>\r
 614 <varlistentry>\r
 615 <term>\r
 616 theirs\r
 617 </term>\r
 618 <listitem>\r
 619 <simpara>\r
 620         This is opposite of <emphasis>ours</emphasis>.\r
 621 </simpara>\r
 622 </listitem>\r
 623 </varlistentry>\r
 624 <varlistentry>\r
 625 <term>\r
 626 patience\r
 627 </term>\r
 628 <listitem>\r
 629 <simpara>\r
 630         With this option, <emphasis>merge-recursive</emphasis> spends a little extra time\r
 631         to avoid mismerges that sometimes occur due to unimportant\r
 632         matching lines (e.g., braces from distinct functions).  Use\r
 633         this when the branches to be merged have diverged wildly.\r
 634         See also <xref linkend="git-diff(1)" /> <emphasis>--patience</emphasis>.\r
 635 </simpara>\r
 636 </listitem>\r
 637 </varlistentry>\r
 638 <varlistentry>\r
 639 <term>\r
 640 ignore-space-change\r
 641 </term>\r
 642 <term>\r
 643 ignore-all-space\r
 644 </term>\r
 645 <term>\r
 646 ignore-space-at-eol\r
 647 </term>\r
 648 <listitem>\r
 649 <simpara>\r
 650         Treats lines with the indicated type of whitespace change as\r
 651         unchanged for the sake of a three-way merge.  Whitespace\r
 652         changes mixed with other changes to a line are not ignored.\r
 653         See also <xref linkend="git-diff(1)" /> <emphasis>-b</emphasis>, <emphasis>-w</emphasis>, and\r
 654         <emphasis>--ignore-space-at-eol</emphasis>.\r
 655 </simpara>\r
 656 <itemizedlist>\r
 657 <listitem>\r
 658 <simpara>\r
 659 If <emphasis>their</emphasis> version only introduces whitespace changes to a line,\r
 660   <emphasis>our</emphasis> version is used;\r
 661 </simpara>\r
 662 </listitem>\r
 663 <listitem>\r
 664 <simpara>\r
 665 If <emphasis>our</emphasis> version introduces whitespace changes but <emphasis>their</emphasis>\r
 666   version includes a substantial change, <emphasis>their</emphasis> version is used;\r
 667 </simpara>\r
 668 </listitem>\r
 669 <listitem>\r
 670 <simpara>\r
 671 Otherwise, the merge proceeds in the usual way.\r
 672 </simpara>\r
 673 </listitem>\r
 674 </itemizedlist>\r
 675 </listitem>\r
 676 </varlistentry>\r
 677 <varlistentry>\r
 678 <term>\r
 679 renormalize\r
 680 </term>\r
 681 <listitem>\r
 682 <simpara>\r
 683         This runs a virtual check-out and check-in of all three stages\r
 684         of a file when resolving a three-way merge.  This option is\r
 685         meant to be used when merging branches with different clean\r
 686         filters or end-of-line normalization rules.  See "Merging\r
 687         branches with differing checkin/checkout attributes" in\r
 688         <xref linkend="gitattributes(5)" /> for details.\r
 689 </simpara>\r
 690 </listitem>\r
 691 </varlistentry>\r
 692 <varlistentry>\r
 693 <term>\r
 694 no-renormalize\r
 695 </term>\r
 696 <listitem>\r
 697 <simpara>\r
 698         Disables the <emphasis>renormalize</emphasis> option.  This overrides the\r
 699         <emphasis>merge.renormalize</emphasis> configuration variable.\r
 700 </simpara>\r
 701 </listitem>\r
 702 </varlistentry>\r
 703 <varlistentry>\r
 704 <term>\r
 705 rename-threshold=&lt;n&gt;\r
 706 </term>\r
 707 <listitem>\r
 708 <simpara>\r
 709         Controls the similarity threshold used for rename detection.\r
 710         See also <xref linkend="git-diff(1)" /> <emphasis>-M</emphasis>.\r
 711 </simpara>\r
 712 </listitem>\r
 713 </varlistentry>\r
 714 <varlistentry>\r
 715 <term>\r
 716 subtree[=&lt;path&gt;]\r
 717 </term>\r
 718 <listitem>\r
 719 <simpara>\r
 720         This option is a more advanced form of <emphasis>subtree</emphasis> strategy, where\r
 721         the strategy makes a guess on how two trees must be shifted to\r
 722         match with each other when merging.  Instead, the specified path\r
 723         is prefixed (or stripped from the beginning) to make the shape of\r
 724         two trees to match.\r
 725 </simpara>\r
 726 </listitem>\r
 727 </varlistentry>\r
 728 </variablelist>\r
 729 </listitem>\r
 730 </varlistentry>\r
 731 <varlistentry>\r
 732 <term>\r
 733 octopus\r
 734 </term>\r
 735 <listitem>\r
 736 <simpara>\r
 737         This resolves cases with more than two heads, but refuses to do\r
 738         a complex merge that needs manual resolution.  It is\r
 739         primarily meant to be used for bundling topic branch\r
 740         heads together.  This is the default merge strategy when\r
 741         pulling or merging more than one branch.\r
 742 </simpara>\r
 743 </listitem>\r
 744 </varlistentry>\r
 745 <varlistentry>\r
 746 <term>\r
 747 ours\r
 748 </term>\r
 749 <listitem>\r
 750 <simpara>\r
 751         This resolves any number of heads, but the resulting tree of the\r
 752         merge is always that of the current branch head, effectively\r
 753         ignoring all changes from all other branches.  It is meant to\r
 754         be used to supersede old development history of side\r
 755         branches.  Note that this is different from the -Xours option to\r
 756         the <emphasis>recursive</emphasis> merge strategy.\r
 757 </simpara>\r
 758 </listitem>\r
 759 </varlistentry>\r
 760 <varlistentry>\r
 761 <term>\r
 762 subtree\r
 763 </term>\r
 764 <listitem>\r
 765 <simpara>\r
 766         This is a modified recursive strategy. When merging trees A and\r
 767         B, if B corresponds to a subtree of A, B is first adjusted to\r
 768         match the tree structure of A, instead of reading the trees at\r
 769         the same level. This adjustment is also done to the common\r
 770         ancestor tree.\r
 771 </simpara>\r
 772 </listitem>\r
 773 </varlistentry>\r
 774 </variablelist>\r
 775 </simplesect>\r
 776 <simplesect id="_configuration">\r
 777 <title>CONFIGURATION</title>\r
 778 <variablelist>\r
 779 <varlistentry>\r
 780 <term>\r
 781 merge.conflictstyle\r
 782 </term>\r
 783 <listitem>\r
 784 <simpara>\r
 785         Specify the style in which conflicted hunks are written out to\r
 786         working tree files upon merge.  The default is "merge", which\r
 787         shows a <emphasis>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</emphasis> conflict marker, changes made by one side,\r
 788         a <emphasis>=======</emphasis> marker, changes made by the other side, and then\r
 789         a <emphasis>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</emphasis> marker.  An alternate style, "diff3", adds a <emphasis>|||||||</emphasis>\r
 790         marker and the original text before the <emphasis>=======</emphasis> marker.\r
 791 </simpara>\r
 792 </listitem>\r
 793 </varlistentry>\r
 794 <varlistentry>\r
 795 <term>\r
 796 merge.defaultToUpstream\r
 797 </term>\r
 798 <listitem>\r
 799 <simpara>\r
 800         If merge is called without any commit argument, merge the upstream\r
 801         branches configured for the current branch by using their last\r
 802         observed values stored in their remote tracking branches.\r
 803         The values of the <emphasis>branch.&lt;current branch&gt;.merge</emphasis> that name the\r
 804         branches at the remote named by <emphasis>branch.&lt;current branch&gt;.remote</emphasis>\r
 805         are consulted, and then they are mapped via <emphasis>remote.&lt;remote&gt;.fetch</emphasis>\r
 806         to their corresponding remote tracking branches, and the tips of\r
 807         these tracking branches are merged.\r
 808 </simpara>\r
 809 </listitem>\r
 810 </varlistentry>\r
 811 <varlistentry>\r
 812 <term>\r
 813 merge.ff\r
 814 </term>\r
 815 <listitem>\r
 816 <simpara>\r
 817         By default, git does not create an extra merge commit when merging\r
 818         a commit that is a descendant of the current commit. Instead, the\r
 819         tip of the current branch is fast-forwarded. When set to <emphasis>false</emphasis>,\r
 820         this variable tells git to create an extra merge commit in such\r
 821         a case (equivalent to giving the <emphasis>--no-ff</emphasis> option from the command\r
 822         line). When set to <emphasis>only</emphasis>, only such fast-forward merges are\r
 823         allowed (equivalent to giving the <emphasis>--ff-only</emphasis> option from the\r
 824         command line).\r
 825 </simpara>\r
 826 </listitem>\r
 827 </varlistentry>\r
 828 <varlistentry>\r
 829 <term>\r
 830 merge.log\r
 831 </term>\r
 832 <listitem>\r
 833 <simpara>\r
 834         In addition to branch names, populate the log message with at\r
 835         most the specified number of one-line descriptions from the\r
 836         actual commits that are being merged.  Defaults to false, and\r
 837         true is a synonym for 20.\r
 838 </simpara>\r
 839 </listitem>\r
 840 </varlistentry>\r
 841 <varlistentry>\r
 842 <term>\r
 843 merge.renameLimit\r
 844 </term>\r
 845 <listitem>\r
 846 <simpara>\r
 847         The number of files to consider when performing rename detection\r
 848         during a merge; if not specified, defaults to the value of\r
 849         diff.renameLimit.\r
 850 </simpara>\r
 851 </listitem>\r
 852 </varlistentry>\r
 853 <varlistentry>\r
 854 <term>\r
 855 merge.renormalize\r
 856 </term>\r
 857 <listitem>\r
 858 <simpara>\r
 859         Tell git that canonical representation of files in the\r
 860         repository has changed over time (e.g. earlier commits record\r
 861         text files with CRLF line endings, but recent ones use LF line\r
 862         endings).  In such a repository, git can convert the data\r
 863         recorded in commits to a canonical form before performing a\r
 864         merge to reduce unnecessary conflicts.  For more information,\r
 865         see section "Merging branches with differing checkin/checkout\r
 866         attributes" in <xref linkend="gitattributes(5)" />.\r
 867 </simpara>\r
 868 </listitem>\r
 869 </varlistentry>\r
 870 <varlistentry>\r
 871 <term>\r
 872 merge.stat\r
 873 </term>\r
 874 <listitem>\r
 875 <simpara>\r
 876         Whether to print the diffstat between ORIG_HEAD and the merge result\r
 877         at the end of the merge.  True by default.\r
 878 </simpara>\r
 879 </listitem>\r
 880 </varlistentry>\r
 881 <varlistentry>\r
 882 <term>\r
 883 merge.tool\r
 884 </term>\r
 885 <listitem>\r
 886 <simpara>\r
 887         Controls which merge resolution program is used by\r
 888         <xref linkend="git-mergetool(1)" />.  Valid built-in values are: "araxis",\r
 889         "bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld",\r
 890         "opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff"\r
 891         and "xxdiff".  Any other value is treated is custom merge tool\r
 892         and there must be a corresponding mergetool.&lt;tool&gt;.cmd option.\r
 893 </simpara>\r
 894 </listitem>\r
 895 </varlistentry>\r
 896 <varlistentry>\r
 897 <term>\r
 898 merge.verbosity\r
 899 </term>\r
 900 <listitem>\r
 901 <simpara>\r
 902         Controls the amount of output shown by the recursive merge\r
 903         strategy.  Level 0 outputs nothing except a final error\r
 904         message if conflicts were detected. Level 1 outputs only\r
 905         conflicts, 2 outputs conflicts and file changes.  Level 5 and\r
 906         above outputs debugging information.  The default is level 2.\r
 907         Can be overridden by the <emphasis>GIT_MERGE_VERBOSITY</emphasis> environment variable.\r
 908 </simpara>\r
 909 </listitem>\r
 910 </varlistentry>\r
 911 <varlistentry>\r
 912 <term>\r
 913 merge.&lt;driver&gt;.name\r
 914 </term>\r
 915 <listitem>\r
 916 <simpara>\r
 917         Defines a human-readable name for a custom low-level\r
 918         merge driver.  See <xref linkend="gitattributes(5)" /> for details.\r
 919 </simpara>\r
 920 </listitem>\r
 921 </varlistentry>\r
 922 <varlistentry>\r
 923 <term>\r
 924 merge.&lt;driver&gt;.driver\r
 925 </term>\r
 926 <listitem>\r
 927 <simpara>\r
 928         Defines the command that implements a custom low-level\r
 929         merge driver.  See <xref linkend="gitattributes(5)" /> for details.\r
 930 </simpara>\r
 931 </listitem>\r
 932 </varlistentry>\r
 933 <varlistentry>\r
 934 <term>\r
 935 merge.&lt;driver&gt;.recursive\r
 936 </term>\r
 937 <listitem>\r
 938 <simpara>\r
 939         Names a low-level merge driver to be used when\r
 940         performing an internal merge between common ancestors.\r
 941         See <xref linkend="gitattributes(5)" /> for details.\r
 942 </simpara>\r
 943 </listitem>\r
 944 </varlistentry>\r
 945 <varlistentry>\r
 946 <term>\r
 947 branch.&lt;name&gt;.mergeoptions\r
 948 </term>\r
 949 <listitem>\r
 950 <simpara>\r
 951         Sets default options for merging into branch &lt;name&gt;. The syntax and\r
 952         supported options are the same as those of <emphasis>git merge</emphasis>, but option\r
 953         values containing whitespace characters are currently not supported.\r
 954 </simpara>\r
 955 </listitem>\r
 956 </varlistentry>\r
 957 </variablelist>\r
 958 </simplesect>\r
 959 <simplesect id="_see_also">\r
 960 <title>SEE ALSO</title>\r
 961 <simpara><xref linkend="git-fmt-merge-msg(1)" />, <xref linkend="git-pull(1)" />,\r
 962 <xref linkend="gitattributes(5)" />,\r
 963 <xref linkend="git-reset(1)" />,\r
 964 <xref linkend="git-diff(1)" />, <xref linkend="git-ls-files(1)" />,\r
 965 <xref linkend="git-add(1)" />, <xref linkend="git-rm(1)" />,\r
 966 <xref linkend="git-mergetool(1)" /></simpara>\r
 967 </simplesect>\r
 968 <simplesect id="_git">\r
 969 <title>GIT</title>\r
 970 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 971 </simplesect>\r
 972 </article>\r