Re: [PATCH] Documentation: merging a tag is a special case
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 21, 2013, 19:50 UTC
- Message-ID
- <7vmwtwa5xa.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <7vboadevpk.fsf@alter.siamese.dyndns.org>
Junio C Hamano <gitster@pobox.com> writes:
Show 21 quoted lines
>> +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