git-merge.html - external/gitster/git-htmldocs - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <meta name="generator" content="AsciiDoc 7.0.1" />
 <style type="text/css">
 /* Debug borders */
 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
 /*
  border: 1px solid red;
 */
 }

 body {
  margin: 1em 5% 1em 5%;
 }

 a { color: blue; }
 a:visited { color: fuchsia; }

 em {
  font-style: italic;
 }

 strong {
  font-weight: bold;
 }

 tt {
  color: navy;
 }

 h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
 }

 h1 {
  border-bottom: 2px solid silver;
 }
 h2 {
  border-bottom: 2px solid silver;
  padding-top: 0.5em;
 }

 div.sectionbody {
  font-family: serif;
  margin-left: 0;
 }

 hr {
  border: 1px solid silver;
 }

 p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
 }

 pre {
  padding: 0;
  margin: 0;
 }

 span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.2em;
 }
 span#email {
 }
 span#revision {
  font-family: sans-serif;
 }

 div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
 }
 div#footer-text {
  float: left;
  padding-bottom: 0.5em;
 }
 div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
 }

 div#preamble,
 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
 }
 div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
 }

 div.content { /* Block element content. */
  padding: 0;
 }

 /* Block element titles. */
 div.title, caption.title {
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
 }
 div.title + * {
  margin-top: 0;
 }

 td div.title:first-child {
  margin-top: 0.0em;
 }
 div.content div.title:first-child {
  margin-top: 0.0em;
 }
 div.content + div.title {
  margin-top: 0.0em;
 }

 div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }

 div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock > div.content {
  padding-left: 2.0em;
 }
 div.quoteblock .attribution {
  text-align: right;
 }

 div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
 }
 div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
 }

 div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
 }

 div.verseblock div.content {
  white-space: pre;
 }

 div.imageblock div.content { padding-left: 0; }
 div.imageblock img { border: 1px solid silver; }
 span.image img { border-style: none; }

 dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: italic;
 }
 dd > *:first-child {
  margin-top: 0;
 }

 ul, ol {
  list-style-position: outside;
 }
 ol.olist2 {
  list-style-type: lower-alpha;
 }

 div.tableblock > table {
  border-color: #527bbd;
  border-width: 3px;
 }
 thead {
  font-family: sans-serif;
  font-weight: bold;
 }
 tfoot {
  font-weight: bold;
 }

 div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 td.hlist1 {
  vertical-align: top;
  font-style: italic;
  padding-right: 0.8em;
 }
 td.hlist2 {
  vertical-align: top;
 }

 @media print {
  div#footer-badges { display: none; }
 }
 include::./stylesheets/xhtml11-manpage.css[]
 /* Workarounds for IE6's broken and incomplete CSS2. */

 div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }
 div.sidebar-title, div.image-title {
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
 }

 div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock-content {
  padding-left: 2.0em;
 }

 div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
 }
 </style>
 <title>git-merge(1)</title>
 </head>
 <body>
 <div id="header">
 <h1>
 git-merge(1) Manual Page
 </h1>
 <h2>NAME</h2>
 <div class="sectionbody">
 <p>git-merge -
  Grand Unified Merge Driver
 </p>
 </div>
 </div>
 <h2>SYNOPSIS</h2>
 <div class="sectionbody">
 <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>
 </div>
 <h2>DESCRIPTION</h2>
 <div class="sectionbody">
 <p>This is the top-level user interface to the merge machinery
 which drives multiple merge strategy scripts.</p>
 </div>
 <h2>OPTIONS</h2>
 <div class="sectionbody">
 <dl>
 <dt>
 -n, --no-summary
 </dt>
 <dd>
 <p>
  Do not show diffstat at the end of the merge.
 </p>
 </dd>
 <dt>
 --no-commit
 </dt>
 <dd>
 <p>
  Perform the merge but pretend the merge failed and do
  not autocommit, to give the user a chance to inspect and
  further tweak the merge result before committing.
 </p>
 </dd>
 <dt>
 -s &lt;strategy&gt;, --strategy=&lt;strategy&gt;
 </dt>
 <dd>
 <p>
  Use the given merge strategy; can be supplied more than
  once to specify them in the order they should be tried.
  If there is no <tt>-s</tt> option, a built-in list of strategies
  is used instead (<tt>git-merge-recursive</tt> when merging a single
  head, <tt>git-merge-octopus</tt> otherwise).
 </p>
 </dd>
 <dt>
 &lt;msg&gt;
 </dt>
 <dd>
 <p>
  The commit message to be used for the merge commit (in case
  it is created). The <tt>git-fmt-merge-msg</tt> script can be used
  to give a good default for automated <tt>git-merge</tt> invocations.
 </p>
 </dd>
 <dt>
 &lt;head&gt;
 </dt>
 <dd>
 <p>
  our branch head commit.
 </p>
 </dd>
 <dt>
 &lt;remote&gt;
 </dt>
 <dd>
 <p>
  other branch head merged into our branch. You need at
  least one &lt;remote&gt;. Specifying more than one &lt;remote&gt;
  obviously means you are trying an Octopus.
 </p>
 </dd>
 </dl>
 </div>
 <h2>MERGE STRATEGIES</h2>
 <div class="sectionbody">
 <dl>
 <dt>
 resolve
 </dt>
 <dd>
 <p>
  This can only resolve two heads (i.e. the current branch
  and another branch you pulled from) using 3-way merge
  algorithm. It tries to carefully detect criss-cross
  merge ambiguities and is considered generally safe and
  fast.
 </p>
 </dd>
 <dt>
 recursive
 </dt>
 <dd>
 <p>
  This can only resolve two heads using 3-way merge
  algorithm. When there are more than one common
  ancestors that can be used for 3-way merge, it creates a
  merged tree of the common ancestors and uses that as
  the reference tree for the 3-way merge. This has been
  reported to result in fewer merge conflicts without
  causing mis-merges by tests done on actual merge commits
  taken from Linux 2.6 kernel development history.
  Additionally this can detect and handle merges involving
  renames. This is the default merge strategy when
  pulling or merging one branch.
 </p>
 </dd>
 <dt>
 octopus
 </dt>
 <dd>
 <p>
  This resolves more than two-head case, but refuses to do
  complex merge that needs manual resolution. It is
  primarily meant to be used for bundling topic branch
  heads together. This is the default merge strategy when
  pulling or merging more than one branches.
 </p>
 </dd>
 <dt>
 ours
 </dt>
 <dd>
 <p>
  This resolves any number of heads, but the result of the
  merge is always the current branch head. It is meant to
  be used to supersede old development history of side
  branches.
 </p>
 </dd>
 </dl>
 <p>If you tried a merge which resulted in a complex conflicts and
 would want to start over, you can recover with
 <a href="git-reset.html">git-reset(1)</a>.</p>
 </div>
 <h2>HOW MERGE WORKS</h2>
 <div class="sectionbody">
 <p>A merge is always between the current <tt>HEAD</tt> and one or more
 remote branch heads, and the index file must exactly match the
 tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) when
 it happens. In other words, <tt>git-diff --cached HEAD</tt> must
 report no changes.</p>
 <div class="admonitionblock">
 <table><tr>
 <td class="icon">
 <div class="title">Note</div>
 </td>
 <td class="content">This is a bit of lie. In certain special cases, your index are
 allowed to be different from the tree of <tt>HEAD</tt> commit. The most
 notable case is when your <tt>HEAD</tt> commit is already ahead of what
 is being merged, in which case your index can have arbitrary
 difference from your <tt>HEAD</tt> commit. Otherwise, your index entries
 are allowed have differences from your <tt>HEAD</tt> commit that match
 the result of trivial merge (e.g. you received the same patch
 from external source to produce the same result as what you are
 merging). For example, if a path did not exist in the common
 ancestor and your head commit but exists in the tree you are
 merging into your repository, and if you already happen to have
 that path exactly in your index, the merge does not have to
 fail.</td>
 </tr></table>
 </div>
 <p>Otherwise, merge will refuse to do any harm to your repository
 (that is, it may fetch the objects from remote, and it may even
 update the local branch used to keep track of the remote branch
 with <tt>git pull remote rbranch:lbranch</tt>, but your working tree,
 <tt>.git/HEAD</tt> pointer and index file are left intact).</p>
 <p>You may have local modifications in the working tree files. In
 other words, <tt>git-diff</tt> is allowed to report changes.
 However, the merge uses your working tree as the working area,
 and in order to prevent the merge operation from losing such
 changes, it makes sure that they do not interfere with the
 merge. Those complex tables in read-tree documentation define
 what it means for a path to "interfere with the merge". And if
 your local modifications interfere with the merge, again, it
 stops before touching anything.</p>
 <p>So in the above two "failed merge" case, you do not have to
 worry about lossage of data --- you simply were not ready to do
 a merge, so no merge happened at all. You may want to finish
 whatever you were in the middle of doing, and retry the same
 pull after you are done and ready.</p>
 <p>When things cleanly merge, these things happen:</p>
 <ol>
 <li>
 <p>
 the results are updated both in the index file and in your
  working tree,
 </p>
 </li>
 <li>
 <p>
 index file is written out as a tree,
 </p>
 </li>
 <li>
 <p>
 the tree gets committed, and
 </p>
 </li>
 <li>
 <p>
 the <tt>HEAD</tt> pointer gets advanced.
 </p>
 </li>
 </ol>
 <p>Because of 2., we require that the original state of the index
 file to match exactly the current <tt>HEAD</tt> commit; otherwise we
 will write out your local changes already registered in your
 index file along with the merge result, which is not good.
 Because 1. involves only the paths different between your
 branch and the remote branch you are pulling from during the
 merge (which is typically a fraction of the whole tree), you can
 have local modifications in your working tree as long as they do
 not overlap with what the merge updates.</p>
 <p>When there are conflicts, these things happen:</p>
 <ol>
 <li>
 <p>
 <tt>HEAD</tt> stays the same.
 </p>
 </li>
 <li>
 <p>
 Cleanly merged paths are updated both in the index file and
  in your working tree.
 </p>
 </li>
 <li>
 <p>
 For conflicting paths, the index file records up to three
  versions; stage1 stores the version from the common ancestor,
  stage2 from <tt>HEAD</tt>, and stage3 from the remote branch (you
  can inspect the stages with <tt>git-ls-files -u</tt>). The working
  tree files have the result of "merge" program; i.e. 3-way
  merge result with familiar conflict markers <tt>&lt;&lt;&lt; === &gt;&gt;&gt;</tt>.
 </p>
 </li>
 <li>
 <p>
 No other changes are done. In particular, the local
  modifications you had before you started merge will stay the
  same and the index entries for them stay as they were,
  i.e. matching <tt>HEAD</tt>.
 </p>
 </li>
 </ol>
 <p>After seeing a conflict, you can do two things:</p>
 <ul>
 <li>
 <p>
 Decide not to merge. The only clean-up you need are to reset
  the index file to the <tt>HEAD</tt> commit to reverse 2. and to clean
  up working tree changes made by 2. and 3.; <tt>git-reset</tt> can
  be used for this.
 </p>
 </li>
 <li>
 <p>
 Resolve the conflicts. <tt>git-diff</tt> would report only the
  conflicting paths because of the above 2. and 3.. Edit the
  working tree files into a desirable shape, <tt>git-update-index</tt>
  them, to make the index file contain what the merge result
  should be, and run <tt>git-commit</tt> to commit the result.
 </p>
 </li>
 </ul>
 </div>
 <h2>SEE ALSO</h2>
 <div class="sectionbody">
 <p><a href="git-fmt-merge-msg.html">git-fmt-merge-msg(1)</a>, <a href="git-pull.html">git-pull(1)</a></p>
 </div>
 <h2>Author</h2>
 <div class="sectionbody">
 <p>Written by Junio C Hamano &lt;junkio@cox.net&gt;</p>
 </div>
 <h2>Documentation</h2>
 <div class="sectionbody">
 <p>Documentation by Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p>
 </div>
 <h2>GIT</h2>
 <div class="sectionbody">
 <p>Part of the <a href="git.html">git(7)</a> suite</p>
 </div>
 <div id="footer">
 <div id="footer-text">
 Last updated 27-Dec-2005 00:16:22 PDT
 </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta name="generator" content="AsciiDoc 7.0.1" />
	<style type="text/css">
	/* Debug borders */
	p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
	/*
	border: 1px solid red;
	*/
	}

	body {
	margin: 1em 5% 1em 5%;
	}

	a { color: blue; }
	a:visited { color: fuchsia; }

	em {
	font-style: italic;
	}

	strong {
	font-weight: bold;
	}

	tt {
	color: navy;
	}

	h1, h2, h3, h4, h5, h6 {
	color: #527bbd;
	font-family: sans-serif;
	margin-top: 1.2em;
	margin-bottom: 0.5em;
	line-height: 1.3;
	}

	h1 {
	border-bottom: 2px solid silver;
	}
	h2 {
	border-bottom: 2px solid silver;
	padding-top: 0.5em;
	}

	div.sectionbody {
	font-family: serif;
	margin-left: 0;
	}

	hr {
	border: 1px solid silver;
	}

	p {
	margin-top: 0.5em;
	margin-bottom: 0.5em;
	}

	pre {
	padding: 0;
	margin: 0;
	}

	span#author {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	font-size: 1.2em;
	}
	span#email {
	}
	span#revision {
	font-family: sans-serif;
	}

	div#footer {
	font-family: sans-serif;
	font-size: small;
	border-top: 2px solid silver;
	padding-top: 0.5em;
	margin-top: 4.0em;
	}
	div#footer-text {
	float: left;
	padding-bottom: 0.5em;
	}
	div#footer-badges {
	float: right;
	padding-bottom: 0.5em;
	}

	div#preamble,
	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
	div.admonitionblock {
	margin-right: 10%;
	margin-top: 1.5em;
	margin-bottom: 1.5em;
	}
	div.admonitionblock {
	margin-top: 2.5em;
	margin-bottom: 2.5em;
	}

	div.content { /* Block element content. */
	padding: 0;
	}

	/* Block element titles. */
	div.title, caption.title {
	font-family: sans-serif;
	font-weight: bold;
	text-align: left;
	margin-top: 1.0em;
	margin-bottom: 0.5em;
	}
	div.title + * {
	margin-top: 0;
	}

	td div.title:first-child {
	margin-top: 0.0em;
	}
	div.content div.title:first-child {
	margin-top: 0.0em;
	}
	div.content + div.title {
	margin-top: 0.0em;
	}

	div.sidebarblock > div.content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}

	div.listingblock > div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock > div.content {
	padding-left: 2.0em;
	}
	div.quoteblock .attribution {
	text-align: right;
	}

	div.admonitionblock .icon {
	vertical-align: top;
	font-size: 1.1em;
	font-weight: bold;
	text-decoration: underline;
	color: #527bbd;
	padding-right: 0.5em;
	}
	div.admonitionblock td.content {
	padding-left: 0.5em;
	border-left: 2px solid silver;
	}

	div.exampleblock > div.content {
	border-left: 2px solid silver;
	padding: 0.5em;
	}

	div.verseblock div.content {
	white-space: pre;
	}

	div.imageblock div.content { padding-left: 0; }
	div.imageblock img { border: 1px solid silver; }
	span.image img { border-style: none; }

	dl {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	dt {
	margin-top: 0.5em;
	margin-bottom: 0;
	font-style: italic;
	}
	dd > *:first-child {
	margin-top: 0;
	}

	ul, ol {
	list-style-position: outside;
	}
	ol.olist2 {
	list-style-type: lower-alpha;
	}

	div.tableblock > table {
	border-color: #527bbd;
	border-width: 3px;
	}
	thead {
	font-family: sans-serif;
	font-weight: bold;
	}
	tfoot {
	font-weight: bold;
	}

	div.hlist {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	td.hlist1 {
	vertical-align: top;
	font-style: italic;
	padding-right: 0.8em;
	}
	td.hlist2 {
	vertical-align: top;
	}

	@media print {
	div#footer-badges { display: none; }
	}
	include::./stylesheets/xhtml11-manpage.css[]
	/* Workarounds for IE6's broken and incomplete CSS2. */

	div.sidebar-content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}
	div.sidebar-title, div.image-title {
	font-family: sans-serif;
	font-weight: bold;
	margin-top: 0.0em;
	margin-bottom: 0.5em;
	}

	div.listingblock div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock-content {
	padding-left: 2.0em;
	}

	div.exampleblock-content {
	border-left: 2px solid silver;
	padding-left: 0.5em;
	}
	</style>
	<title>git-merge(1)</title>
	</head>
	<body>
	<div id="header">
	<h1>
	git-merge(1) Manual Page
	</h1>
	<h2>NAME</h2>
	<div class="sectionbody">
	<p>git-merge -
	Grand Unified Merge Driver
	</p>
	</div>
	</div>
	<h2>SYNOPSIS</h2>
	<div class="sectionbody">
	<p><em>git-merge</em> [-n] [--no-commit] [-s <strategy>]… <msg> <head> <remote> <remote>…</p>
	</div>
	<h2>DESCRIPTION</h2>
	<div class="sectionbody">
	<p>This is the top-level user interface to the merge machinery
	which drives multiple merge strategy scripts.</p>
	</div>
	<h2>OPTIONS</h2>
	<div class="sectionbody">
	<dl>
	<dt>
	-n, --no-summary
	</dt>
	<dd>
	<p>
	Do not show diffstat at the end of the merge.
	</p>
	</dd>
	<dt>
	--no-commit
	</dt>
	<dd>
	<p>
	Perform the merge but pretend the merge failed and do
	not autocommit, to give the user a chance to inspect and
	further tweak the merge result before committing.
	</p>
	</dd>
	<dt>
	-s <strategy>, --strategy=<strategy>
	</dt>
	<dd>
	<p>
	Use the given merge strategy; can be supplied more than
	once to specify them in the order they should be tried.
	If there is no <tt>-s</tt> option, a built-in list of strategies
	is used instead (<tt>git-merge-recursive</tt> when merging a single
	head, <tt>git-merge-octopus</tt> otherwise).
	</p>
	</dd>
	<dt>
	<msg>
	</dt>
	<dd>
	<p>
	The commit message to be used for the merge commit (in case
	it is created). The <tt>git-fmt-merge-msg</tt> script can be used
	to give a good default for automated <tt>git-merge</tt> invocations.
	</p>
	</dd>
	<dt>
	<head>
	</dt>
	<dd>
	<p>
	our branch head commit.
	</p>
	</dd>
	<dt>
	<remote>
	</dt>
	<dd>
	<p>
	other branch head merged into our branch. You need at
	least one <remote>. Specifying more than one <remote>
	obviously means you are trying an Octopus.
	</p>
	</dd>
	</dl>
	</div>
	<h2>MERGE STRATEGIES</h2>
	<div class="sectionbody">
	<dl>
	<dt>
	resolve
	</dt>
	<dd>
	<p>
	This can only resolve two heads (i.e. the current branch
	and another branch you pulled from) using 3-way merge
	algorithm. It tries to carefully detect criss-cross
	merge ambiguities and is considered generally safe and
	fast.
	</p>
	</dd>
	<dt>
	recursive
	</dt>
	<dd>
	<p>
	This can only resolve two heads using 3-way merge
	algorithm. When there are more than one common
	ancestors that can be used for 3-way merge, it creates a
	merged tree of the common ancestors and uses that as
	the reference tree for the 3-way merge. This has been
	reported to result in fewer merge conflicts without
	causing mis-merges by tests done on actual merge commits
	taken from Linux 2.6 kernel development history.
	Additionally this can detect and handle merges involving
	renames. This is the default merge strategy when
	pulling or merging one branch.
	</p>
	</dd>
	<dt>
	octopus
	</dt>
	<dd>
	<p>
	This resolves more than two-head case, but refuses to do
	complex merge that needs manual resolution. It is
	primarily meant to be used for bundling topic branch
	heads together. This is the default merge strategy when
	pulling or merging more than one branches.
	</p>
	</dd>
	<dt>
	ours
	</dt>
	<dd>
	<p>
	This resolves any number of heads, but the result of the
	merge is always the current branch head. It is meant to
	be used to supersede old development history of side
	branches.
	</p>
	</dd>
	</dl>
	<p>If you tried a merge which resulted in a complex conflicts and
	would want to start over, you can recover with
	<a href="git-reset.html">git-reset(1)</a>.</p>
	</div>
	<h2>HOW MERGE WORKS</h2>
	<div class="sectionbody">
	<p>A merge is always between the current <tt>HEAD</tt> and one or more
	remote branch heads, and the index file must exactly match the
	tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) when
	it happens. In other words, <tt>git-diff --cached HEAD</tt> must
	report no changes.</p>
	<div class="admonitionblock">
	<table><tr>
	<td class="icon">
	<div class="title">Note</div>
	</td>
	<td class="content">This is a bit of lie. In certain special cases, your index are
	allowed to be different from the tree of <tt>HEAD</tt> commit. The most
	notable case is when your <tt>HEAD</tt> commit is already ahead of what
	is being merged, in which case your index can have arbitrary
	difference from your <tt>HEAD</tt> commit. Otherwise, your index entries
	are allowed have differences from your <tt>HEAD</tt> commit that match
	the result of trivial merge (e.g. you received the same patch
	from external source to produce the same result as what you are
	merging). For example, if a path did not exist in the common
	ancestor and your head commit but exists in the tree you are
	merging into your repository, and if you already happen to have
	that path exactly in your index, the merge does not have to
	fail.</td>
	</tr></table>
	</div>
	<p>Otherwise, merge will refuse to do any harm to your repository
	(that is, it may fetch the objects from remote, and it may even
	update the local branch used to keep track of the remote branch
	with <tt>git pull remote rbranch:lbranch</tt>, but your working tree,
	<tt>.git/HEAD</tt> pointer and index file are left intact).</p>
	<p>You may have local modifications in the working tree files. In
	other words, <tt>git-diff</tt> is allowed to report changes.
	However, the merge uses your working tree as the working area,
	and in order to prevent the merge operation from losing such
	changes, it makes sure that they do not interfere with the
	merge. Those complex tables in read-tree documentation define
	what it means for a path to "interfere with the merge". And if
	your local modifications interfere with the merge, again, it
	stops before touching anything.</p>
	<p>So in the above two "failed merge" case, you do not have to
	worry about lossage of data --- you simply were not ready to do
	a merge, so no merge happened at all. You may want to finish
	whatever you were in the middle of doing, and retry the same
	pull after you are done and ready.</p>
	<p>When things cleanly merge, these things happen:</p>
	<ol>
	<li>
	<p>
	the results are updated both in the index file and in your
	working tree,
	</p>
	</li>
	<li>
	<p>
	index file is written out as a tree,
	</p>
	</li>
	<li>
	<p>
	the tree gets committed, and
	</p>
	</li>
	<li>
	<p>
	the <tt>HEAD</tt> pointer gets advanced.
	</p>
	</li>
	</ol>
	<p>Because of 2., we require that the original state of the index
	file to match exactly the current <tt>HEAD</tt> commit; otherwise we
	will write out your local changes already registered in your
	index file along with the merge result, which is not good.
	Because 1. involves only the paths different between your
	branch and the remote branch you are pulling from during the
	merge (which is typically a fraction of the whole tree), you can
	have local modifications in your working tree as long as they do
	not overlap with what the merge updates.</p>
	<p>When there are conflicts, these things happen:</p>
	<ol>
	<li>
	<p>
	<tt>HEAD</tt> stays the same.
	</p>
	</li>
	<li>
	<p>
	Cleanly merged paths are updated both in the index file and
	in your working tree.
	</p>
	</li>
	<li>
	<p>
	For conflicting paths, the index file records up to three
	versions; stage1 stores the version from the common ancestor,
	stage2 from <tt>HEAD</tt>, and stage3 from the remote branch (you
	can inspect the stages with <tt>git-ls-files -u</tt>). The working
	tree files have the result of "merge" program; i.e. 3-way
	merge result with familiar conflict markers <tt><<< === >>></tt>.
	</p>
	</li>
	<li>
	<p>
	No other changes are done. In particular, the local
	modifications you had before you started merge will stay the
	same and the index entries for them stay as they were,
	i.e. matching <tt>HEAD</tt>.
	</p>
	</li>
	</ol>
	<p>After seeing a conflict, you can do two things:</p>
	<ul>
	<li>
	<p>
	Decide not to merge. The only clean-up you need are to reset
	the index file to the <tt>HEAD</tt> commit to reverse 2. and to clean
	up working tree changes made by 2. and 3.; <tt>git-reset</tt> can
	be used for this.
	</p>
	</li>
	<li>
	<p>
	Resolve the conflicts. <tt>git-diff</tt> would report only the
	conflicting paths because of the above 2. and 3.. Edit the
	working tree files into a desirable shape, <tt>git-update-index</tt>
	them, to make the index file contain what the merge result
	should be, and run <tt>git-commit</tt> to commit the result.
	</p>
	</li>
	</ul>
	</div>
	<h2>SEE ALSO</h2>
	<div class="sectionbody">
	<p><a href="git-fmt-merge-msg.html">git-fmt-merge-msg(1)</a>, <a href="git-pull.html">git-pull(1)</a></p>
	</div>
	<h2>Author</h2>
	<div class="sectionbody">
	<p>Written by Junio C Hamano <junkio@cox.net></p>
	</div>
	<h2>Documentation</h2>
	<div class="sectionbody">
	<p>Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.</p>
	</div>
	<h2>GIT</h2>
	<div class="sectionbody">
	<p>Part of the <a href="git.html">git(7)</a> suite</p>
	</div>
	<div id="footer">
	<div id="footer-text">
	Last updated 27-Dec-2005 00:16:22 PDT
	</div>
	</div>
	</body>
	</html>