[PATCH v2 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 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                   | 48 ++++++++++++++++-----
 t/t7900-maintenance.sh             | 54 +++++++++++++++++-------
 t/unit-tests/u-reftable-stack.c    | 12 +++++-
 14 files changed, 266 insertions(+), 40 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 v1:

1:  e5e6eedfbe = 1:  5431fe40ef reftable/stack: return stack segments directly
2:  6fac9e5eb5 ! 2:  248882aad6 reftable/stack: add function to check if optimization is required
    @@ Metadata
      ## Commit message ##
         reftable/stack: add function to check if optimization is required
     
    -    The reftable backend, performs auto-compaction as part of its regular
    +    The reftable backend performs auto-compaction as part of its regular
         flow, which is required to keep the number of tables part of a stack at
         bay. This allows it to stay optimized.
     
    @@ reftable/reftable-stack.h: struct reftable_log_expiry_config {
      int reftable_stack_compact_all(struct reftable_stack *st,
      			       struct reftable_log_expiry_config *config);
      
    -+/* Check if compaction is required. */
    ++/*
    ++ * Check if compaction is required.
    ++ *
    ++ * When `use_heuristics` is false, check if all tables can be compacted to a
    ++ * single table. If true, use heuristics to determine if the tables need to be
    ++ * compacted to maintain geometric progression.
    ++ */
     +int reftable_stack_compaction_required(struct reftable_stack *st,
     +				       bool use_heuristics,
     +				       bool *required);
3:  2ec39102a5 = 3:  e98c2c2e3e refs: add a `optimize_required` field to `struct ref_storage_be`
4:  c246efdc4a ! 4:  9b7fa79c8c maintenance: add checking logic in `pack_refs_condition()`
    @@ Metadata
      ## Commit message ##
         maintenance: add checking logic in `pack_refs_condition()`
     
    -    The 'git-maintenance(1)' command support an '--auto' flag. Usage of the
    +    The 'git-maintenance(1)' command supports an '--auto' flag. Usage of the
         flag ensures to run maintenance tasks only if certain thresholds are
         met. The heuristic is defined on a task level, wherein each task defines
    -    a 'auto_condition', which states if the task should be run.
    +    an 'auto_condition', which states if the task should be run.
     
         The 'pack-refs' task is hard-coded to return 1 as:
         1. There was never a way to check if the reference backend needs to be
    @@ Commit message
     
         This allows us to add a 'git maintenance is-needed' subcommand which can
         notify the user if maintenance is needed without actually performing the
    -    optimization, without this change, the reference backend would always
    +    optimization. Without this change, the reference backend would always
         state that optimization is needed.
     
         Since we import 'revision.h', we need to remove the definition for
    @@ builtin/gc.c: static void maintenance_run_opts_release(struct maintenance_run_op
     +	};
     +	bool required;
     +
    -+	// Check for all refs, similar to 'git refs optimize --all'.
    ++	/* Check for all refs, similar to 'git refs optimize --all'. */
     +	string_list_append(optimize_opts.includes, "*");
     +
     +	if (refs_optimize_required(get_main_ref_store(the_repository),
    @@ builtin/gc.c: static void maintenance_run_opts_release(struct maintenance_run_op
     +	clear_ref_exclusions(&excludes);
     +	string_list_clear(&included_refs, 0);
     +
    -+	return required;
    ++	return required == true;
      }
      
      static int maintenance_task_pack_refs(struct maintenance_run_opts *opts,
5:  64c15c1319 ! 5:  ed3658528b maintenance: add 'is-needed' subcommand
    @@ Documentation/git-maintenance.adoc: The `unregister` subcommand will report an e
     +is-needed::
     +    Check whether maintenance needs to be run without actually running it.
     +    Exits with a 0 status code if maintenance needs to be run, 1 otherwise.
    -+    Can be used along with `--task`. Ideally should be used with '--auto'.
    ++    Ideally used with the '--auto' flag.
    +++
    ++If one or more `--task` options	are specified, then those tasks are checked
    ++in that order. Otherwise, the tasks are determined by which
    ++`maintenance.<task>.enabled` config options are true. By default, only
    ++`maintenance.gc.enabled` is true.
     +
      TASKS
      -----
    @@ builtin/gc.c: static int maintenance_stop(int argc, const char **argv, const cha
     +	argc = parse_options(argc, argv, prefix, options,
     +			     builtin_maintenance_is_needed_usage,
     +			     PARSE_OPT_STOP_AT_NON_OPTION);
    ++	if (argc)
    ++		usage_with_options(builtin_maintenance_is_needed_usage, options);
     +
     +	gc_config(&cfg);
     +	initialize_task_config(&opts, &selected_tasks);
     +
    -+	if (argc)
    -+		usage_with_options(builtin_maintenance_is_needed_usage, options);
    -+
     +	if (opts.auto_flag) {
     +		for (size_t i = 0; i < opts.tasks_nr; i++) {
     +			if (tasks[opts.tasks[i]].auto_condition &&


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

Thanks
- Karthik