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). In addition,
-merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
-a problematic merge can be removed by using `git reset ORIG_HEAD`.
-
-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'
+ conflicting paths because of the above 2. and 3.
+ Edit the working tree files into a desirable shape
+ ('git mergetool' can ease this task), '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.
Author
------
-Written by Junio C Hamano <junkio@cox.net>
+Written by Junio C Hamano <gitster@pobox.com>
Documentation