| Message ID | pull.1768.git.1722550226.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | git for-each-ref: is-base atom and base branches | expand |
"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> 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:<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? Thanks.
On 8/1/24 7:06 PM, Junio C Hamano wrote: > "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> 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:<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
Derrick Stolee <stolee@gmail.com> writes: > 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>`. > + OK. Knowing what definition you used is crucial when reading the implementation, as we cannot tell what you wanted to implement without it ;-) Thanks.
Junio C Hamano <gitster@pobox.com> writes: >> +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. This was a bit too dense for me to grok. So if I have a <commit> that is at the tip of a branch B forked from 'master', and then 'master' advanced by a lot since the branch forked, the number this is minimizing for 'master' is the commits on the branch B, but when showing 'maint', then even though the branch B may have the tip of 'maint' as an ancestor, the number for 'maint' would be a lot more than the number for 'master'. If there were another branch C that was forked from 'master' and shared some (or all) commits that are near the tip of branch B, e.g. ---o---o---o---o---o---o---o---o---o 'master' \ o---o---o---o 'C' \ o---o---o---o 'B' then the number may be even smaller for branch 'C' than 'master'. And for at most one ref, %(is-base:<commit>) becomes "(<commit>)"; for all other refs, it becomes an empty string. OK. > OK. Knowing what definition you used is crucial when reading the > implementation, as we cannot tell what you wanted to implement > without it ;-) > > Thanks.