From: Karthik Nayak Date: Fri, 04 Sep 2026 13:05:20 GMT Subject: Re: [PATCH 01/11] builtin/init: rename "--ref-format=" to "--ref-storage=" Message-ID: In-Reply-To: <20260904-b4-pks-unify-ref-storage-format-v1-1-08144e5004ff@pks.im> Patrick Steinhardt writes: > Back when we gained support for reftables we of course introduced the > ability to control the reference storage format that is used by newly > created repositories. This infrastructure has grown over time, and > unfortunately without consistency: > > - The command line parameter to specify the ref storage format is > called "--ref-format=", while the corresponding repository extension > is called "refStorage". > > - In most cases we refer to the "ref storage format" in our docs, so > calling it "--ref-format=" is being inconsistent with them. > > - It is possible to override the ref storage format via an environment > variable that is called "GIT_REFERENCE_BACKEND", which is not even > remotely consistent with anything else. > > - There is also an "object format", but that format does not control > how we store objects but rather whether we use SHA1 or SHA256. > > So in summary, it's a huge mess. > > This problem is about to become even worse though, as we're soon going > to introduce an object storage extension. This extension is the > equivalent to the ref storage extension, and of course we also want > users to be able to control which object storage format new repositories > are using. But we cannot properly name that parameter without creating > even more inconsistencies: > > - "--object-format=" would match "--ref-format=", but that parameter > name is already taken to specify the hash function. > > - "--object-storage=" would be a good fit, but be inconsistent with > "--ref-format=". Asking the user to execute `git init --ref-format= > --object-storage=` just feels extremely awkward. > > Instead, this and subsequent patches will fix the mess by consistently > referring to the ref storage format as "ref storage" throughout all > options, environment variables and config settings. This new name much > more closely indicates that it is about how we store data and finally > brings consistency into this area. We will keep the old names working of > course for the sake of backwards compatibility. > > Start with git-init(1). > > Signed-off-by: Patrick Steinhardt > --- > Documentation/config/init.adoc | 2 +- > Documentation/git-init.adoc | 4 ++-- > Documentation/git.adoc | 2 +- > builtin/init-db.c | 16 ++++++++------- > t/perf/p1401-ref-store-tombstones.sh | 4 ++-- > t/perf/perf-lib.sh | 2 +- > t/t0001-init.sh | 24 +++++++++++------------ > t/t0610-reftable-basics.sh | 14 ++++++------- > t/t0611-reftable-httpd.sh | 2 +- > t/t1400-update-ref.sh | 2 +- > t/t1423-ref-backend.sh | 6 +++--- > t/t1460-refs-migrate.sh | 36 +++++++++++++++++----------------- > t/t1900-repo-info.sh | 6 +++--- > t/t5510-fetch.sh | 8 ++++---- > t/t7424-submodule-mixed-ref-formats.sh | 2 +- > 15 files changed, 66 insertions(+), 64 deletions(-) > > diff --git a/Documentation/config/init.adoc b/Documentation/config/init.adoc > index 7b4abdaf8b..9c78440192 100644 > --- a/Documentation/config/init.adoc > +++ b/Documentation/config/init.adoc > @@ -15,7 +15,7 @@ endif::[] > this config. > `init.defaultRefFormat`:: > Allows overriding the default ref storage format for new repositories. > - See `--ref-format=` in linkgit:git-init[1]. Both the command line > + See `--ref-storage=` in linkgit:git-init[1]. Both the command line > option and the `GIT_DEFAULT_REF_FORMAT` environment variable take > precedence over this config. [snip] > @@ -83,7 +83,7 @@ int cmd_init_db(int argc, > unsigned int flags = 0; > int bare = startup_info->force_bare_repository ? 1 : -1; > const char *object_format = NULL; > - const char *ref_format = NULL; > + const char *ref_storage = NULL; > const char *initial_branch = NULL; > int hash_algo = GIT_HASH_UNKNOWN; > enum ref_storage_format ref_storage_format = REF_STORAGE_FORMAT_UNKNOWN; > @@ -109,8 +109,10 @@ int cmd_init_db(int argc, > N_("override the name of the initial branch")), > OPT_STRING(0, "object-format", &object_format, N_("hash"), > N_("specify the hash algorithm to use")), > - OPT_STRING(0, "ref-format", &ref_format, N_("format"), > - N_("specify the reference format to use")), > + OPT_STRING(0, "ref-storage", &ref_storage, N_("format"), > + N_("specify the reference storage format to use")), shouldn't we use 'ref-storage' for the argh value too? > + OPT_STRING_F(0, "ref-format", &ref_storage, N_("format"), > + N_("specify the reference storage format to use"), PARSE_OPT_HIDDEN), > OPT_END() > }; > So we stay backwards compatible by leaving the old 'ref-format' as is. Makes sense. > int ret; > @@ -173,10 +175,10 @@ int cmd_init_db(int argc, > die(_("unknown hash algorithm '%s'"), object_format); > } > > - if (ref_format) { > - ref_storage_format = ref_storage_format_by_name(ref_format); > + if (ref_storage) { > + ref_storage_format = ref_storage_format_by_name(ref_storage); > if (ref_storage_format == REF_STORAGE_FORMAT_UNKNOWN) > - die(_("unknown ref storage format '%s'"), ref_format); > + die(_("unknown ref storage format '%s'"), ref_storage); Funny that we error'd out with 'ref storage' while the name was ref_format. > } > > if (init_shared_repository != -1) [snip]