From: Karthik Nayak Date: Tue, 04 Nov 2025 08:43:55 GMT Subject: [PATCH v2 0/5] maintenance: add an 'is-needed' subcommand Message-ID: <20251104-562-add-sub-command-to-check-if-maintenance-is-needed-v2-0-303462a9e4ed@gmail.com> In-Reply-To: <20251031-562-add-sub-command-to-check-if-maintenance-is-needed-v1-0-a03d53e28d0e@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..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