From: Derrick Stolee Date: Fri, 02 Aug 2024 14:32:46 GMT Subject: Re: [PATCH 0/3] git for-each-ref: is-base atom and base branches Message-ID: <27f3de89-55b2-413d-b4b4-6b35f8c4bcc9@gmail.com> In-Reply-To: On 8/1/24 7:06 PM, Junio C Hamano wrote: > "Derrick Stolee via GitGitGadget" writes: > >> Derrick Stolee (3): >> commit-reach: add get_branch_base_for_tip >> for-each-ref: add 'is-base' token >> p1500: add is-base performance tests >> >> commit-reach.c | 118 ++++++++++++++++++++++++++++++++++++ >> commit-reach.h | 17 ++++++ >> ref-filter.c | 78 +++++++++++++++++++++++- >> ref-filter.h | 15 +++++ >> t/helper/test-reach.c | 2 + >> t/perf/p1500-graph-walks.sh | 31 ++++++++++ >> t/t6600-test-reach.sh | 94 ++++++++++++++++++++++++++++ >> 7 files changed, 354 insertions(+), 1 deletion(-) > > I was expecting to see an documentation update to for-each-ref (and > probably branch and tag) so that what this new atom means. Is it > that %(is-base:) interpolates to for a ref that is an > ancestor of , and interpolates to an empty string for a ref > that is not, or something? You are absolutely right that I missed this crucial detail. I will eventually send a v2 with this oversight corrected. For now, please consider this documentation diff, and I look forward to other review comments that I can use to improve this series before sending v2. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c1dd12b93cf..5154ba3e2a7 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -264,6 +264,16 @@ ahead-behind::: commits ahead and behind, respectively, when comparing the output ref to the `` specified in the format. +is-base::: + In at most one row, `()` will appear to indicate the ref + that minimizes the number of commits in the first-parent history of + `` and not in the first-parent history of the ref. Ties + are broken by favoring the earliest ref in the list. Note that this + token will not appear if the first-parent history of `` + does not intersect the first-parent histories of the filtered refs. + This can be used as a heuristic to guess which of the filtered refs + was used as the base of the branch that produced ``. + describe[:options]:: A human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may