for-each-ref: add 'is-base' token
The previous change introduced the get_branch_base_for_tip() method in commit-reach.c. The motivation of that change was about using a heuristic to deteremine the base branch for a source commit from a list of candidate commit tips. This change makes that algorithm visible to users via a new atom in the 'git for-each-ref' format. This change is very similar to the chang in 49abcd21da6 (for-each-ref: add ahead-behind format atom, 2023-03-20). Introduce the 'is-base:<source>' atom, which will indicate that the algorithm should be computed and the result of the algorithm is reported using an indicator of the form '(<source>)'. For example, using '%(is-base:HEAD)' would result in one line having the token '(HEAD)'. Use the sorted order of refs included in the ref filter to break ties in the algorithm's heuristic. In the previous change, the motivating examples include using an L0 trunk, long-lived L1 branches, and temporary release branches. A caller could communicate the ordered preference among these categories using the input refpecs and avoiding a different sort mechanism. This sorting behavior is tested in the test scripts. It is important to include this atom as a special case to can_do_iterative_format() to match the expectations created in bd98f9774e1 (ref-filter.c: filter & format refs in the same callback, 2023-11-14). The ahead-behind atom was one of the special cases, and this similarly requires using an algorithm across all input refs before starting the format of any single ref. In the test script, the format tokens use colons or lack whitespace to avoid Git complaining about trailing whitespace errors. Signed-off-by: Derrick Stolee <stolee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Derrick Stolee committed
Aug 14, 2024 at 10:31 UTC
9c1732ca113d565e431b303911fcf66bfa1f8f56
5 files changed
+202
-1
Documentation/git-for-each-ref.txt
+42
@@ -264,6 +264,48 @@ ahead-behind:<committish>::
264
commits ahead and behind, respectively, when comparing the output
265
ref to the `<committish>` specified in the format.
266
267
+is-base:<committish>::
268
+ In at most one row, `(<committish>)` will appear to indicate the ref
269
+ that is most likely the ref used as a starting point for the branch
270
+ that produced `<committish>`. This choice is made using a heuristic:
271
+ choose the ref that minimizes the number of commits in the
272
+ first-parent history of `<committish>` and not in the first-parent
273
+ history of the ref.
274
++
275
+For example, consider the following figure of first-parent histories of
276
+several refs:
277
++
278
+----
279
+*--*--*--*--*--* refs/heads/A
280
+\
281
+ \
282
+ *--*--*--* refs/heads/B
283
+ \ \
284
+ \ \
285
+ * * refs/heads/C
286
+ \
287
+ \
288
+ *--* refs/heads/D
289
+----
290
++
291
+Here, if `A`, `B`, and `C` are the filtered references, and the format
292
+string is `%(refname):%(is-base:D)`, then the output would be
293
++
294
+----
295
+refs/heads/A:
296
+refs/heads/B:(D)
297
+refs/heads/C:
298
+----
299
++
300
+This is because the first-parent history of `D` has its earliest
301
+intersection with the first-parent histories of the filtered refs at a
302
+common first-parent ancestor of `B` and `C` and ties are broken by the
303
+earliest ref in the sorted order.
304
++
305
+Note that this token will not appear if the first-parent history of
306
+`<committish>` does not intersect the first-parent histories of the
307
+filtered refs.
308
+
309
describe[:options]::
310
A human-readable name, like linkgit:git-describe[1];
311
empty string for undescribable commits. The `describe` string may
ref-filter.c
+76
-1
@@ -169,6 +169,7 @@ enum atom_type {
169
ATOM_ELSE,
170
ATOM_REST,
171
ATOM_AHEADBEHIND,
172
+ ATOM_ISBASE,
173
};
174
175
/*
@@ -891,6 +892,23 @@ static int ahead_behind_atom_parser(struct ref_format *format,
892
return 0;
893
}
894
895
+static int is_base_atom_parser(struct ref_format *format,
896
+ struct used_atom *atom UNUSED,
897
+ const char *arg, struct strbuf *err)
898
+{
899
+ struct string_list_item *item;
900
+
901
+ if (!arg)
902
+ return strbuf_addf_ret(err, -1, _("expected format: %%(is-base:<committish>)"));
903
+
904
+ item = string_list_append(&format->is_base_tips, arg);
905
+ item->util = lookup_commit_reference_by_name(arg);
906
+ if (!item->util)
907
+ die("failed to find '%s'", arg);
908
+
909
+ return 0;
910
+}
911
+
912
static int head_atom_parser(struct ref_format *format UNUSED,
913
struct used_atom *atom,
914
const char *arg, struct strbuf *err)
@@ -956,6 +974,7 @@ static struct {
974
[ATOM_ELSE] = { "else", SOURCE_NONE },
975
[ATOM_REST] = { "rest", SOURCE_NONE, FIELD_STR, rest_atom_parser },
976
[ATOM_AHEADBEHIND] = { "ahead-behind", SOURCE_OTHER, FIELD_STR, ahead_behind_atom_parser },
977
+ [ATOM_ISBASE] = { "is-base", SOURCE_OTHER, FIELD_STR, is_base_atom_parser },
978
/*
979
* Please update $__git_ref_fieldlist in git-completion.bash
980
* when you add new atoms
@@ -2340,6 +2359,7 @@ static int populate_value(struct ref_array_item *ref, struct strbuf *err)
2359
int i;
2360
struct object_info empty = OBJECT_INFO_INIT;
2361
int ahead_behind_atoms = 0;
2362
+ int is_base_atoms = 0;
2363
2364
CALLOC_ARRAY(ref->value, used_atom_cnt);
2365
@@ -2483,6 +2503,15 @@ static int populate_value(struct ref_array_item *ref, struct strbuf *err)
2503
v->s = xstrdup("");
2504
}
2505
continue;
2506
+ } else if (atom_type == ATOM_ISBASE) {
2507
+ if (ref->is_base && ref->is_base[is_base_atoms]) {
2508
+ v->s = xstrfmt("(%s)", ref->is_base[is_base_atoms]);
2509
+ free(ref->is_base[is_base_atoms]);
2510
+ } else {
2511
+ v->s = xstrdup("");
2512
+ }
2513
+ is_base_atoms++;
2514
+ continue;
2515
} else
2516
continue;
2517
@@ -2888,6 +2917,7 @@ static void free_array_item(struct ref_array_item *item)
2917
free(item->value);
2918
}
2919
free(item->counts);
2920
+ free(item->is_base);
2921
free(item);
2922
}
2923
@@ -3052,6 +3082,49 @@ void filter_ahead_behind(struct repository *r,
3082
free(commits);
3083
}
3084
3085
+void filter_is_base(struct repository *r,
3086
+ struct ref_format *format,
3087
+ struct ref_array *array)
3088
+{
3089
+ struct commit **bases;
3090
+ size_t bases_nr = 0;
3091
+ struct ref_array_item **back_index;
3092
+
3093
+ if (!format->is_base_tips.nr || !array->nr)
3094
+ return;
3095
+
3096
+ CALLOC_ARRAY(back_index, array->nr);
3097
+ CALLOC_ARRAY(bases, array->nr);
3098
+
3099
+ for (size_t i = 0; i < array->nr; i++) {
3100
+ const char *name = array->items[i]->refname;
3101
+ struct commit *c = lookup_commit_reference_by_name_gently(name, 1);
3102
+
3103
+ CALLOC_ARRAY(array->items[i]->is_base, format->is_base_tips.nr);
3104
+
3105
+ if (!c)
3106
+ continue;
3107
+
3108
+ back_index[bases_nr] = array->items[i];
3109
+ bases[bases_nr] = c;
3110
+ bases_nr++;
3111
+ }
3112
+
3113
+ for (size_t i = 0; i < format->is_base_tips.nr; i++) {
3114
+ struct commit *tip = format->is_base_tips.items[i].util;
3115
+ int base_index = get_branch_base_for_tip(r, tip, bases, bases_nr);
3116
+
3117
+ if (base_index < 0)
3118
+ continue;
3119
+
3120
+ /* Store the string for use in output later. */
3121
+ back_index[base_index]->is_base[i] = xstrdup(format->is_base_tips.items[i].string);
3122
+ }
3123
+
3124
+ free(back_index);
3125
+ free(bases);
3126
+}
3127
+
3128
static int do_filter_refs(struct ref_filter *filter, unsigned int type, each_ref_fn fn, void *cb_data)
3129
{
3130
int ret = 0;
@@ -3145,7 +3218,8 @@ static inline int can_do_iterative_format(struct ref_filter *filter,
3218
return !(filter->reachable_from ||
3219
filter->unreachable_from ||
3220
sorting ||
3148
- format->bases.nr);
3221
+ format->bases.nr ||
3222
+ format->is_base_tips.nr);
3223
}
3224
3225
void filter_and_format_refs(struct ref_filter *filter, unsigned int type,
@@ -3169,6 +3243,7 @@ void filter_and_format_refs(struct ref_filter *filter, unsigned int type,
3243
struct ref_array array = { 0 };
3244
filter_refs(&array, filter, type);
3245
filter_ahead_behind(the_repository, format, &array);
3246
+ filter_is_base(the_repository, format, &array);
3247
ref_array_sort(sorting, &array);
3248
print_formatted_ref_array(&array, format);
3249
ref_array_clear(&array);
ref-filter.h
+15
@@ -48,6 +48,7 @@ struct ref_array_item {
48
struct commit *commit;
49
struct atom_value *value;
50
struct ahead_behind_count **counts;
51
+ char **is_base;
52
53
char refname[FLEX_ARRAY];
54
};
@@ -101,6 +102,9 @@ struct ref_format {
102
/* List of bases for ahead-behind counts. */
103
struct string_list bases;
104
105
+ /* List of bases for is-base indicators. */
106
+ struct string_list is_base_tips;
107
+
108
struct {
109
int max_count;
110
int omit_empty;
@@ -114,6 +118,7 @@ struct ref_format {
118
#define REF_FORMAT_INIT { \
119
.use_color = -1, \
120
.bases = STRING_LIST_INIT_DUP, \
121
+ .is_base_tips = STRING_LIST_INIT_DUP, \
122
}
123
124
/* Macros for checking --merged and --no-merged options */
@@ -203,6 +208,16 @@ void filter_ahead_behind(struct repository *r,
208
struct ref_format *format,
209
struct ref_array *array);
210
211
+/*
212
+ * If the provided format includes is-base atoms, then compute the base checks
213
+ * for those tips against all refs.
214
+ *
215
+ * If this is not called, then any is-base atoms will be blank.
216
+ */
217
+void filter_is_base(struct repository *r,
218
+ struct ref_format *format,
219
+ struct ref_array *array);
220
+
221
void ref_filter_init(struct ref_filter *filter);
222
void ref_filter_clear(struct ref_filter *filter);
223
t/t6300-for-each-ref.sh
+9
@@ -1907,6 +1907,15 @@ test_expect_success 'git for-each-ref with nested tags' '
1907
test_cmp expect actual
1908
'
1909
1910
+test_expect_success 'is-base atom with non-commits' '
1911
+ git for-each-ref --format="%(is-base:HEAD) %(refname)" >out 2>err &&
1912
+ grep "(HEAD) refs/heads/main" out &&
1913
+
1914
+ test_line_count = 2 err &&
1915
+ grep "error: object .* is a commit, not a blob" err &&
1916
+ grep "error: bad tag pointer to" err
1917
+'
1918
+
1919
GRADE_FORMAT="%(signature:grade)%0a%(signature:key)%0a%(signature:signer)%0a%(signature:fingerprint)%0a%(signature:primarykeyfingerprint)"
1920
TRUSTLEVEL_FORMAT="%(signature:trustlevel)%0a%(signature:key)%0a%(signature:signer)%0a%(signature:fingerprint)%0a%(signature:primarykeyfingerprint)"
1921
t/t6600-test-reach.sh
+60
@@ -673,4 +673,64 @@ test_expect_success 'get_branch_base_for_tip: all reach tip' '
673
test_all_modes get_branch_base_for_tip
674
'
675
676
+test_expect_success 'for-each-ref is-base: none reach' '
677
+ cat >input <<-\EOF &&
678
+ refs/heads/commit-1-1
679
+ refs/heads/commit-4-2
680
+ refs/heads/commit-4-4
681
+ refs/heads/commit-8-4
682
+ EOF
683
+ cat >expect <<-\EOF &&
684
+ refs/heads/commit-1-1:
685
+ refs/heads/commit-4-2:(commit-2-3)
686
+ refs/heads/commit-4-4:
687
+ refs/heads/commit-8-4:
688
+ EOF
689
+ run_all_modes git for-each-ref \
690
+ --format="%(refname):%(is-base:commit-2-3)" --stdin
691
+'
692
+
693
+test_expect_success 'for-each-ref is-base: all reach' '
694
+ cat >input <<-\EOF &&
695
+ refs/heads/commit-4-2
696
+ refs/heads/commit-5-1
697
+ EOF
698
+ cat >expect <<-\EOF &&
699
+ refs/heads/commit-4-2:(commit-4-1)
700
+ refs/heads/commit-5-1:
701
+ EOF
702
+ run_all_modes git for-each-ref \
703
+ --format="%(refname):%(is-base:commit-4-1)" --stdin
704
+'
705
+
706
+test_expect_success 'for-each-ref is-base: equal to tip' '
707
+ cat >input <<-\EOF &&
708
+ refs/heads/commit-4-2
709
+ refs/heads/commit-5-1
710
+ EOF
711
+ cat >expect <<-\EOF &&
712
+ refs/heads/commit-4-2:(commit-4-2)
713
+ refs/heads/commit-5-1:
714
+ EOF
715
+ run_all_modes git for-each-ref \
716
+ --format="%(refname):%(is-base:commit-4-2)" --stdin
717
+'
718
+
719
+test_expect_success 'for-each-ref is-base:multiple' '
720
+ cat >input <<-\EOF &&
721
+ refs/heads/commit-1-1
722
+ refs/heads/commit-4-2
723
+ refs/heads/commit-4-4
724
+ refs/heads/commit-8-4
725
+ EOF
726
+ cat >expect <<-\EOF &&
727
+ refs/heads/commit-1-1[-]
728
+ refs/heads/commit-4-2[(commit-2-3)-]
729
+ refs/heads/commit-4-4[-]
730
+ refs/heads/commit-8-4[-(commit-6-5)]
731
+ EOF
732
+ run_all_modes git for-each-ref \
733
+ --format="%(refname)[%(is-base:commit-2-3)-%(is-base:commit-6-5)]" --stdin
734
+'
735
+
736
test_done