git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 2/7] setup: introduce object storage extension

From
Patrick Steinhardt <ps@pks.im>
Date
Oct 21, 2026, 05:39 UTC
Message-ID
<20261021-b4-pks-odb-extension-v2-2-8cf11b65eda8@pks.im>
In-Reply-To
<20261021-b4-pks-odb-extension-v2-0-8cf11b65eda8@pks.im>

Introduce a new "extensions.objectStorage" extension that allows the user to configure the primary object database source of a repository. The value is a URI in the format "<schema>[://<payload>]", mirroring the format used by "extensions.refStorage":

  - The schema identifies the backend that shall be used. For now the
    only supported schema is "files", which is the existing object
    database backed by loose objects and packfiles.
  - The payload can be passed to configure the backend, and its
    interpretation is backend-specific. For the "files" backend, it
    allows you to configure a different location for the ".git/objects"
    directory.
Eventually, this mechanism will be used to support alternative backends.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/config/extensions.adoc     | 23 ++++++++++++++++
 Documentation/object-storage-format.adoc |  6 +++++
 odb.c                                    |  2 +-
 odb/source-files.c                       |  7 +++++
 odb/source-files.h                       |  1 +
 odb/source.c                             | 45 +++++++++++++++++++++++++++++++-
 odb/source.h                             | 12 ++++++++-
 repository.c                             | 11 ++++++++
 repository.h                             |  8 ++++++
 setup.c                                  | 13 +++++++++
 setup.h                                  |  1 +
 t/t0001-init.sh                          | 30 +++++++++++++++++++++
 t/unit-tests/u-odb-inmemory.c            |  1 +
 13 files changed, 157 insertions(+), 3 deletions(-)
diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc
index be6678bb5b..4f3a66a454 100644
--- a/Documentation/config/extensions.adoc
+++ b/Documentation/config/extensions.adoc
@@ -56,6 +56,29 @@ preciousObjects:::
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
+objectStorage:::
+	Specify the object storage format and a corresponding payload. The
+	value can be either a format name or a URI:
++
+--
+* A format name alone (e.g., `files`).
+
+* A URI format `<format>://<payload>` explicitly specifies both the
+  format and payload (e.g., `files:///foo/bar`).
+
+Supported formats are:
+
+include::../object-storage-format.adoc[]
+
+--
++
+Note that this setting should only be set by linkgit:git-init[1] or
+linkgit:git-clone[1]. Trying to change it after initialization will make
+preexisting objects inaccessible.
++
+NOTE: This extension is still considered EXPERIMENTAL and may be subject to
+change.
+
 refStorage:::
 	Specify the ref storage format and a corresponding payload. The value
 	can be either a format name or a URI:
diff --git a/Documentation/object-storage-format.adoc b/Documentation/object-storage-format.adoc
new file mode 100644
index 0000000000..4c4aef6dda
--- /dev/null
+++ b/Documentation/object-storage-format.adoc
@@ -0,0 +1,6 @@
+`files[://<path>]`;; for loose objects and packfiles. This is the default.
++
+The optional payload can be passed to specify an alternative filesystem path
+where the objects will be stored. Relative paths are resolved relative to the
+`$GIT_COMMON_DIR`. Defaults to `$GIT_COMMON_DIR/objects` when no payload is
+provided. The payload is ignored when `GIT_OBJECT_DIRECTORY` is set.
diff --git a/odb.c b/odb.c
index 98c5c862f5..6c07b3b671 100644
--- a/odb.c
+++ b/odb.c
@@ -757,7 +757,7 @@ struct object_database *odb_new(struct repository *repo,
 	o->repo = repo;
 	pthread_mutex_init(&o->replace_mutex, NULL);
 
-	o->source = odb_source_new(o, flags);
+	o->source = odb_source_new(o, repo->object_storage_format, flags);
 	o->inmemory_objects = &odb_source_inmemory_new(o)->base;
 
 	return o;
diff --git a/odb/source-files.c b/odb/source-files.c
index 455f409db0..4a7cbbfd9b 100644
--- a/odb/source-files.c
+++ b/odb/source-files.c
@@ -1235,6 +1235,7 @@ struct odb_files_dir *odb_source_files_find_dir(struct object_database *odb, con
 }
 
 struct odb_source_files *odb_source_files_new(struct object_database *odb,
+					      const char *payload,
 					      enum odb_new_flags flags)
 {
 	struct odb_source_files *files;
@@ -1245,6 +1246,12 @@ struct odb_source_files *odb_source_files_new(struct object_database *odb,
 		object_dir = xstrdup_or_null(getenv(DB_ENVIRONMENT));
 		alternates = xstrdup_or_null(getenv(ALTERNATE_DB_ENVIRONMENT));
 	}
+	if (!object_dir && payload) {
+		if (is_absolute_path(payload))
+			object_dir = xstrdup(payload);
+		else
+			object_dir = xstrfmt("%s/%s", odb->repo->commondir, payload);
+	}
 	if (!object_dir)
 		object_dir = xstrfmt("%s/objects", odb->repo->commondir);
 
diff --git a/odb/source-files.h b/odb/source-files.h
index 837e890304..71e8db84ff 100644
--- a/odb/source-files.h
+++ b/odb/source-files.h
@@ -70,6 +70,7 @@ struct odb_source_files {
 
 /* Allocate and initialize a new object source. */
 struct odb_source_files *odb_source_files_new(struct object_database *odb,
+					      const char *payload,
 					      enum odb_new_flags flags);
 
 /*
diff --git a/odb/source.c b/odb/source.c
index b25ef14df8..7917ecc990 100644
--- a/odb/source.c
+++ b/odb/source.c
@@ -1,4 +1,5 @@
 #include "git-compat-util.h"
+#include "gettext.h"
 #include "object-file.h"
 #include "odb/source-files.h"
 #include "odb/source.h"
@@ -23,10 +24,52 @@ const char *odb_source_type_to_name(enum odb_source_type type)
 	return name;
 }
 
+static enum odb_source_type odb_source_type_by_name(const char *name)
+{
+	if (!strcmp(name, "files"))
+		return ODB_SOURCE_FILES;
+	return ODB_SOURCE_UNKNOWN;
+}
+
+enum odb_source_type odb_source_type_by_uri(const char *uri, char **payload)
+{
+	enum odb_source_type type;
+	const char *schema_end;
+	char *name;
+
+	schema_end = strstr(uri, "://");
+	if (!schema_end) {
+		name = xstrdup(uri);
+		if (payload)
+			*payload = NULL;
+	} else {
+		name = xstrndup(uri, schema_end - uri);
+		if (payload)
+			*payload = *(schema_end + 3) ? xstrdup(schema_end + 3) : NULL;
+	}
+
+	type = odb_source_type_by_name(name);
+	free(name);
+	return type;
+}
+
 struct odb_source *odb_source_new(struct object_database *odb,
+				  const char *object_storage_format,
 				  enum odb_new_flags flags)
 {
-	return &odb_source_files_new(odb, flags)->base;
+	struct odb_source *source;
+	char *payload = NULL;
+
+	switch (odb_source_type_by_uri(object_storage_format, &payload)) {
+	case ODB_SOURCE_FILES:
+		source = &odb_source_files_new(odb, payload, flags)->base;
+		break;
+	default:
+		die(_("unknown object storage format '%s'"), object_storage_format);
+	}
+
+	free(payload);
+	return source;
 }
 
 void odb_source_init(struct odb_source *source,
diff --git a/odb/source.h b/odb/source.h
index 1867347dfc..c194b3254b 100644
--- a/odb/source.h
+++ b/odb/source.h
@@ -32,6 +32,14 @@ enum odb_source_type {
  */
 const char *odb_source_type_to_name(enum odb_source_type type);
 
+/*
+ * Parse the given URI in the format "<schema>[://<payload>]" and return the
+ * source type identified by the schema. If `payload` is non-NULL it will be
+ * set to a newly allocated copy of the payload, or NULL if the URI has no or
+ * an empty payload. Returns `ODB_SOURCE_UNKNOWN` for unknown schemas.
+ */
+enum odb_source_type odb_source_type_by_uri(const char *uri, char **payload);
+
 struct object_id;
 struct odb_stream;
 struct strbuf;
@@ -304,9 +312,11 @@ struct odb_source {
 
 /*
  * Allocate and initialize a new source for the given object database. The path
- * of the source is derived from repository paths.
+ * of the source is derived from repository paths or from the object storage
+ * format.
  */
 struct odb_source *odb_source_new(struct object_database *odb,
+				  const char *object_storage_format,
 				  enum odb_new_flags flags);
 
 /*
diff --git a/repository.c b/repository.c
index 970d181828..5b1f1460e0 100644
--- a/repository.c
+++ b/repository.c
@@ -217,6 +217,16 @@ void repo_set_ref_storage_format(struct repository *repo,
 	repo->ref_storage_payload = xstrdup_or_null(payload);
 }
 
+void repo_set_object_storage_format(struct repository *repo,
+				    const char *uri)
+{
+	free(repo->object_storage_format);
+	if (uri)
+		repo->object_storage_format = xstrdup(uri);
+	else
+		repo->object_storage_format = xstrdup("files");
+}
+
 /*
  * Attempt to resolve and set the provided 'gitdir' for repository 'repo'.
  * Return 0 upon success and a non-zero value upon failure.
@@ -382,6 +392,7 @@ void repo_clear(struct repository *repo)
 	free(repo->worktree);
 	free(repo->submodule_prefix);
 	free(repo->ref_storage_payload);
+	free(repo->object_storage_format);
 
 	odb_free(repo->objects);
 
diff --git a/repository.h b/repository.h
index 2a348012e8..e9a3a7f18b 100644
--- a/repository.h
+++ b/repository.h
@@ -178,6 +178,12 @@ struct repository {
 	 */
 	char *ref_storage_payload;
 
+	/*
+	 * The object storage URI in the format "<schema>[://<payload>]", as
+	 * configured via "extensions.objectStorage".
+	 */
+	char *object_storage_format;
+
 	/* A unique-id for tracing purposes. */
 	int trace2_repo_id;
 
@@ -255,6 +261,8 @@ void repo_set_compat_hash_algo(struct repository *repo, uint32_t compat_algo);
 void repo_set_ref_storage_format(struct repository *repo,
 				 enum ref_storage_format format,
 				 const char *payload);
+void repo_set_object_storage_format(struct repository *repo,
+				    const char *uri);
 void initialize_repository(struct repository *repo);
 RESULT_MUST_BE_USED
 int repo_init(struct repository *r, const char *gitdir, const char *worktree);
diff --git a/setup.c b/setup.c
index 3ee19f3e3c..499b5bbe3c 100644
--- a/setup.c
+++ b/setup.c
@@ -9,6 +9,7 @@
 #include "hex.h"
 #include "object-file.h"
 #include "object-name.h"
+#include "odb/source.h"
 #include "refs.h"
 #include "repository.h"
 #include "config.h"
@@ -687,6 +688,15 @@ static enum extension_result handle_extension(const char *var,
 				     "extensions.refstorage", value);
 		data->ref_storage_format = format;
 		return EXTENSION_OK;
+	} else if (!strcmp(ext, "objectstorage")) {
+		if (!value)
+			return config_error_nonbool(var);
+		if (odb_source_type_by_uri(value, NULL) == ODB_SOURCE_UNKNOWN)
+			return error(_("invalid value for '%s': '%s'"),
+				     "extensions.objectstorage", value);
+		free(data->object_storage);
+		data->object_storage = xstrdup(value);
+		return EXTENSION_OK;
 	} else if (!strcmp(ext, "relativeworktrees")) {
 		data->relative_worktrees = git_config_bool(var, value);
 		return EXTENSION_OK;
@@ -694,6 +704,7 @@ static enum extension_result handle_extension(const char *var,
 		data->submodule_path_cfg = git_config_bool(var, value);
 		return EXTENSION_OK;
 	}
+
 	return EXTENSION_UNKNOWN;
 }
 
@@ -864,6 +875,7 @@ void clear_repository_format(struct repository_format *format)
 	free(format->work_tree);
 	free(format->partial_clone);
 	free(format->ref_storage_payload);
+	free(format->object_storage);
 	init_repository_format(format);
 }
 
@@ -1786,6 +1798,7 @@ int apply_repository_format(struct repository *repo,
 	repo_set_ref_storage_format(repo,
 				    format->ref_storage_format,
 				    format->ref_storage_payload);
+	repo_set_object_storage_format(repo, format->object_storage);
 	repo->repository_format_worktree_config =
 		format->worktree_config;
 	repo->repository_format_submodule_path_cfg =
diff --git a/setup.h b/setup.h
index 7a3efe5e48..9145aacc5f 100644
--- a/setup.h
+++ b/setup.h
@@ -192,6 +192,7 @@ struct repository_format {
 	char *ref_storage_payload;
 	int sparse_index;
 	char *work_tree;
+	char *object_storage;
 	struct string_list unknown_extensions;
 	struct string_list v1_only_extensions;
 };
diff --git a/t/t0001-init.sh b/t/t0001-init.sh
index f1d227f271..c7c464d3a2 100755
--- a/t/t0001-init.sh
+++ b/t/t0001-init.sh
@@ -839,6 +839,36 @@ test_expect_success 'init with --ref-storage-format=garbage' '
 	test_cmp expect err
 '
 
+test_expect_success DEFAULT_REPO_FORMAT 'extensions.objectStorage is not allowed with repo version 0' '
+	test_when_finished "rm -rf objstorage" &&
+	git init objstorage &&
+	git -C objstorage config set extensions.objectStorage files &&
+	test_must_fail git -C objstorage rev-parse 2>err &&
+	test_grep "repo version is 0, but v1-only extension found" err
+'
+
+test_expect_success DEFAULT_REPO_FORMAT 'extensions.objectStorage with files backend' '
+	test_when_finished "rm -rf objstorage" &&
+	git init objstorage &&
+	git -C objstorage config set core.repositoryformatversion 1 &&
+	git -C objstorage config set extensions.objectStorage files &&
+	test_commit -C objstorage A &&
+	git -C objstorage rev-parse --verify HEAD
+'
+
+test_expect_success DEFAULT_REPO_FORMAT 'extensions.objectStorage with unknown backend' '
+	test_when_finished "rm -rf objstorage" &&
+	git init objstorage &&
+	git -C objstorage config set core.repositoryformatversion 1 &&
+	git -C objstorage config set extensions.objectStorage garbage &&
+	test_must_fail git -C objstorage rev-parse 2>err &&
+	test_grep "invalid value for ${SQ}extensions.objectstorage${SQ}: ${SQ}garbage${SQ}" err &&
+
+	git config --file objstorage/.git/config extensions.objectStorage garbage://payload &&
+	test_must_fail git -C objstorage rev-parse 2>err &&
+	test_grep "invalid value for ${SQ}extensions.objectstorage${SQ}: ${SQ}garbage://payload${SQ}" err
+'
+
 test_expect_success MINGW 'core.hidedotfiles = false' '
 	git config --global core.hidedotfiles false &&
 	rm -rf newdir &&
diff --git a/t/unit-tests/u-odb-inmemory.c b/t/unit-tests/u-odb-inmemory.c
index a8da278c68..d7261b9e0c 100644
--- a/t/unit-tests/u-odb-inmemory.c
+++ b/t/unit-tests/u-odb-inmemory.c
@@ -12,6 +12,7 @@
 
 static struct repository repo = {
 	.hash_algo = &hash_algos[GIT_HASH_SHA1],
+	.object_storage_format = (char *) "files",
 };
 static struct object_database *odb;
 
-- 
2.56.0.307.g5fe7bd680c.dirty
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 25 of 59 in “odb: introduce object storage extension”
  1. 0/7 odb: introduce object storage extensionPatrick Steinhardt, Oct 19, 2026
  2. 1/7 loose: drop unused `repo_write_loose_object_map()`Patrick Steinhardt, Oct 19, 2026
  3. Karthik NayakOct 19, 2026
  4. Patrick SteinhardtOct 20, 2026
  5. Karthik NayakOct 20, 2026
  6. 2/7 setup: introduce object storage extensionPatrick Steinhardt, Oct 19, 2026
  7. Karthik NayakOct 19, 2026
  8. Junio C HamanoOct 20, 2026
  9. Karthik NayakOct 20, 2026
  10. Patrick SteinhardtOct 20, 2026
  11. Karthik NayakOct 20, 2026
  12. 3/7 setup: allow overriding object storage format via environmentPatrick Steinhardt, Oct 19, 2026
  13. Karthik NayakOct 19, 2026
  14. Patrick SteinhardtOct 20, 2026
  15. Karthik NayakOct 20, 2026
  16. 4/7 builtin: expose the object storage formatPatrick Steinhardt, Oct 19, 2026
  17. Karthik NayakOct 19, 2026
  18. Patrick SteinhardtOct 20, 2026
  19. Karthik NayakOct 20, 2026
  20. 5/7 builtin/init: introduce handling of object storage formatPatrick Steinhardt, Oct 19, 2026
  21. 6/7 builtin/clone: introduce "--object-storage-format="Patrick Steinhardt, Oct 19, 2026
  22. 7/7 builtin/submodule: propagate "--object-storage-format="Patrick Steinhardt, Oct 19, 2026
  23. 0/7 odb: introduce object storage extensionPatrick Steinhardt, Oct 21, 2026
  24. 1/7 loose: drop unused `repo_write_loose_object_map()`Patrick Steinhardt, Oct 21, 2026
  25. 2/7 setup: introduce object storage extensionPatrick Steinhardt, Oct 21, 2026
  26. 3/7 setup: allow overriding object storage format via environmentPatrick Steinhardt, Oct 21, 2026
  27. 4/7 builtin: expose the object storage formatPatrick Steinhardt, Oct 21, 2026
  28. 5/7 builtin/init: introduce handling of object storage formatPatrick Steinhardt, Oct 21, 2026
  29. Karthik NayakOct 21, 2026
  30. Patrick SteinhardtOct 23, 2026
  31. 6/7 builtin/clone: introduce "--object-storage-format="Patrick Steinhardt, Oct 21, 2026
  32. 7/7 builtin/submodule: propagate "--object-storage-format="Patrick Steinhardt, Oct 21, 2026
  33. Karthik NayakOct 21, 2026
  34. 0/7 odb: introduce object storage extensionPatrick Steinhardt, Oct 23, 2026
  35. 1/7 loose: drop unused `repo_write_loose_object_map()`Patrick Steinhardt, Oct 23, 2026
  36. 2/7 setup: introduce object storage extensionPatrick Steinhardt, Oct 23, 2026
  37. SZEDER GáborOct 24, 2026
  38. Patrick SteinhardtOct 26, 2026
  39. Karthik NayakOct 26, 2026
  40. Patrick SteinhardtOct 26, 2026
  41. 3/7 setup: allow overriding object storage format via environmentPatrick Steinhardt, Oct 23, 2026
  42. Karthik NayakOct 26, 2026
  43. Patrick SteinhardtOct 26, 2026
  44. 4/7 builtin: expose the object storage formatPatrick Steinhardt, Oct 23, 2026
  45. 5/7 builtin/init: introduce handling of object storage formatPatrick Steinhardt, Oct 23, 2026
  46. 6/7 builtin/clone: introduce "--object-storage-format="Patrick Steinhardt, Oct 23, 2026
  47. 7/7 builtin/submodule: propagate "--object-storage-format="Patrick Steinhardt, Oct 23, 2026
  48. Karthik NayakOct 26, 2026
  49. Patrick SteinhardtOct 26, 2026
  50. 0/7 odb: introduce object storage extensionPatrick Steinhardt, Oct 27, 2026
  51. 1/7 loose: drop unused `repo_write_loose_object_map()`Patrick Steinhardt, Oct 27, 2026
  52. 2/7 setup: introduce object storage extensionPatrick Steinhardt, Oct 27, 2026
  53. 3/7 setup: allow overriding object storage format via environmentPatrick Steinhardt, Oct 27, 2026
  54. 4/7 builtin: expose the object storage formatPatrick Steinhardt, Oct 27, 2026
  55. 5/7 builtin/init: introduce handling of object storage formatPatrick Steinhardt, Oct 27, 2026
  56. 6/7 builtin/clone: introduce "--object-storage-format="Patrick Steinhardt, Oct 27, 2026
  57. 7/7 builtin/submodule: propagate "--object-storage-format="Patrick Steinhardt, Oct 27, 2026
  58. Karthik NayakOct 28, 2026
  59. Patrick SteinhardtOct 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.