"man git-tag" inconsistent about whether you can tag non-commit objects

"man git-tag" inconsistent about whether you can tag non-commit objects

[Robert P. J. Day]

  embarrassed to admit i had no idea that you could tag non-commit
objects, only realized that when i was reading the man page and saw:

  SYNOPSIS
     git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
           <tagname> [<commit> | <object>]
                                 ^^^^^^^^

so i tried it and, sure enough, i could tag a blob object. but if you
read further into DESCRIPTION, about halfway through, you read:

  "Otherwise just a tag reference for the SHA-1 object name of the
   commit object is created (i.e. a lightweight tag)."
   ^^^^^^

which suggests only commit objects. finally, much further down, under
OPTIONS:

  "<commit>, <object>
     The object that the new tag will refer to, usually a commit.
                                                ^^^^^^^^^^^^^^^^

so to clean this up, is it sufficient to just change that middle line
to say "object" rather than "commit object"? or is there more in the
man page that needs tweaking?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                  http://crashcourse.ca/dokuwiki

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: "man git-tag" inconsistent about whether you can tag non-commit objects

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>   embarrassed to admit i had no idea that you could tag non-commit
> objects, only realized that when i was reading the man page and saw:
>
>   SYNOPSIS
>      git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
>            <tagname> [<commit> | <object>]
>                                  ^^^^^^^^
>
> so i tried it and, sure enough, i could tag a blob object. but if you
> read further into DESCRIPTION, about halfway through, you read:
>
>   "Otherwise just a tag reference for the SHA-1 object name of the
>    commit object is created (i.e. a lightweight tag)."
>    ^^^^^^
>
> which suggests only commit objects. finally, much further down, under
> OPTIONS:
>
>   "<commit>, <object>
>      The object that the new tag will refer to, usually a commit.
>                                                 ^^^^^^^^^^^^^^^^
>
> so to clean this up, is it sufficient to just change that middle line
> to say "object" rather than "commit object"? or is there more in the
> man page that needs tweaking?

As that sentence talks about a lightweight tag (i.e. a reference in
refs/tags/ hierarchy that directly points at an object of any kind),
another possibility would be to say

	Otherwise a tag reference that directly points at the given
	object (i.e. lightweight tag) is created.

Re: "man git-tag" inconsistent about whether you can tag non-commit objects

[Ævar Arnfjörð Bjarmason]

On Fri, May 25 2018, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
>>   embarrassed to admit i had no idea that you could tag non-commit
>> objects, only realized that when i was reading the man page and saw:
>>
>>   SYNOPSIS
>>      git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
>>            <tagname> [<commit> | <object>]
>>                                  ^^^^^^^^
>>
>> so i tried it and, sure enough, i could tag a blob object. but if you
>> read further into DESCRIPTION, about halfway through, you read:
>>
>>   "Otherwise just a tag reference for the SHA-1 object name of the
>>    commit object is created (i.e. a lightweight tag)."
>>    ^^^^^^
>>
>> which suggests only commit objects. finally, much further down, under
>> OPTIONS:
>>
>>   "<commit>, <object>
>>      The object that the new tag will refer to, usually a commit.
>>                                                 ^^^^^^^^^^^^^^^^
>>
>> so to clean this up, is it sufficient to just change that middle line
>> to say "object" rather than "commit object"? or is there more in the
>> man page that needs tweaking?
>
> As that sentence talks about a lightweight tag (i.e. a reference in
> refs/tags/ hierarchy that directly points at an object of any kind),
> another possibility would be to say
>
> 	Otherwise a tag reference that directly points at the given
> 	object (i.e. lightweight tag) is created.

Related, this recent patch of mine:
https://public-inbox.org/git/20180429202100.32353-6-avarab@gmail.com/#t

I.e. might be worth talking about this briefly in the git-tag manpage as
well, i.e. that you can create a lightweight "tag" to a commit, but then
depending on where you push it it becomes either a branch or a tag,
which may not be intuitive to users...

Re: "man git-tag" inconsistent about whether you can tag non-commit objects

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

>> As that sentence talks about a lightweight tag (i.e. a reference in
>> refs/tags/ hierarchy that directly points at an object of any kind),
>> another possibility would be to say
>>
>> 	Otherwise a tag reference that directly points at the given
>> 	object (i.e. lightweight tag) is created.
>
> Related, this recent patch of mine:
> https://public-inbox.org/git/20180429202100.32353-6-avarab@gmail.com/#t
>
> I.e. might be worth talking about this briefly in the git-tag manpage as
> well, i.e. that you can create a lightweight "tag" to a commit, but then
> depending on where you push it it becomes either a branch or a tag,
> which may not be intuitive to users...

I am not sure if I agree.  People won't get confused, unless they
think too much and pedantically.

If you make refs/tags/$name point at a commit, it becomes a
lightweight tag, if you make refs/heads/$name point at a commit,
it becomes a local branch, if you make refs/remotes/$remote/$name
point at a commit, it behaves as a remote-tracking branch for the
named $remote.  Anywhere else, it is just a random ref that happens
to point at a commit.

And notice that I never said "push" in the above.  The verb I used
is "make" and that is deliberate.  It does not make any difference
if you make such a ref point at a commit by pushing into a
repository, fetching from elsewhere, or running "git branch", "git
tag", "git update-ref" locally.

Re: "man git-tag" inconsistent about whether you can tag non-commit objects

[Robert P. J. Day]

On Fri, 25 May 2018, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> >   embarrassed to admit i had no idea that you could tag non-commit
> > objects, only realized that when i was reading the man page and saw:
> >
> >   SYNOPSIS
> >      git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
> >            <tagname> [<commit> | <object>]
> >                                  ^^^^^^^^
> >
> > so i tried it and, sure enough, i could tag a blob object. but if you
> > read further into DESCRIPTION, about halfway through, you read:
> >
> >   "Otherwise just a tag reference for the SHA-1 object name of the
> >    commit object is created (i.e. a lightweight tag)."
> >    ^^^^^^
> >
> > which suggests only commit objects. finally, much further down, under
> > OPTIONS:
> >
> >   "<commit>, <object>
> >      The object that the new tag will refer to, usually a commit.
> >                                                 ^^^^^^^^^^^^^^^^
> >
> > so to clean this up, is it sufficient to just change that middle line
> > to say "object" rather than "commit object"? or is there more in the
> > man page that needs tweaking?
>
> As that sentence talks about a lightweight tag (i.e. a reference in
> refs/tags/ hierarchy that directly points at an object of any kind),
> another possibility would be to say
>
> 	Otherwise a tag reference that directly points at the given
> 	object (i.e. lightweight tag) is created.

  yup, that would resolve the issue. patch coming shortly.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                  http://crashcourse.ca/dokuwiki

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================