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

[Kaartic Sivaraam <kaartic.sivaraam@gmail.com>]

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?

> ---
>   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..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.

> diff --git a/Documentation/git-init.adoc b/Documentation/git-init.adoc
> index bab99b9b47..7e407d3ef1 100644
> --- a/Documentation/git-init.adoc
> +++ b/Documentation/git-init.adoc
> @@ -11,7 +11,7 @@ SYNOPSIS
>   [synopsis]
>   git init [-q | --quiet] [--bare] [--template=<template-directory>]
>   	 [--separate-git-dir <git-dir>] [--object-format=<format>]
> -	 [--ref-format=<format>]
> +	 [--ref-storage-format=<format>]
>   	 [-b <branch-name> | --initial-branch=<branch-name>]
>   	 [--shared[=<permissions>]] [<directory>]
>   
> @@ -57,7 +57,7 @@ values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
>   +
>   include::object-format-disclaimer.adoc[]
>   
> -`--ref-format=<format>`::
> +`--ref-storage-format=<format>`::
>   Specify the given ref storage _<format>_ for the repository. The valid values are:
>   +
>   include::ref-storage-format.adoc[]
> diff --git a/Documentation/git.adoc b/Documentation/git.adoc
> index 8a5cdd3b3d..23ba65656e 100644
> --- a/Documentation/git.adoc
> +++ b/Documentation/git.adoc
> @@ -593,7 +593,7 @@ double-quotes and respecting backslash escapes. E.g., the value
>   `GIT_DEFAULT_REF_FORMAT`::
>   	If this variable is set, the default reference backend format for new
>   	repositories will be set to this value. The default is "files".
> -	See `--ref-format` in linkgit:git-init[1].
> +	See `--ref-storage-format` in linkgit:git-init[1].
>   
>   `GIT_REFERENCE_BACKEND`::
>       Specify which reference backend to be used along with its URI.
> 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.

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`.

> diff --git a/t/t7424-submodule-mixed-ref-formats.sh b/t/t7424-submodule-mixed-ref-formats.sh
> index 559713b607..1ca245c732 100755
> --- a/t/t7424-submodule-mixed-ref-formats.sh
> +++ b/t/t7424-submodule-mixed-ref-formats.sh
> @@ -31,7 +31,7 @@ test_expect_success 'add existing repository with different ref storage format'
>   	(
>   		cd parent &&
>   		test_commit parent &&
> -		git init --ref-format=$OTHER_FORMAT submodule &&
> +		git init --ref-storage-format=$OTHER_FORMAT submodule &&
>   		test_commit -C submodule submodule &&
>   		git submodule add ./submodule
>   	)
> 

Rest of the patch looks fine to me.

--
Sivaraam