it is created). The 'git-fmt-merge-msg' script can be used
to give a good default for automated 'git-merge' invocations.
-<remote>::
- Other branch head merged into our branch. You need at
+<remote>...::
+ Other branch heads to merge into our branch. You need at
least one <remote>. Specifying more than one <remote>
obviously means you are trying an Octopus.
A merge is always between the current `HEAD` and one or more
commits (usually, branch head or tag), and the index file must
-exactly match the
-tree of `HEAD` commit (i.e. the contents of the last commit) when
-it happens. In other words, `git diff --cached HEAD` must
-report no changes.
-
-[NOTE]
-This is a bit of a lie. In certain special cases, your index is
-allowed to be different from the tree of the `HEAD` commit. The most
-notable case is when your `HEAD` commit is already ahead of what
-is being merged, in which case your index can have arbitrary
-differences from your `HEAD` commit. Also, your index entries
-may have differences from your `HEAD` commit that match
-the result of a trivial merge (e.g. you received the same patch
-from an 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.
-
-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 `git pull remote rbranch:lbranch`, but your working tree,
-`.git/HEAD` pointer and index file are left intact).
-
-You may have local modifications in the working tree files. In
-other words, 'git-diff' 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.
-
-So in the above two "failed merge" case, you do not have to
-worry about loss 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.
-
+match the tree of `HEAD` commit (i.e. the contents of the last commit)
+when it starts out. In other words, `git diff --cached HEAD` must
+report no changes. (One exception is when the changed index
+entries are already in the same state that would result from
+the merge anyway.)
+
+Three kinds of merge can happen:
+
+* The merged commit is already contained in `HEAD`. This is the
+ simplest case, called "Already up-to-date."
+
+* `HEAD` is already contained in the merged commit. This is the
+ most common case especially when involved through 'git pull':
+ you are tracking an upstream repository, committed no local
+ changes and now you want to update to a newer upstream revision.
+ Your `HEAD` (and the index) is updated to at point the merged
+ commit, without creating an extra merge commit. This is
+ called "Fast-forward".
+
+* Both the merged commit and `HEAD` are independent and must be
+ tied together by a merge commit that has them both as its parents.
+ The rest of this section describes this "True merge" case.
+
+The chosen merge strategy merges the two commits into a single
+new source tree.
When things cleanly merge, these things happen:
1. The results are updated both in the index file and in your
* Decide not to merge. The only clean-up you need are to reset
the index file to the `HEAD` commit to reverse 2. and to clean
- up working tree changes made by 2. and 3.; 'git-reset' can
+ up working tree changes made by 2. and 3.; 'git-reset --hard' can
be used for this.
- * Resolve the conflicts. `git diff` would report only the
- conflicting paths because of the above 2. and 3. Edit the
- working tree files into a desirable shape, 'git-add' or 'git-rm'
- them, to make the index file contain what the merge result
- should be, and run 'git-commit' to commit the result.
+ * Resolve the conflicts. Git will mark the conflicts in
+ the working tree. Edit the files into shape and
+ 'git-add' to the index. 'git-commit' to seal the deal.
+
+You can work through the conflict with a number of tools:
+
+ * Use a mergetool. 'git mergetool' to launch a graphical
+ mergetool which will work you through the merge.
+
+ * Look at the diffs. 'git diff' will show a three-way diff,
+ highlighting changes from both the HEAD and remote versions.
+
+ * Look at the diffs on their own. 'git log --merge -p <path>'
+ will show diffs first for the HEAD version and then the
+ remote version.
+ * Look at the originals. 'git show :1:filename' shows the
+ common ancestor, 'git show :2:filename' shows the HEAD
+ version and 'git show :3:filename' shows the remote version.
SEE ALSO
--------
Author
------
-Written by Junio C Hamano <junkio@cox.net>
+Written by Junio C Hamano <gitster@pobox.com>
Documentation