From: Karthik Nayak Date: Sat, 08 Nov 2025 21:51:52 GMT Subject: [PATCH v4 0/5] maintenance: add an 'is-needed' subcommand Message-ID: <20251108-562-add-sub-command-to-check-if-maintenance-is-needed-v4-0-a90f229b6023@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 v4: - In `update_segment_if_compaction_required()` change the argument name from `use_heuristics` to `use_geometric` since we only have one heuristic currently and this is much clearer to understand. - There were a lot of discussion on how to return a bool variable when the function has a return type of int. We discussed both '!!required', and 'required != true'. I'm going to punt this discussion keeping it simple as 'return required' as in my first version, since even Junio expressed his thoughts in favor of it. - Add a TODO for improvements to the flow when running `git maintenance is-needed` without the `--auto` flag. - Link to v3: https://patch.msgid.link/20251106-562-add-sub-command-to-check-if-maintenance-is-needed-v3-0-d611a2a95cf5@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 | 93 ++++++++++++++++++++++++++++++++++---- 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, 284 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 v3: 1: 48c877bbc4 = 1: 4026aad0e2 reftable/stack: return stack segments directly 2: b2c0da304b ! 2: ed2b307572 reftable/stack: add function to check if optimization is required @@ reftable/stack.c: static int stack_segments_for_compaction(struct reftable_stack -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 use_geometric, + bool *required) { - struct segment seg; @@ reftable/stack.c: static int stack_segments_for_compaction(struct reftable_stack + return 0; + } + -+ if (!use_heuristics) { ++ if (!use_geometric) { + *required = true; return 0; + } 3: aec4861598 = 3: 4ac6fe6346 refs: add a `optimize_required` field to `struct ref_storage_be` 4: 36d9bfbfe0 ! 4: e239f9d1d1 maintenance: add checking logic in `pack_refs_condition()` @@ 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 == true; ++ return required; } static int maintenance_task_pack_refs(struct maintenance_run_opts *opts, 5: 2fc7dcb38c ! 5: 2457e5ce0e maintenance: add 'is-needed' subcommand @@ Documentation/git-maintenance.adoc: The `unregister` subcommand will report an e + Exits with a 0 status code if maintenance needs to be run, 1 otherwise. + Ideally used with the '--auto' flag. ++ -+If one or more `--task` options are specified, then those tasks are checked ++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. @@ builtin/gc.c: static int maintenance_stop(int argc, const char **argv, const cha + } + } + } else { -+ /* When not using --auto, we should always require maintenance. */ ++ /* ++ * When not using --auto we always require maintenance right now. ++ * ++ * TODO: this certainly is too eager, as some maintenance tasks may ++ * decide to not do anything because the data structures are already ++ * fully optimized. We may eventually want to extend the auto ++ * condition to also cover non-auto runs so that we can detect such ++ * cases. ++ */ + is_needed = true; + } + base-commit: edd2018f5db39d68d55a7a4af42375b1a06b9406 change-id: 20251021-562-add-sub-command-to-check-if-maintenance-is-needed-01cae01b4606 Thanks - Karthik