Re: [PATCH 0/3] git for-each-ref: is-base atom and base branches

On 8/1/24 7:06 PM, Junio C Hamano wrote:

"Derrick Stolee via GitGitGadget" [off-list ref] writes:

quoted

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:<commit>) interpolates to <commit> for a ref that is an
ancestor of <commit>, 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:<committish>::
  	commits ahead and behind, respectively, when comparing the output
  	ref to the `<committish>` specified in the format.

+is-base:<committish>::
+	In at most one row, `(<committish>)` will appear to indicate the ref
+	that minimizes the number of commits in the first-parent history of
+	`<committish>` 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 `<committish>`
+	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 `<committish>`.
+
  describe[:options]::
  	A human-readable name, like linkgit:git-describe[1];
  	empty string for undescribable commits. The `describe` string may