development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-07-17 02:57:48 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

Documentation: emphasize when git merge terminates early

Browse source 
A merge-based operation in git can fail in two ways: one that
stops before touching anything, or one that goes ahead and
results in conflicts.

As the 'git merge' manual explains:

| A merge is always between the current `HEAD` and one or more
| commits (usually, branch head or tag), and the index file must
| match the tree of `HEAD` commit (i.e. the contents of the last commit)
| when it starts out.

Unfortunately, the placement of this sentence makes it easy to
skip over, and its formulation leaves the important point, that
any other attempted merge will be gracefully aborted, unspoken.

So give this point its own section and expand upon it.

Probably this could be simplified somewhat: after all, a change
registered in the index is just a special kind of local
uncommited change, so the second added paragraph is only a
special case of the first.  It seemed more helpful to be explicit
here.

Inspired by <http://gitster.livejournal.com/25801.html>.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
This commit is contained in:
Jonathan Nieder 2010-01-23 03:44:17 -06:00 committed by Thomas Rast
parent b40bb374a6
commit 30f2bade84
1 changed files with 21 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
Documentation/git-merge.txt
View file

@ -67,21 +67,32 @@ include::merge-options.txt[]
<commit> obviously means you are trying an Octopus.
PRE-MERGE CHECKS
----------------
Before applying outside changes, you should get your own work in
good shape and committed locally, so it will not be clobbered if
there are conflicts. See also linkgit:git-stash[1].
'git pull' and 'git merge' will stop without doing anything when
local uncommitted changes overlap with files that 'git pull'/'git
merge' may need to update.
To avoid recording unrelated changes in the merge commit,
'git pull' and 'git merge' will also abort if there are any changes
registered in the index relative to the `HEAD` commit. (One
exception is when the changed index entries are in the state that
would result from the merge already.)
If all named commits are already ancestors of `HEAD`, 'git merge'
will exit early with the message "Already up-to-date."
HOW MERGE WORKS
---------------
A merge is always between the current `HEAD` and one or more
commits (usually, branch head or tag), and the index file must
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.)
commits (usually a branch head or tag).
Three kinds of merge can happen:
* The merged commit is already contained in `HEAD`. This is the
simplest case, called "Already up-to-date."
Two kinds of merge can happen:
* `HEAD` is already contained in the merged commit. This is the
most common case especially when invoked from 'git pull':