Re: git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)

Re: git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)

[Jonathon Mah]

>         Some git command (ex. git describe) by default only consider 
> annotated tags.

I always add --tags when I call git-describe. Is there any reason this shouldn't become the new default (quickly, before git 2.0 perhaps)? I wasn't able to find any reason for the current behavior with just a little digging.



Jonathon Mah
me@JonathonMah.com

Re: git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)

[Junio C Hamano]

Jonathon Mah <me@JonathonMah.com> writes:

> I always add --tags when I call git-describe. Is there any reason this shouldn't become the new default (quickly, before git 2.0 perhaps)?

The distinction is there for a reason--- annotated tags are meant
for the more "public" and "permanent" stuff, while you can do
lightweight tags for random short-term stuff.

An argument could be to change Git not to follow unannotated tags
with "git fetch" and "git push --follow-tags" by default, which goes
in the direction to make the distinction even clear.  But for a
change to make the distinction less useful, I would have to say it
is probably a bad idea.

git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)

[Daniele Segato]

Hi,

I think there is an issue with the documentation of git tag, or with the 
default being chosen for tags.

the git tag documentation say:

*****
        If one of -a, -s, or -u <key-id> is passed, the command creates 
a tag object, and requires a tag message. Unless -m <msg> or -F <file> 
is given, an editor is started for the user to type in the tag
        message.

        If -m <msg> or -F <file> is given and -a, -s, and -u <key-id> 
are absent, -a is implied.

        Otherwise just a tag reference for the SHA1 object name of the 
commit object is created (i.e. a lightweight tag).
******

And no options below is provided to list annotated tags only or 
lightweight tags only (is there a way to do so?)

I initially didn't get git cared too much on this difference: I've been 
using both annotated and lightweight tags without distinctions, 
annotated when I want to write something about the tag and non-annotated 
when I do not need it.

Since no option is given to show annotated only tags these made sense to me.



Recently I started using submodules and I noticed that:
git submodule status

sometimes gave me the tag name of the submodule between parentesis and 
sometimes it gave me something like this:
+6903774653de52d0206e0e6026ca6914def8a333 submodule (1.0-2-g6903774)

even if the 6903774653de52d0206e0e6026ca6914def8a333 was actually a tag 
(1.1)

the git help submodule say status use git describe, so I've entered the 
submodule directory and tried:

$ git describe
1.0-2-g6903774

$ git describe --tags
1.1

reading the git help describe I discovered the git describe made an 
assumption and default to just show annotated tags.


To me, this assumption should have been documented very clearly in the 
git tag help page, something like this:

*****
        If one of -a, -s, or -u <key-id> is passed, the command creates 
a tag object, and requires a tag message. Unless -m <msg> or -F <file> 
is given, an editor is started for the user to type in the tag
        message.

        If -m <msg> or -F <file> is given and -a, -s, and -u <key-id> 
are absent, -a is implied.

        Otherwise just a tag reference for the SHA1 object name of the 
commit object is created (i.e. a lightweight tag).


        ANNOTATED vs LIGHTWEIGHT tags

        Some git command (ex. git describe) by default only consider 
annotated tags. Annotated and Lightweight tags are not the same thing 
for git and you shouldn't mix them up. Annotated tags are meant for 
release while lightweight tags are meant to tag random commits.
******

And I think an option in git tag to only show annotated tags (or only 
show lightweight tags) is needed.



Finally, now that I discovered this I can't replace the lightweights 
tags with annotated tags without a public announcement requiring all 
developers to delete their local tags.

I'm not aware of any discussion you did about this matter but I think 
there's something wrong here that should be fixed.

Regards,
Daniele Segato

Re: git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)

[Junio C Hamano]

Daniele Segato <daniele.segato@gmail.com> writes:

> Annotated and Lightweight tags are not the same thing
> for git and you shouldn't mix them up. Annotated tags are meant for
> release while lightweight tags are meant to tag random commits.

Nicely explained.

This is one of those "we who worked on Git (not worked "with" Git)
for a long time _know_ it and do not need it to be explained, and we
didn't spot that it is not explained in the documentation for new
people."

Care to roll a documentation patch (and get a commit count for
yourself ;-)?

Thanks.

Re: git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)

[Daniele Segato]

On 07/24/2013 10:34 PM, Junio C Hamano wrote:
> Daniele Segato <daniele.segato@gmail.com> writes:
>
>> Annotated and Lightweight tags are not the same thing
>> for git and you shouldn't mix them up. Annotated tags are meant for
>> release while lightweight tags are meant to tag random commits.
>
> Nicely explained.
>
> This is one of those "we who worked on Git (not worked "with" Git)
> for a long time _know_ it and do not need it to be explained, and we
> didn't spot that it is not explained in the documentation for new
> people."

Good!

Any change in adding an option to filter tags list by annotated only?


>
> Care to roll a documentation patch (and get a commit count for
> yourself ;-)?

I tried, just sent the patch, hopefully I managed to follow the guide I 
found here: 
http://repo.or.cz/w/git.git?a=blob;f=Documentation/SubmittingPatches;hb=HEAD

As you suggested I removed the "title" line and the reference to git 
describe default.

If I did something wrong please explain me what and I'll fix it

>
> Thanks.

You're Welcome :-)

Cheers,
Daniele Segato