[v4,4/4] init: provide useful advice about init.defaultBranch

Commit Message

Johannes Schindelin Dec. 10, 2020, 9:58 p.m. UTC

From: Johannes Schindelin <[e-mail]>

To give ample warning for users wishing to override Git's the fall-back
for an unconfigured `init.defaultBranch` (in case we decide to change it
in a future Git version), let's introduce some advice that is shown upon
`git init` when that value is not set.

Note: two test cases in Git's test suite want to verify that the
`stderr` output of `git init` is empty. It is now necessary to suppress
the advice, we now do that via the `init.defaultBranch` setting. While
not strictly necessary, we also set this to `false` in
`test_create_repo()`.

Signed-off-by: Johannes Schindelin <[e-mail]>
---
 refs.c                  | 18 +++++++++++++++++-
 t/t0001-init.sh         |  9 ++++++++-
 t/t1510-repo-setup.sh   |  2 +-
 t/test-lib-functions.sh |  4 +++-
 4 files changed, 29 insertions(+), 4 deletions(-)

Comments

Felipe Contreras Dec. 11, 2020, 12:15 a.m. UTC | #1

On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget
<[e-mail]> wrote:

> +static const char default_branch_name_advice[] = N_(
> +"Using '%s' as the name for the initial branch. This default branch name\n"
> +"is subject to change. To configure the initial branch name to use in all\n"
> +"of your new repositories, which will suppress this warning, call:\n"
> +"\n"
> +"\tgit config --global init.defaultBranch <name>\n"
> +"\n"
> +"Common names are 'main', 'trunk' and 'development'. The initial branch\n"

This is disingenuous; the most common name is "master"... by far. In a
couple years this might change, but not right now.

If you don't want to mention "master", then don't mention "common
names" that are not really the most common names.

Cheers.

Johannes Schindelin Dec. 11, 2020, 12:47 a.m. UTC | #2

Hi Junio,

On Thu, 10 Dec 2020, Junio C Hamano wrote:

> Felipe Contreras <[e-mail]> writes:
>
> > On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget
> > <[e-mail]> wrote:
> >
> >> +static const char default_branch_name_advice[] = N_(
> >> +"Using '%s' as the name for the initial branch. This default branch name\n"
> >> +"is subject to change. To configure the initial branch name to use in all\n"
> >> +"of your new repositories, which will suppress this warning, call:\n"
> >> +"\n"
> >> +"\tgit config --global init.defaultBranch <name>\n"
> >> +"\n"
> >> +"Common names are 'main', 'trunk' and 'development'. The initial branch\n"
> >
> > This is disingenuous; the most common name is "master"... by far. In a
> > couple years this might change, but not right now.
> >
> > If you don't want to mention "master", then don't mention "common
> > names" that are not really the most common names.
>
> Names commonly chosen by those who want to move away from 'master'
> are...

"those who want to move away" sounds a bit too non-committal for my
liking. So I changed it to:

	Names commonly chosen instead of 'master' are 'main', 'trunk'
	and 'development'.

While at it, I also improved the next sentence:

	 The just-created branch can be renamed via this command:

Ciao,
Dscho

Junio C Hamano Dec. 11, 2020, 1:22 a.m. UTC | #3

Felipe Contreras <[e-mail]> writes:

> On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget
> <[e-mail]> wrote:
>
>> +static const char default_branch_name_advice[] = N_(
>> +"Using '%s' as the name for the initial branch. This default branch name\n"
>> +"is subject to change. To configure the initial branch name to use in all\n"
>> +"of your new repositories, which will suppress this warning, call:\n"
>> +"\n"
>> +"\tgit config --global init.defaultBranch <name>\n"
>> +"\n"
>> +"Common names are 'main', 'trunk' and 'development'. The initial branch\n"
>
> This is disingenuous; the most common name is "master"... by far. In a
> couple years this might change, but not right now.
>
> If you don't want to mention "master", then don't mention "common
> names" that are not really the most common names.

Names commonly chosen by those who want to move away from 'master'
are...

Felipe Contreras Dec. 11, 2020, 2 a.m. UTC | #4

On Thu, Dec 10, 2020 at 7:23 PM Junio C Hamano <[e-mail]> wrote:
>
> Felipe Contreras <[e-mail]> writes:
>
> > On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget
> > <[e-mail]> wrote:
> >
> >> +static const char default_branch_name_advice[] = N_(
> >> +"Using '%s' as the name for the initial branch. This default branch name\n"
> >> +"is subject to change. To configure the initial branch name to use in all\n"
> >> +"of your new repositories, which will suppress this warning, call:\n"
> >> +"\n"
> >> +"\tgit config --global init.defaultBranch <name>\n"
> >> +"\n"
> >> +"Common names are 'main', 'trunk' and 'development'. The initial branch\n"
> >
> > This is disingenuous; the most common name is "master"... by far. In a
> > couple years this might change, but not right now.
> >
> > If you don't want to mention "master", then don't mention "common
> > names" that are not really the most common names.
>
> Names commonly chosen by those who want to move away from 'master'
> are...

But we don't want to spill drama into the user interface.

I think the vast majority of users haven't heard of this drama. Just
like the vast majority of users had not heard of the git-foo
obsoletion even after several years. Our vantage point is skewed for
being too close to Git development.

Those users will ask: "who wants to move away from 'master'?"

If we don't presume our users have the same knowledge as us, we have to explain:

  Names commonly chosen by those who want to move away from 'master'
  are; 'main', 'trunk', and 'development'. For more information read
  this post:
  https://dev.to/rhymu8354/git-renaming-the-master-branch-137b.

I say don't. If the user wants to know why anyone would want to change
"the default branch name", she can google it and find out.

Cheer.

Patch

diff --git a/refs.c b/refs.c
index 8df03122d69..6e047b3d1b4 100644
--- a/refs.c
+++ b/refs.c
@@ -562,6 +562,19 @@  void expand_ref_prefix(struct strvec *prefixes, const char *prefix)
 		strvec_pushf(prefixes, *p, len, prefix);
 }
 
+static const char default_branch_name_advice[] = N_(
+"Using '%s' as the name for the initial branch. This default branch name\n"
+"is subject to change. To configure the initial branch name to use in all\n"
+"of your new repositories, which will suppress this warning, call:\n"
+"\n"
+"\tgit config --global init.defaultBranch <name>\n"
+"\n"
+"Common names are 'main', 'trunk' and 'development'. The initial branch\n"
+"that was created can be renamed via this command:\n"
+"\n"
+"\tgit branch -m <name>\n"
+);
+
 char *repo_default_branch_name(struct repository *r, int quiet)
 {
 	const char *config_key = "init.defaultbranch";
@@ -574,8 +587,11 @@  char *repo_default_branch_name(struct repository *r, int quiet)
 	else if (repo_config_get_string(r, config_key, &ret) < 0)
 		die(_("could not retrieve `%s`"), config_display_key);
 
-	if (!ret)
+	if (!ret) {
 		ret = xstrdup("master");
+		if (!quiet)
+			advise(_(default_branch_name_advice), ret);
+	}
 
 	full_ref = xstrfmt("refs/heads/%s", ret);
 	if (check_refname_format(full_ref, 0))
diff --git a/t/t0001-init.sh b/t/t0001-init.sh
index bb23e56a165..0803994874f 100755
--- a/t/t0001-init.sh
+++ b/t/t0001-init.sh
@@ -163,7 +163,7 @@  test_expect_success 'reinit' '
 	(
 		mkdir again &&
 		cd again &&
-		git init >out1 2>err1 &&
+		git -c init.defaultBranch=initial init >out1 2>err1 &&
 		git init >out2 2>err2
 	) &&
 	test_i18ngrep "Initialized empty" again/out1 &&
@@ -558,6 +558,13 @@  test_expect_success 'overridden default initial branch name (config)' '
 	grep nmb actual
 '
 
+test_expect_success 'advice on unconfigured init.defaultBranch' '
+	GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME= git -c color.advice=always \
+		init unconfigured-default-branch-name 2>err &&
+	test_decode_color <err >decoded &&
+	test_i18ngrep "<YELLOW>hint: " decoded
+'
+
 test_expect_success 'overridden default main branch name (env)' '
 	test_config_global init.defaultBranch nmb &&
 	GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME=env git init main-branch-env &&
diff --git a/t/t1510-repo-setup.sh b/t/t1510-repo-setup.sh
index 9974457f561..bbfe05b8e4a 100755
--- a/t/t1510-repo-setup.sh
+++ b/t/t1510-repo-setup.sh
@@ -79,7 +79,7 @@  setup_repo () {
 	name=$1 worktreecfg=$2 gitfile=$3 barecfg=$4 &&
 	sane_unset GIT_DIR GIT_WORK_TREE &&
 
-	git init "$name" &&
+	git -c init.defaultBranch=initial init "$name" &&
 	maybe_config "$name/.git/config" core.worktree "$worktreecfg" &&
 	maybe_config "$name/.git/config" core.bare "$barecfg" &&
 	mkdir -p "$name/sub/sub" &&
diff --git a/t/test-lib-functions.sh b/t/test-lib-functions.sh
index 59bbf75e832..9910102ae1f 100644
--- a/t/test-lib-functions.sh
+++ b/t/test-lib-functions.sh
@@ -1202,7 +1202,9 @@  test_create_repo () {
 	mkdir -p "$repo"
 	(
 		cd "$repo" || error "Cannot setup test environment"
-		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" init \
+		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" -c \
+			init.defaultBranch="${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME-master}" \
+			init \
 			"--template=$GIT_BUILD_DIR/templates/blt/" >&3 2>&4 ||
 		error "cannot run git init -- have you built things yet?"
 		mv .git/hooks .git/hooks-disabled