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

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]
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 3 of 20 in “Fix inconsistent ref storage format terminology”
  1. 00/11 Fix inconsistent ref storage format terminologyPatrick Steinhardt, Sep 4, 2026
  2. 01/11 builtin/init: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  3. Karthik NayakSep 4, 2026
  4. Patrick SteinhardtSep 7, 2026
  5. 02/11 builtin/clone: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  6. 03/11 builtin/refs: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  7. 04/11 builtin/submodule: rename "--ref-format=" to "--ref-storage="Patrick Steinhardt, Sep 4, 2026
  8. 05/11 builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage"Patrick Steinhardt, Sep 4, 2026
  9. 06/11 help: rename "default-ref-format" to "default-ref-storage"Patrick Steinhardt, Sep 4, 2026
  10. 07/11 refs: expose function to parse reference URIsPatrick Steinhardt, Sep 4, 2026
  11. Karthik NayakSep 4, 2026
  12. 08/11 setup: refactor how we configure the ref storage formatPatrick Steinhardt, Sep 4, 2026
  13. 09/11 setup: rename ref storage format environment variablesPatrick Steinhardt, Sep 4, 2026
  14. Karthik NayakSep 4, 2026
  15. Patrick SteinhardtSep 7, 2026
  16. 10/11 setup: rename "init.defaultRefFormat" to "init.defaultRefStorage"Patrick Steinhardt, Sep 4, 2026
  17. 11/11 setup: allow "git init --ref-storage=" to specify a payloadPatrick Steinhardt, Sep 4, 2026
  18. Karthik NayakSep 4, 2026
  19. Junio C HamanoSep 4, 2026
  20. Patrick SteinhardtSep 7, 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.