Documentation: merging a tag is a special case
When asking Git to merge a tag (such as a signed tag or annotated tag), it will always create a merge commit even if fast-forward was possible. It's like having --no-ff present on the command line. It's a difference from the default behavior described in git-merge.txt. It should be documented as an exception of "FAST-FORWARD MERGE" section and "--ff" option description. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Reviewed-by: Yann Droneaud <ydroneaud@opteya.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Mar 21, 2013 at 22:57 UTC
77c72780edfa5e3858423366fc91699724793b39
2 files changed
+26
-1
Documentation/git-merge.txt
+24
@@ -170,6 +170,30 @@ happens:
170
If you tried a merge which resulted in complex conflicts and
171
want to start over, you can recover with `git merge --abort`.
172
173
+MERGING TAG
174
+-----------
175
+
176
+When merging an annotated (and possibly signed) tag, Git always
177
+creates a merge commit even if a fast-forward merge is possible, and
178
+the commit message template is prepared with the tag message.
179
+Additionally, if the tag is signed, the signature check is reported
180
+as a comment in the message template. See also linkgit:git-tag[1].
181
+
182
+When you want to just integrate with the work leading to the commit
183
+that happens to be tagged, e.g. synchronizing with an upstream
184
+release point, you may not want to make an unnecessary merge commit.
185
+
186
+In such a case, you can "unwrap" the tag yourself before feeding it
187
+to `git merge`, or pass `--ff-only` when you do not have any work on
188
+your own. e.g.
189
+
190
+---
191
+git fetch origin
192
+git merge v1.2.3^0
193
+git merge --ff-only v1.2.3
194
+---
195
+
196
+
197
HOW CONFLICTS ARE PRESENTED
198
---------------------------
199
Documentation/merge-options.txt
+2
-1
@@ -30,7 +30,8 @@ set to `no` at the beginning of them.
30
31
--no-ff::
32
Create a merge commit even when the merge resolves as a
33
- fast-forward.
33
+ fast-forward. This is the default behaviour when merging an
34
+ annotated (and possibly signed) tag.
35
36
--ff-only::
37
Refuse to merge and exit with a non-zero status unless the