[PATCH v3 0/5] maintenance: add an 'is-needed' subcommand

[Karthik Nayak <karthik.188@gmail.com>]

Hello,

I recently raised a patch series [1] to add 'git refs optimize --required'
which checks if the reference backend can be optimized, without actually
performing the optimization.

Back then, we had decided [2] that it would be a better to broaden the
approach and add a 'is-needed' subcommand to 'git-maintenance(1)'. This
would allow users to check if maintenance was required for the
repository and users could also provide a task via the '--task' to check
if maintenance was needed for a particular task.

Ideally the subcommand will be used with the '--auto' flag which can
check the same heuristics as that used with 'git maintenance run
--auto'. Future patches can also add support for the '--schedule' flag
which can be used to check required schedule it met. However that flag
isn't added as part of this series.

This series implements that.

Commits 1-3 add the required functionality in the refs subsystem to
expose an 'optimize_required' field which can be used to check if
backends need to be optimized.
Commit 4 utilizes this within the 'git-maintenance(1)' code.
Commit 5 adds the 'is-needed' subcommand to 'git-maintenance(1)'.

This is based on top of master a99f379adf (The 27th batch, 2025-10-30)
and is dependent on the following series:

    - kn/refs-optim-cleanup
    - ps/ref-peeled-tags

Merges cleanly with `next`. I think those two topics are close to being
merged to `next` so hopefully this dependency tree doesn't get too
complicated. I'll rebase as needed to resolve conflicts.

[1]: https://lore.kernel.org/git/20251010-562-add-option-to-check-if-reference-backend-needs-repacking-v1-0-c7962be584fa@gmail.com/
[2]: https://lore.kernel.org/git/CAOLa=ZRdxm787nE4FSr2VUHDB+hW06Ggc6yUcKmeTKAb6B7YOA@mail.gmail.com/

---
Changes in v3:
- In patch 2/5 extract out code for deciding if compaction is required
  into a static function. This removes duplication of logic for deciding
  if compaction is needed.
- Link to v2: https://patch.msgid.link/20251104-562-add-sub-command-to-check-if-maintenance-is-needed-v2-0-303462a9e4ed@gmail.com

Changes in v2:
- Added more documentation for `reftable_stack_compaction_required()`.
- Fixed some typos and grammar mistakes in commit messages.
- Clarify which tasks will be run when '--task' is not used.
- Move the call to 'usage_with_options()' to be with 'parse_options()'.
- Link to v1: https://patch.msgid.link/20251031-562-add-sub-command-to-check-if-maintenance-is-needed-v1-0-a03d53e28d0e@gmail.com

---
 Documentation/git-maintenance.adoc | 13 ++++++
 builtin/gc.c                       | 85 +++++++++++++++++++++++++++++++++-----
 object.h                           |  1 -
 refs.c                             |  7 ++++
 refs.h                             |  7 ++++
 refs/debug.c                       | 13 ++++++
 refs/files-backend.c               | 11 +++++
 refs/packed-backend.c              | 13 ++++++
 refs/refs-internal.h               |  6 +++
 refs/reftable-backend.c            | 25 +++++++++++
 reftable/reftable-stack.h          | 11 +++++
 reftable/stack.c                   | 61 ++++++++++++++++++++-------
 t/t7900-maintenance.sh             | 54 +++++++++++++++++-------
 t/unit-tests/u-reftable-stack.c    | 12 +++++-
 14 files changed, 276 insertions(+), 43 deletions(-)

Karthik Nayak (5):
      reftable/stack: return stack segments directly
      reftable/stack: add function to check if optimization is required
      refs: add a `optimize_required` field to `struct ref_storage_be`
      maintenance: add checking logic in `pack_refs_condition()`
      maintenance: add 'is-needed' subcommand

Range-diff versus v2:

1:  16b447b66c = 1:  fe8977aefc reftable/stack: return stack segments directly
2:  b463d5c69d ! 2:  e73f672566 reftable/stack: add function to check if optimization is required
    @@ Commit message
         is no way for the user to check if optimization is required without
         actually performing it.
     
    -    Add and expose `reftable_stack_compaction_required()` which will allow
    -    users to check if the reftable backend can be optimized.
    +    Extract out the heuristics logic from 'reftable_stack_auto_compact()'
    +    into an internal function 'update_segment_if_compaction_required()'.
    +    Then use this to add and expose `reftable_stack_compaction_required()`
    +    which will allow users to check if the reftable backend can be
    +    optimized.
     
         Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
     
    @@ reftable/stack.c: static int stack_segments_for_compaction(struct reftable_stack
      	return 0;
      }
      
    -+int reftable_stack_compaction_required(struct reftable_stack *st,
    -+				       bool use_heuristics,
    -+				       bool *required)
    -+{
    -+	struct segment seg;
    -+	int err = 0;
    -+
    +-int reftable_stack_auto_compact(struct reftable_stack *st)
    ++static int update_segment_if_compaction_required(struct reftable_stack *st,
    ++						 struct segment *seg,
    ++						 bool use_heuristics,
    ++						 bool *required)
    + {
    +-	struct segment seg;
    + 	int err;
    + 
    +-	if (st->merged->tables_len < 2)
     +	if (st->merged->tables_len < 2) {
     +		*required = false;
     +		return 0;
    @@ reftable/stack.c: static int stack_segments_for_compaction(struct reftable_stack
     +
     +	if (!use_heuristics) {
     +		*required = true;
    -+		return 0;
    + 		return 0;
     +	}
     +
    -+	err = stack_segments_for_compaction(st, &seg);
    ++	err = stack_segments_for_compaction(st, seg);
     +	if (err)
     +		return err;
     +
    -+	*required = segment_size(&seg) > 0;
    ++	*required = segment_size(seg) > 0;
     +	return 0;
     +}
     +
    - int reftable_stack_auto_compact(struct reftable_stack *st)
    - {
    - 	struct segment seg;
    ++int reftable_stack_compaction_required(struct reftable_stack *st,
    ++				       bool use_heuristics,
    ++				       bool *required)
    ++{
    ++	struct segment seg;
    ++	return update_segment_if_compaction_required(st, &seg, use_heuristics,
    ++						     required);
    ++}
    ++
    ++int reftable_stack_auto_compact(struct reftable_stack *st)
    ++{
    ++	struct segment seg;
    ++	bool required;
    ++	int err;
    + 
    +-	err = stack_segments_for_compaction(st, &seg);
    ++	err = update_segment_if_compaction_required(st, &seg, true, &required);
    + 	if (err)
    + 		return err;
    + 
    +-	if (segment_size(&seg) > 0)
    ++	if (required)
    + 		return stack_compact_range(st, seg.start, seg.end - 1,
    + 					   NULL, STACK_COMPACT_RANGE_BEST_EFFORT);
    + 
     
      ## t/unit-tests/u-reftable-stack.c ##
     @@ t/unit-tests/u-reftable-stack.c: void test_reftable_stack__add_performs_auto_compaction(void)
3:  b9f44f61f2 = 3:  7d2428b2f9 refs: add a `optimize_required` field to `struct ref_storage_be`
4:  f94ddfdba3 = 4:  3c5f969d62 maintenance: add checking logic in `pack_refs_condition()`
5:  bc56849266 = 5:  bc2d3c26e2 maintenance: add 'is-needed' subcommand


base-commit: edd2018f5db39d68d55a7a4af42375b1a06b9406
change-id: 20251021-562-add-sub-command-to-check-if-maintenance-is-needed-01cae01b4606

Thanks
- Karthik