Junio C Hamano <gits...@pobox.com> writes:
>> +MERGING TAG
>> +-----------
>> +
>> +When merging a tag (annotated or signed), Git will create a merge commit
>> +...
>> +if the tag was signed. See also linkgit:git-tag[1].
>> +
>
> It would make it more helpful to readers to describe how _not_ to
> create such a merge commit if it is unwanted, and how the request to
> merge a tag interacts with --ff-only option.
>
>> @@ -26,7 +26,7 @@ set to `no` at the beginning of them.
>> --ff::
>> When the merge resolves as a fast-forward, only update the branch
>> pointer, without creating a merge commit. This is the default
>> - behavior.
>> + behavior (except when merging a tag).
>
> With this update, the reader will be left wondering what would be
> the default when she asks Git to merge a tag, no?
Taking Jonathan's input and the above into account, perhaps we can
do something like this on top of the posted patch?
Documentation/git-merge.txt | 26 +++++++++++++++++++++-----
Documentation/merge-options.txt | 5 +++--
2 files changed, 24 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index f7e68e1..75b5ee7 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -173,11 +173,27 @@ want to start over, you can recover with `git merge
--abort`.
MERGING TAG
-----------
-When merging a tag (annotated or signed), Git will create a merge commit
-even if a fast-forward merge is possible (see above).
-The commit message template will be created from the tag message.
-Additionally, the signature check will be reported as a comment
-if the tag was signed. See also linkgit:git-tag[1].
+When merging an annotated (and possibly signed) tag, Git always
+creates a merge commit even if a fast-forward merge is possible, and
+the commit message template is prepared with the tag message.
+Additionally, the signature check is reported as a comment
+if the tag is signed. See also linkgit:git-tag[1].
+
+Consequently a request `git merge --ff-only v1.2.3` to merge such a
+tag would fail.
+
+When you want to just integrate with the work leading to the commit
+that happens to be tagged, e.g. synchronizing with an upstream
+release point, you may not want to make an unnecessary merge commit
+especially when you do not have any work on your own. In such a
+case, you can "unwrap" the tag yourself before feeding it to `git
+merge`, e.g.
+
+---
+git fetch origin
+git merge [--ff-only] v1.2.3^0
+---
+
HOW CONFLICTS ARE PRESENTED
---------------------------
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index 70d1ec0..34a8445 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -26,11 +26,12 @@ set to `no` at the beginning of them.
--ff::
When the merge resolves as a fast-forward, only update the branch
pointer, without creating a merge commit. This is the default
- behavior (except when merging a tag).
+ behavior.
--no-ff::
Create a merge commit even when the merge resolves as a
- fast-forward.
+ fast-forward. This is the default behaviour when merging an
+ annotated (and possibly signed) tag.
--ff-only::
Refuse to merge and exit with a non-zero status unless the
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
