git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "René Scharfe." <l.s.r@web.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Eli Schwartz" <eschwartz@archlinux.org>,
	git@vger.kernel.org
Subject: Re: [PATCH 1/2] pretty: add %(describe)
Date: Tue, 2 Mar 2021 17:00:14 +0100	[thread overview]
Message-ID: <be83e397-f1c1-3483-1ad4-b71067779f6e@web.de> (raw)
In-Reply-To: <xmqq35xesqzk.fsf@gitster.c.googlers.com>

Am 01.03.21 um 18:50 schrieb Junio C Hamano:
> René Scharfe. <l.s.r@web.de> writes:
>
>> Am 17.02.21 um 01:47 schrieb Ævar Arnfjörð Bjarmason:
>>> Usually something shelling out has going for it is that even if it's
>>> slow it's at least known to be bug-free, after all we use the command
>>> like that already.
>>>
>>> I just wanted to point out this edge case, for "git describe <commits>"
>>> we do the ref list once at the beginning so our N list will be
>>> consistent within itself.
>>>
>>> Whereas one might expect "git log" to also format such a list, but due
>>> to the internal implementation the semantics are different.
>>
>> It shouldn't matter for the intended use case (git archive containing a
>> spec file with a single "$Format:%(describe)$") and I cannot imagine how
>> consistency in the face of tag changes would be useful (what application
>> would be OK with consistently outdated output, but break with partly
>> outdated descriptions).  But it makes sense to mention it in the docs.
>
> Does it?
>
> As long as the reader understands "git describe" is about measuring
> the "location" of given commits relative to the annotated tags (or
> whatever anchor points the invocation chooses to use), I would say
> that it is unlikely that the reader does not to realize the
> ramifications of changing tags in the middle.

I actually agree, but I'm biased.  The thing is: The question came up
and needed answering, so there is a chance that it might help someone
else as well.

> While it may not be incorrect per-se (hence it may "not hurt"),
> making the description longer does hurt the readers' experience.

The added sentence would look better in a smaller font, or in a
footnote. :-|

> So, I am a bit skeptical if this is a good change, but will queue
> for now anyway.
>
> Thanks.
>
>
>
>> -- >8 --
>> Subject: [PATCH] pretty: document multiple %(describe) being inconsistent
>>
>> Each %(describe) placeholder is expanded using a separate git describe
>> call.  Their outputs depend on the tags present at the time, so there's
>> no consistency guarantee.  Document that fact.
>>
>> Reported-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> Signed-off-by: René Scharfe <l.s.r@web.de>
>> ---
>>  Documentation/pretty-formats.txt | 4 +++-
>>  1 file changed, 3 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
>> index 231010e6ef..45133066e4 100644
>> --- a/Documentation/pretty-formats.txt
>> +++ b/Documentation/pretty-formats.txt
>> @@ -212,7 +212,9 @@ The placeholders are:
>>  			  linkgit:git-describe[1]; empty string for
>>  			  undescribable commits.  The `describe` string
>>  			  may be followed by a colon and zero or more
>> -			  comma-separated options.
>> +			  comma-separated options.  Descriptions can be
>> +			  inconsistent when tags are added or removed at
>> +			  the same time.
>>  +
>>  ** 'match=<pattern>': Only consider tags matching the given
>>     `glob(7)` pattern, excluding the "refs/tags/" prefix.
>> --
>> 2.30.1

  parent reply	other threads:[~2021-03-03 14:21 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-01-25  0:32 gitattributes export-subst and software versioning Eli Schwartz
2021-02-08 19:46 ` René Scharfe
2021-02-08 22:41   ` Junio C Hamano
2021-02-09  0:19   ` Eli Schwartz
2021-02-09 20:42     ` Junio C Hamano
2021-02-14 10:04       ` René Scharfe
2021-02-14 10:04     ` René Scharfe
2021-02-14 10:04 ` [PATCH 1/2] pretty: add %(describe) René Scharfe
2021-02-14 10:10   ` [PATCH 2/2] pretty: add merge and exclude options to %(describe) René Scharfe.
2021-02-17 18:31     ` Jeff King
2021-02-28 11:22       ` René Scharfe.
2021-02-28 15:41         ` Ævar Arnfjörð Bjarmason
2021-03-02 16:00           ` René Scharfe.
2021-03-06 16:18             ` René Scharfe.
     [not found]         ` <xmqqy2f6rc8f.fsf@gitster.c.googlers.com>
2021-03-02 16:00           ` René Scharfe.
     [not found]     ` <xmqqsg5uletz.fsf@gitster.g>
2021-02-28 11:22       ` René Scharfe.
2021-02-16  5:04   ` [PATCH 1/2] pretty: add %(describe) Eli Schwartz
2021-02-16 13:00   ` Ævar Arnfjörð Bjarmason
2021-02-16 17:13     ` René Scharfe.
2021-02-16 18:44     ` Junio C Hamano
2021-02-17  0:47       ` Ævar Arnfjörð Bjarmason
2021-02-28 11:22         ` René Scharfe.
     [not found]           ` <xmqq35xesqzk.fsf@gitster.c.googlers.com>
2021-03-02 16:00             ` René Scharfe. [this message]
2021-02-17  0:58   ` Ævar Arnfjörð Bjarmason
2021-02-17 18:12     ` Junio C Hamano
2021-02-28 11:22     ` René Scharfe.
     [not found]       ` <xmqq7dmqsr72.fsf@gitster.c.googlers.com>
2021-03-02 16:00         ` René Scharfe.

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=be83e397-f1c1-3483-1ad4-b71067779f6e@web.de \
    --to=l.s.r@web.de \
    --cc=avarab@gmail.com \
    --cc=eschwartz@archlinux.org \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).