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

[PATCH v2 6/7] builtin/clone: introduce "--object-storage-format="

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

Wire up the new object storage format in git-clone(1) via a new `--object-storage-format=` option, same as we have introduced in the preceding commit for git-init(1).

Note that "--local" clones will not work if either of the object databases is not using the "files" format. This is because we hardlink loose objects and packfiles into the new repository, and that is something that simply won't work with alternative backends. Consequently, we either downgrade to a non-local clone with a warning, or we die in case the user has explicitly asked for a local clone.

We _could_ in theory handle the case where the "files" backend has been configured with an alternative object directory path (that is, with "files:///path/to/dir"). But that's left for a future patch series to implement for the sake of simplicity.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-clone.adoc | 11 +++++++
 builtin/clone.c              | 50 ++++++++++++++++++++++++++++++--
 t/t5601-clone.sh             | 68 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 127 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc
index 07f7cf1a98..dd3b44817a 100644
--- a/Documentation/git-clone.adoc
+++ b/Documentation/git-clone.adoc
@@ -360,6 +360,17 @@ include::ref-storage-format.adoc[]
 `--ref-format=<format>`::
 Deprecated alias of `--ref-storage-format=<format>`.
 
+`--object-storage-format=<format>`::
+Specify the given object storage _<format>_ for the repository. Backends that
+require additional configuration accept a payload in the form
+`<format>://<payload>`, for example a path or a connection string identifying
+the database that shall store the objects. The valid values are:
++
+include::object-storage-format.adoc[]
++
+Local clones (see `--local`) fall back to the regular transport when either
+repository uses a non-default object storage.
+
 `-j<n>`::
 `--jobs=<n>`::
 	The number of submodules fetched at the same time.
diff --git a/builtin/clone.c b/builtin/clone.c
index ba4fc16def..85c124dc37 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -26,6 +26,7 @@
 #include "refspec.h"
 #include "object-file.h"
 #include "odb.h"
+#include "odb/source.h"
 #include "tree.h"
 #include "tree-walk.h"
 #include "unpack-trees.h"
@@ -378,6 +379,28 @@ static void copy_or_link_directory(struct strbuf *src, struct strbuf *dest,
 	dir_iterator_free(iter);
 }
 
+static bool is_using_default_object_storage_format(const char *repo_path)
+{
+	struct repository_format format = REPOSITORY_FORMAT_INIT;
+	struct strbuf config = STRBUF_INIT;
+	bool uses_default_format = true;
+	char *payload = NULL;
+
+	get_common_dir(&config, repo_path);
+	strbuf_addstr(&config, "/config");
+	read_repository_format(&format, config.buf);
+
+	if (format.version >= 1 &&
+	    format.object_storage &&
+	    (odb_source_type_by_uri(format.object_storage, &payload) != ODB_SOURCE_FILES || payload))
+		uses_default_format = false;
+
+	clear_repository_format(&format);
+	strbuf_release(&config);
+	free(payload);
+	return uses_default_format;
+}
+
 static void clone_local(const char *src_repo, const char *dest_repo)
 {
 	if (!option_shared) {
@@ -927,6 +950,7 @@ int cmd_clone(int argc,
 	struct string_list option_not = STRING_LIST_INIT_NODUP;
 	const char *real_git_dir = NULL;
 	const char *ref_storage_format_uri = NULL;
+	const char *object_storage_format_uri = NULL;
 	const char *option_upload_pack = "git-upload-pack";
 	int option_progress = -1;
 	int option_sparse_checkout = 0;
@@ -1008,6 +1032,8 @@ int cmd_clone(int argc,
 			   N_("separate git dir from working tree")),
 		OPT_STRING(0, "ref-storage-format", &ref_storage_format_uri, N_("format"),
 			   N_("specify the reference storage format to use")),
+		OPT_STRING(0, "object-storage-format", &object_storage_format_uri, N_("format"),
+			   N_("specify the object storage format to use")),
 		OPT_ALIAS_F(0, "ref-format", "ref-storage-format", PARSE_OPT_HIDDEN),
 		OPT_STRING_LIST('c', "config", &option_config, N_("key=value"),
 				N_("set config inside the new repository")),
@@ -1060,6 +1086,10 @@ int cmd_clone(int argc,
 			die(_("unknown ref storage format '%s'"), ref_storage_format_uri);
 	}
 
+	if (object_storage_format_uri &&
+	    odb_source_type_by_uri(object_storage_format_uri, NULL) == ODB_SOURCE_UNKNOWN)
+		die(_("unknown object storage format '%s'"), object_storage_format_uri);
+
 	if (option_mirror) {
 		option_bare = 1;
 		option_tags = 0;
@@ -1213,8 +1243,9 @@ int cmd_clone(int argc,
 	 * their on-disk data structures.
 	 */
 	create_repository(the_repository, git_dir, real_git_dir, work_tree,
-			  option_template, GIT_HASH_UNKNOWN, ref_storage_format_uri,
-			  NULL, do_not_override_repo_unix_permissions, NULL);
+			  option_template, GIT_HASH_UNKNOWN,
+			  ref_storage_format_uri, object_storage_format_uri,
+			  do_not_override_repo_unix_permissions, NULL);
 
 	if (real_git_dir) {
 		free((char *)git_dir);
@@ -1362,6 +1393,21 @@ int cmd_clone(int argc,
 			is_local = 0;
 		}
 	}
+
+	/*
+	 * Local clones copy or hardlink the object directory of the source repository
+	 * into the destination. This only works when both repositories use the "files"
+	 * object storage format.
+	 */
+	if (is_local &&
+	    (!is_using_default_object_storage_format(path) || !is_using_default_object_storage_format(git_dir))) {
+		if (option_local > 0)
+			die(_("cannot perform local clone with non-default object storage format"));
+		else
+			warning(_("falling back to non-local clone because of non-default object storage format"));
+		is_local = 0;
+	}
+
 	if (option_local > 0 && !is_local)
 		warning(_("--local is ignored"));
 
diff --git a/t/t5601-clone.sh b/t/t5601-clone.sh
index 06f6121f82..85f439d6b6 100755
--- a/t/t5601-clone.sh
+++ b/t/t5601-clone.sh
@@ -181,6 +181,74 @@ test_expect_success 'clone with garbage ref format' '
 	test_path_is_missing ref-storage
 '
 
+test_expect_success 'clone with files object storage format' '
+	test_when_finished "rm -rf object-storage" &&
+	git clone --object-storage-format=files --bare src object-storage &&
+	test_must_fail git -C object-storage config get extensions.objectstorage &&
+	git -C object-storage rev-parse --show-object-storage-format >actual &&
+	echo files >expect &&
+	test_cmp expect actual
+'
+
+test_expect_success 'clone with object storage payload' '
+	test_when_finished "rm -rf object-storage" &&
+	git clone --object-storage-format=files://objs --bare src object-storage &&
+	git -C object-storage config get extensions.objectstorage >actual &&
+	echo files://objs >expect &&
+	test_cmp expect actual &&
+	git -C object-storage rev-parse --show-object-storage-format >actual &&
+	test_cmp expect actual &&
+	test_path_is_dir object-storage/objs/pack &&
+	test_path_is_missing object-storage/objects/pack
+'
+
+test_expect_success 'clone with object storage payload and bundle URI' '
+	test_when_finished "rm -rf object-storage src.bundle" &&
+	git -C src bundle create ../src.bundle --all &&
+	git clone --object-storage-format=files://objs --bundle-uri="$PWD/src.bundle" \
+		src object-storage &&
+	git -C object-storage rev-parse --show-object-storage-format >actual &&
+	echo files://objs >expect &&
+	test_cmp expect actual
+'
+
+test_expect_success 'clone with garbage object storage format' '
+	cat >expect <<-EOF &&
+	fatal: unknown object storage format ${SQ}garbage${SQ}
+	EOF
+	test_must_fail git clone --object-storage-format=garbage --bare src object-storage 2>err &&
+	test_cmp expect err &&
+	test_path_is_missing object-storage
+'
+
+test_expect_success 'local clone into non-default object storage bails' '
+	test_when_finished "rm -rf object-storage" &&
+	test_must_fail git clone --local --object-storage-format=files://objs src object-storage 2>err &&
+	test_grep "cannot perform local clone with non-default object storage format" err
+'
+
+test_expect_success 'local clone from explicit files object storage succeeds' '
+	test_when_finished "rm -rf object-storage object-storage-dest" &&
+	git clone src object-storage &&
+	git -C object-storage config set core.repositoryformatversion 1 &&
+	git -C object-storage config set extensions.objectstorage files &&
+	git clone --local object-storage object-storage-dest
+'
+
+test_expect_success 'local clone from non-default object storage bails' '
+	test_when_finished "rm -rf object-storage object-storage-dest" &&
+	git clone --object-storage-format=files://objs src object-storage &&
+	test_must_fail git clone --local object-storage object-storage-dest 2>err &&
+	test_grep "cannot perform local clone with non-default object storage format" err
+'
+
+test_expect_success 'local clone from non-default object storage without --local warns' '
+	test_when_finished "rm -rf object-storage object-storage-dest" &&
+	git clone --object-storage-format=files://objs src object-storage &&
+	git clone object-storage object-storage-dest 2>err &&
+	test_grep "falling back to non-local clone" err
+'
+
 test_expect_success 'clone to destination with trailing /' '
 
 	git clone src target-1/ &&
-- 
2.56.0.307.g5fe7bd680c.dirty
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 31 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.