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

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

@@ -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")),

 	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);