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

Commit Message

Johannes Schindelin Nov. 23, 2020, 11:20 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. With this patch, that is only
true if `init.defaultBranch` is configured, so let's do exactly that in
those test cases. The same reasoning applies to `test_create_repo()`.

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

Comments

Junio C Hamano Nov. 23, 2020, 11:53 p.m. UTC | #1

"Johannes Schindelin via GitGitGadget" <[e-mail]>
writes:

> +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, run:\n"

I think this is good, assuming that "subject to change" covers the
case where we end up doing nothing after all.  I'd feel safer if we
said "s/is subject to change/may change in the future/", but this is
not a strong preference.

> +"\n"
> +"\tgit config --global init.defaultBranch <name>\n"
> +"\n"
> +"Common names are 'main', 'trunk' and 'development'. If you merely wish\n"
> +"to suppress this warning, you can also use the current default branch\n"
> +"name. The current branch can be renamed via this command:\n"

I think this is worse than the previous one.  Those who merely wish
to suppress the message without wanting to commit to a particular
name (i.e. they just want to take whatever the default we give them)
would be mislead and be frozen in time forever.  We do not give
"I'll just accept the default of the day" choice, and that is OK,
but we want to be clear about it, which is why I've kept raising this
as an issue.

    To configure the initial branch name to use in all of your new
    repositories and squelch this message, run:

may be better---it makes it clear that the offered two choices are
(1) do nothing and see this message every time, or (2) commit to a
name and not see this message again.

Thanks.

Johannes Schindelin Nov. 24, 2020, 5:57 a.m. UTC | #2

Hi Junio,

On Mon, 23 Nov 2020, Junio C Hamano wrote:

> "Johannes Schindelin via GitGitGadget" <[e-mail]>
> writes:
>
> > +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, run:\n"
>
> I think this is good, assuming that "subject to change" covers the
> case where we end up doing nothing after all.  I'd feel safer if we
> said "s/is subject to change/may change in the future/", but this is
> not a strong preference.

I'd rather keep the current form, as it sounds a bit more firm to me.

> > +"\n"
> > +"\tgit config --global init.defaultBranch <name>\n"
> > +"\n"
> > +"Common names are 'main', 'trunk' and 'development'. If you merely wish\n"
> > +"to suppress this warning, you can also use the current default branch\n"
> > +"name. The current branch can be renamed via this command:\n"
>
> I think this is worse than the previous one.  Those who merely wish
> to suppress the message without wanting to commit to a particular
> name (i.e. they just want to take whatever the default we give them)
> would be mislead and be frozen in time forever.  We do not give
> "I'll just accept the default of the day" choice, and that is OK,
> but we want to be clear about it, which is why I've kept raising this
> as an issue.
>
>     To configure the initial branch name to use in all of your new
>     repositories and squelch this message, run:
>
> may be better---it makes it clear that the offered two choices are
> (1) do nothing and see this message every time, or (2) commit to a
> name and not see this message again.

Well, I think I finally understand what you are saying: there is a
legitimate need for a way to go with Git's preference but still suppress
that message.

I introduced `advice.defaultBranchName` to that end, and now display
prominently, at the top of the message, how to use that flag to avoid
seeing this advice ever again.

Ciao,
Dscho

Junio C Hamano Nov. 24, 2020, 8:53 p.m. UTC | #3

Johannes Schindelin <[e-mail]> writes:

>>     To configure the initial branch name to use in all of your new
>>     repositories and squelch this message, run:
>>
>> may be better---it makes it clear that the offered two choices are
>> (1) do nothing and see this message every time, or (2) commit to a
>> name and not see this message again.
>
> Well, I think I finally understand what you are saying: there is a
> legitimate need for a way to go with Git's preference but still suppress
> that message.

I am not saying it is a legitimate need.  I just wanted to make it
clear that we deliberately chose not to grant that wish in the
message.  An advice flag in this context means that the users can
choose to let their distro and sysadm to flip the default silently,
which is much worse than having to see the message every time they
start a new repository with "git init".

Johannes Schindelin Dec. 9, 2020, 2:47 p.m. UTC | #4

Hi Junio,

On Tue, 24 Nov 2020, Junio C Hamano wrote:

> Johannes Schindelin <[e-mail]> writes:
>
> >>     To configure the initial branch name to use in all of your new
> >>     repositories and squelch this message, run:
> >>
> >> may be better---it makes it clear that the offered two choices are
> >> (1) do nothing and see this message every time, or (2) commit to a
> >> name and not see this message again.
> >
> > Well, I think I finally understand what you are saying: there is a
> > legitimate need for a way to go with Git's preference but still suppress
> > that message.
>
> I am not saying it is a legitimate need.  I just wanted to make it
> clear that we deliberately chose not to grant that wish in the
> message.  An advice flag in this context means that the users can
> choose to let their distro and sysadm to flip the default silently,
> which is much worse than having to see the message every time they
> start a new repository with "git init".

The distribution already can add patches, so this objection is a red
herring. The sysadm can pick a different value for `init.defaultBranch`
and dictate to the user silently what initial branch name to use, so that
is also a red herring.

I still think that there is a legitimate need for this config option to
turn the advice off, without having to override Git's default branch name.

In particular in this context, I would think that most users will want to
just go with whatever is Git's default.

Ciao,
Dscho

Junio C Hamano Dec. 9, 2020, 10:15 p.m. UTC | #5

Johannes Schindelin <[e-mail]> writes:

> On Tue, 24 Nov 2020, Junio C Hamano wrote:
>
>> I am not saying it is a legitimate need.  I just wanted to make it
>> clear that we deliberately chose not to grant that wish in the
>> message.  An advice flag in this context means that the users can
>> choose to let their distro and sysadm to flip the default silently,
>> which is much worse than having to see the message every time they
>> start a new repository with "git init".
>
> The distribution already can add patches, so this objection is a red
> herring. The sysadm can pick a different value for `init.defaultBranch`
> and dictate to the user silently what initial branch name to use, so that
> is also a red herring.

The "setting init.defaultBranch is the only way to squelch" approach
means the ~/.gitconfig will have the settings soon after the user
starts using Git and /etc/gitconfig will not allow administrators to
force their will over what the user decides to use.  Distros adding
patches to strip configurability by setting init.defaultBranch in
user's ~/.gitconfig?  Is that the kind of possibilities worth
discussing?

So, no, your counter-argument above is nothing but a red-herring.

If you want a counter-argument, please explain why "I am fine to see
the default flipped to whatever the tool picks and having no control
over when the flipping happens" can be a sensible choice for users
with what kind of workflows.  The only folks I can think of who
would be fine with that are (1) those who do not create the second
branch in the repository and will stay on the primary branch
forever, and (2) those who immediately rename the branch to what
they want after "git init".  For other folks, such a choice is a
disaster waiting to happen, and it just feels irresponsible to offer
such a choice, at least to me.

Thanks.

Felipe Contreras Dec. 10, 2020, 12:40 a.m. UTC | #6

On Wed, Dec 9, 2020 at 5:24 PM Johannes Schindelin
<[e-mail]> wrote:
> On Tue, 24 Nov 2020, Junio C Hamano wrote:

> The distribution already can add patches, so this objection is a red
> herring. The sysadm can pick a different value for `init.defaultBranch`
> and dictate to the user silently what initial branch name to use, so that
> is also a red herring.

Yes, but if they do; they have picked the ball. The user would blame
them--and not Git--for any unexpected change in behavior.

Cheers.

Johannes Schindelin Dec. 10, 2020, 12:12 p.m. UTC | #7

Hi Junio,

On Wed, 9 Dec 2020, Junio C Hamano wrote:

> Johannes Schindelin <[e-mail]> writes:
>
> > On Tue, 24 Nov 2020, Junio C Hamano wrote:
> >
> >> I am not saying it is a legitimate need.  I just wanted to make it
> >> clear that we deliberately chose not to grant that wish in the
> >> message.  An advice flag in this context means that the users can
> >> choose to let their distro and sysadm to flip the default silently,
> >> which is much worse than having to see the message every time they
> >> start a new repository with "git init".
> >
> > The distribution already can add patches, so this objection is a red
> > herring. The sysadm can pick a different value for `init.defaultBranch`
> > and dictate to the user silently what initial branch name to use, so that
> > is also a red herring.
>
> The "setting init.defaultBranch is the only way to squelch" approach
> means the ~/.gitconfig will have the settings soon after the user
> starts using Git and /etc/gitconfig will not allow administrators to
> force their will over what the user decides to use.  Distros adding
> patches to strip configurability by setting init.defaultBranch in
> user's ~/.gitconfig?  Is that the kind of possibilities worth
> discussing?
>
> So, no, your counter-argument above is nothing but a red-herring.
>
> If you want a counter-argument, please explain why "I am fine to see
> the default flipped to whatever the tool picks and having no control
> over when the flipping happens" can be a sensible choice for users
> with what kind of workflows.  The only folks I can think of who
> would be fine with that are (1) those who do not create the second
> branch in the repository and will stay on the primary branch
> forever, and (2) those who immediately rename the branch to what
> they want after "git init".  For other folks, such a choice is a
> disaster waiting to happen, and it just feels irresponsible to offer
> such a choice, at least to me.

I'll make this short.

I talked to a couple Git users whether they'd be fine if `git init` used a
different branch name by default, and everybody I asked said essentially
"yeah, whatever, I don't really care".

For that reason, Git for Windows' installer has that option, and will keep
offering it.

Ciao,
Dscho

Junio C Hamano Dec. 10, 2020, 11:32 p.m. UTC | #8

Johannes Schindelin <[e-mail]> writes:

> I talked to a couple Git users whether they'd be fine if `git init` used a
> different branch name by default, and everybody I asked said essentially
> "yeah, whatever, I don't really care".

Yeah, I would expect that, too.  They would not have asked about the
details on when that switchover of the default would happen, and
would not have been told that the timing is not under their control.
I would answer to such a question with "yeah, whatever." that does
not give you an assurance that I won't complain when the switchover
actually happens ;-).

Patch

diff --git a/refs.c b/refs.c
index 8df03122d6..67275858fc 100644
--- a/refs.c
+++ b/refs.c
@@ -562,6 +562,20 @@  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, run:\n"
+"\n"
+"\tgit config --global init.defaultBranch <name>\n"
+"\n"
+"Common names are 'main', 'trunk' and 'development'. If you merely wish\n"
+"to suppress this warning, you can also use the current default branch\n"
+"name. The current branch 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 +588,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 69c5ad179c..6f693d9609 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 9974457f56..5189a520a2 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=repo 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 59bbf75e83..68305a4939 100644
--- a/t/test-lib-functions.sh
+++ b/t/test-lib-functions.sh
@@ -1202,7 +1202,8 @@  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