[PATCH 4/6] Documentation: emphasize when git merge terminates early
From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:47:59
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
A merge-based operation in git can fail in two ways: - One that stops before touching anything (either your index was dirty and nothing happened, or your index was clean but you had local modifications in your work tree). - Another that goes ahead and results in conflicts. The 'git merge' manual explains half of the first case as follows: | 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. The placement of this sentence makes it easy to skip over, and its formulation is perhaps too formal to be memorable. So give this point its own section and expand upon it. Most of the added text is taken from <http://gitster.livejournal.com/25801.html>. Cc: Petr Baudis <redacted>, Cc: Junio C Hamano <redacted> Cc: Thomas Rast <redacted> Not-signed-off-by: Jonathan Nieder [off-list ref] --- This is not signed off because most of the text is from Junio’s blog. I hope that is okay. Documentation/git-merge.txt | 34 ++++++++++++++++++++++++---------- 1 files changed, 24 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e29bb97..8950aa4 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt@@ -60,6 +60,28 @@ include::merge-options.txt[] least one <remote>. Specifying more than one <remote> obviously means you are trying an Octopus. +PRE-MERGE CHECKS +---------------- + +In some other version control systems, you merge/update and then +commit, with the risk of clobbering your changes with humongous +conflicts. You shouldn't be pulling or merging if you haven't got +your own work into good shape and committed it locally (see also +linkgit:git-stash[1]). + +But novices can make this mistake, and '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. + +Also, to avoid unrelated changes in the recorded commit, 'git +pull' and 'git merge' abort if there are any changes registered +in the index relative to the contents of the `HEAD` commit. +(One exception is when the changed index entries are already in +the same state that would result from the merge anyway.) + +If all named commits are already ancestors of `HEAD`, 'git merge' +will exit early with the message "Already up-to-date." + include::merge-strategies.txt[]
@@ -70,17 +92,9 @@ 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.) - -Three kinds of merge can happen: +commits (usually, branch head or tag). -* 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':
--
1.6.6