Am 01.03.21 um 18:50 schrieb Junio C Hamano: > René Scharfe. <l.s.r@xxxxxx> 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@xxxxxxxxx> >> Signed-off-by: René Scharfe <l.s.r@xxxxxx> >> --- >> 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
