Re: [PATCH 01/11] builtin/init: rename "--ref-format=" to "--ref-storage="
- From
Karthik Nayak <karthik.188@gmail.com>
- Date
- Sep 4, 2026, 13:05 UTC
- Message-ID
- <CAOLa=ZQO05kg6ekVJf-0Hkmq8rMVQuGox6O7DJL6mMTRA7_HLw@mail.gmail.com>
- In-Reply-To
- <20260904-b4-pks-unify-ref-storage-format-v1-1-08144e5004ff@pks.im>
Patrick Steinhardt <ps@pks.im> writes:
Show 75 quoted lines
> 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 <ps@pks.im> > --- > 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]
Show 17 quoted lines
> @@ -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?
Show 5 quoted lines
> + 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.
Show 12 quoted lines
> 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]