Re: [PATCH v2 01/11] builtin/init: rename "--ref-format=" to "--ref-storage-format="

[Patrick Steinhardt <ps@pks.im>]

On Tue, Sep 08, 2026 at 02:31:22PM +0530, Kaartic Sivaraam wrote:
> On 9/7/26 16:48, Patrick Steinhardt wrote:
> 
> > Instead, this and subsequent patches will fix the mess by consistently
> > referring to the ref storage format as such 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.
> > 
> 
> Just a doubt regarding the old option. At the moment, the patch appears to
> introduce the new name alongside the old name. Do we not plan on deprecating
> the old one and issue a warning to users when it is used so that we could
> eventually retire it at some point?

I'm aiming for a a quiet deprecation -- the old options keep on working,
but we don't show them anymore. We may eventually remove them
altogether, but I neither want to warn about use of old options now or
even remove them as that would likely cause more negative consequences
than is worth it. It's not like we want to soon use the old names.

> > diff --git a/Documentation/config/init.adoc b/Documentation/config/init.adoc
> > index 7b4abdaf8b..a048f0bddc 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-format=` in linkgit:git-init[1]. Both the command line
> >   	option and the `GIT_DEFAULT_REF_FORMAT` environment variable take
> >   	precedence over this config.
> 
> Relevant only if we are deprecating the old option: we need to mention that
> the old one is deprecated in the documentation so that users are aware of
> the same.

But I agree that we should keep the old options documented. Otherwise,
it might be hard to figure out what those options do in case they for
example still exist in an old script.

> > diff --git a/builtin/init-db.c b/builtin/init-db.c
> > index e96b1283b7..63f33154c0 100644
> > --- a/builtin/init-db.c
> > +++ b/builtin/init-db.c
> > @@ -57,7 +57,7 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
> >   static const char *const init_db_usage[] = {
> >   	N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
> >   	   "         [--separate-git-dir <git-dir>] [--object-format=<format>]\n"
> > -	   "         [--ref-format=<format>]\n"
> > +	   "         [--ref-storage-format=<format>]\n"
> >   	   "         [-b <branch-name> | --initial-branch=<branch-name>]\n"
> >   	   "         [--shared[=<permissions>]] [<directory>]"),
> >   	NULL
> > @@ -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_format_str = 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-format", &ref_storage_format_str, N_("format"),
> > +			   N_("specify the reference storage format to use")),
> > +		OPT_STRING_F(0, "ref-format", &ref_storage_format_str, N_("format"),
> > +			   N_("specify the reference storage format to use"), PARSE_OPT_HIDDEN),
> 
> Relevant only if we are deprecating the old option: We could change the
> description of the old option to convey that it is deprecated so that it
> could be easily distinguished by anyone reading through. I suggest this by
> noting a similar pattern in `builtin/name-rev.c` for the `--stdin` argument.

We don't really have to update the description as we pass
`PARSE_OPT_HIDDEN` anyway, so the option is not even shown.

> If we don't plan to deprecate, I suppose we could use OPT_ALIAS to clarify
> that `ref-format` is an alias of `ref-storage-format` similar to how
> `recursive` is marked as an alias of `recurse-submodules` in
> `builtin/clone.c`.

I was originally planning to use `OPT_ALIAS()`, but we don't seem to
support `PARSE_OPT_HIDDEN` there. Maybe it's better to add a small
preparatory patch to support that though.

Patrick