# "man git-tag" inconsistent about whether you can tag non-commit objects 5 messages from 2018-05-24 to 2018-05-25. Participants: Robert P. J. Day, Junio C Hamano, Ævar Arnfjörð Bjarmason. Thread: https://gitlist.dev/t/48564 ## Robert P. J. Day, 2018-05-24 14:46 Subject: "man git-tag" inconsistent about whether you can tag non-commit objects Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.21.1805241040400.14773%40localhost.localdomain ``` 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 ] [-f] [-m | -F ] [-e] [ | ] ^^^^^^^^ 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: ", 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 ======================================================================== ``` ## Junio C Hamano, 2018-05-25 01:38 Subject: Re: "man git-tag" inconsistent about whether you can tag non-commit objects Message-ID: URL: https://gitlist.dev/e/xmqqpo1kpl9i.fsf%40gitster-ct.c.googlers.com In-Reply-To: ``` "Robert P. J. Day" 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 ] [-f] [-m | -F ] [-e] > [ | ] > ^^^^^^^^ > > 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: > > ", > 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. ``` ## Ævar Arnfjörð Bjarmason, 2018-05-25 07:45 Subject: Re: "man git-tag" inconsistent about whether you can tag non-commit objects Message-ID: <87muwo6uwq.fsf@evledraar.gmail.com> URL: https://gitlist.dev/e/87muwo6uwq.fsf%40evledraar.gmail.com In-Reply-To: ``` On Fri, May 25 2018, Junio C Hamano wrote: > "Robert P. J. Day" 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 ] [-f] [-m | -F ] [-e] >> [ | ] >> ^^^^^^^^ >> >> 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: >> >> ", >> 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... ``` ## Junio C Hamano, 2018-05-25 08:47 Subject: Re: "man git-tag" inconsistent about whether you can tag non-commit objects Message-ID: URL: https://gitlist.dev/e/xmqqh8mwnmus.fsf%40gitster-ct.c.googlers.com In-Reply-To: <87muwo6uwq.fsf@evledraar.gmail.com> ``` Ævar Arnfjörð Bjarmason 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. ``` ## Robert P. J. Day, 2018-05-25 09:40 Subject: Re: "man git-tag" inconsistent about whether you can tag non-commit objects Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.21.1805250539580.7109%40localhost.localdomain In-Reply-To: ``` On Fri, 25 May 2018, Junio C Hamano wrote: > "Robert P. J. Day" 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 ] [-f] [-m | -F ] [-e] > > [ | ] > > ^^^^^^^^ > > > > 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: > > > > ", > > 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 ======================================================================== ```