From: Jonathan Nieder <jrnieder@gmail•com>
To: Junio C Hamano <gitster@pobox•com>
Cc: Thomas Rast <trast@student•ethz.ch>, Petr Baudis <pasky@suse•cz>,
git@vger•kernel.org
Subject: [PATCH 4/6] Documentation: emphasize when git merge terminates early
Date: Mon, 11 Jan 2010 02:37:54 -0600 [thread overview]
Message-ID: <20100111083754.GD23806@progeny.tock> (raw)
In-Reply-To: <20100111082123.GA23742@progeny.tock>
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 <pasky@suse•cz>,
Cc: Junio C Hamano <gitster@pobox•com>
Cc: Thomas Rast <trast@student•ethz.ch>
Not-signed-off-by: Jonathan Nieder <jrnieder@gmail•com>
---
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
next prev parent reply other threads:[~2010-01-11 8:38 UTC|newest]
Thread overview: 46+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-01-07 17:03 [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull" Thomas Rast
2010-01-07 17:03 ` [PATCH 2/2] Documentation: warn prominently against merging with dirty trees Thomas Rast
2010-01-07 17:03 ` [NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font Thomas Rast
2010-01-07 20:25 ` Jonathan Nieder
2010-01-07 21:08 ` Junio C Hamano
2010-01-07 18:01 ` [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull" Junio C Hamano
2010-01-10 0:02 ` [PATCH v2 0/4] Documentation style fixes Thomas Rast
2010-01-10 0:02 ` [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull" Thomas Rast
2010-01-10 4:13 ` Jonathan Nieder
2010-01-10 12:24 ` Thomas Rast
2010-01-23 22:48 ` [PATCH] Documentation: merge: use MERGE_HEAD to refer to the remote branch Jonathan Nieder
2010-01-10 0:02 ` [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees Thomas Rast
2010-01-10 4:49 ` Jonathan Nieder
2010-01-10 6:31 ` Junio C Hamano
2010-01-10 12:16 ` Thomas Rast
2010-01-11 2:13 ` Jonathan Nieder
2010-01-11 2:30 ` Junio C Hamano
2010-01-11 4:13 ` Jonathan Nieder
2010-01-11 8:21 ` [PATCH 0/6] " Jonathan Nieder
2010-01-11 8:27 ` [PATCH/RFC 1/6] Documentation: clarify one-line description for merge Jonathan Nieder
2010-01-11 8:30 ` [PATCH 2/6] Documentation: merge: add an overview Jonathan Nieder
2010-01-11 10:09 ` Junio C Hamano
2010-01-11 8:37 ` Jonathan Nieder [this message]
2010-01-11 23:11 ` [PATCH 4/6] Documentation: emphasize when git merge terminates early Thomas Rast
2010-01-11 8:39 ` [PATCH 5/6] Documentation: merge: add a section about fast-forward Jonathan Nieder
2010-01-11 8:43 ` [PATCH 6/6] Documentation: tweak How Merge Works Jonathan Nieder
2010-01-11 23:11 ` Thomas Rast
2010-01-13 10:44 ` [PATCH 0/6] Re: Documentation: warn prominently against merging with dirty trees Petr Baudis
2010-01-13 6:55 ` [PATCH v2 2/4] " Junio C Hamano
2010-01-10 0:02 ` [PATCH v2 3/4] Documentation: format full commands in typewriter font Thomas Rast
2010-01-10 3:31 ` Jonathan Nieder
2010-01-10 0:07 ` [PATCH v2 0/4] Documentation style fixes Thomas Rast
2010-01-10 0:19 ` Thomas Rast
2010-01-10 6:34 ` Junio C Hamano
2010-01-10 12:10 ` Thomas Rast
2010-01-10 12:10 ` [PATCH 1/2] More missed dashed 'git-cmd' forms Thomas Rast
2010-01-10 12:10 ` [PATCH 2/2] More missed `code snippets` Thomas Rast
2010-01-10 12:11 ` [PATCH] Documentation: show-files is now called git-ls-files Thomas Rast
2010-01-18 1:18 ` [PATCH v2 0/4] Documentation style fixes Junio C Hamano
2010-01-19 17:29 ` Thomas Rast
2010-01-19 17:39 ` Jonathan Nieder
2010-01-10 7:12 ` Junio C Hamano
[not found] ` <9516c897017ec420403bb7f687fb8962de42cb7c.1263081032.git.trast@student.ethz.ch>
2010-01-10 2:56 ` [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout Jonathan Nieder
2010-01-10 2:59 ` [PATCH 1/2] Documentation: git gc packs refs by default now Jonathan Nieder
2010-01-10 3:01 ` [PATCH 2/2] Documentation: tiny git config manual tweaks Jonathan Nieder
2010-01-10 12:21 ` [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout Thomas Rast
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20100111083754.GD23806@progeny.tock \
--to=jrnieder@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=pasky@suse$(echo .)cz \
--cc=trast@student$(echo .)ethz.ch \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox