Re: [PATCH 1/2] pretty: add %(describe)

Am 01.03.21 um 18:50 schrieb Junio C Hamano:

René Scharfe. [off-list ref] writes:

quoted

Am 17.02.21 um 01:47 schrieb Ævar Arnfjörð Bjarmason:

quoted

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.

quoted

-- >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 <redacted>
Signed-off-by: René Scharfe <redacted>
---
 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