Subject: [GSoC][PATCH v4 1/9] refs: add a generic 'optimize' API

From: Meet Soni <[email-masked]>
Date: Fri, 19 Sep 2025 13:56:39 +0530

The existing `pack-refs` API is conceptually tied to the 'files'
backend, but its behavior is generic (e.g., it triggers compaction for
reftable). This naming is confusing.

Introduce a new generic refs_optimize() API that dispatches to a
backend-specific implementation via a new 'optimize' vtable method.

This lays the architectural groundwork for different reference backends
(like 'files' and 'reftable') to provide their own storage optimization
logic, which will be called from a single, generic entry point.

Mentored-by: Patrick Steinhardt <[email-masked]>
Mentored-by: shejialuo <[email-masked]>
Signed-off-by: Meet Soni <[email-masked]>
---
 refs.c               | 5 +++++
 refs.h               | 6 ++++++
 refs/refs-internal.h | 3 +++
 3 files changed, 14 insertions(+)

diff --git a/refs.c b/refs.c
index 4ff55cf24f..191b95b4a3 100644
--- a/refs.c
+++ b/refs.c
@@ -2282,6 +2282,11 @@ int refs_pack_refs(struct ref_store *refs, struct pack_refs_opts *opts)
 	return refs->be->pack_refs(refs, opts);
 }
 
+int refs_optimize(struct ref_store *refs, struct pack_refs_opts *opts)
+{
+	return refs->be->optimize(refs, opts);
+}
+
 int peel_iterated_oid(struct repository *r, const struct object_id *base, struct object_id *peeled)
 {
 	if (current_ref_iter &&
diff --git a/refs.h b/refs.h
index f29e486e33..d28c4ef0af 100644
--- a/refs.h
+++ b/refs.h
@@ -480,6 +480,12 @@ struct pack_refs_opts {
  */
 int refs_pack_refs(struct ref_store *refs, struct pack_refs_opts *opts);
 
+/*
+ * Optimize the ref store. The exact behavior is up to the backend.
+ * For the files backend, this is equivalent to packing refs.
+ */
+int refs_optimize(struct ref_store *refs, struct pack_refs_opts *opts);
+
 /*
  * Setup reflog before using. Fill in err and return -1 on failure.
  */
diff --git a/refs/refs-internal.h b/refs/refs-internal.h
index 54c2079c12..4ef3bd75c6 100644
--- a/refs/refs-internal.h
+++ b/refs/refs-internal.h
@@ -447,6 +447,8 @@ typedef int ref_transaction_commit_fn(struct ref_store *refs,
 
 typedef int pack_refs_fn(struct ref_store *ref_store,
 			 struct pack_refs_opts *opts);
+typedef int optimize_fn(struct ref_store *ref_store,
+			struct pack_refs_opts *opts);
 typedef int rename_ref_fn(struct ref_store *ref_store,
 			  const char *oldref, const char *newref,
 			  const char *logmsg);
@@ -572,6 +574,7 @@ struct ref_storage_be {
 	ref_transaction_abort_fn *transaction_abort;
 
 	pack_refs_fn *pack_refs;
+	optimize_fn *optimize;
 	rename_ref_fn *rename_ref;
 	copy_ref_fn *copy_ref;
 
-- 
2.34.1