Subject: Re: [PATCH v2 5/4] initial branch: give hints after switching the default name

From: Phillip Wood <[email-masked]>
Date: Thu, 18 Sep 2025 16:06:28 +0100

On 17/09/2025 17:18, Junio C Hamano wrote:
> It is likely that those who came to Git after 3.0 switched the
> default initial branch name to 'main' would still try to follow
> tutorials that were written before 3.0 happened and with the
> assumption that the tool would call the initial branch 'master'.
> 
> To help these new users after 3.0 boundary, let's retain one part of
> the hint we will be giving before the default changes, namely, how
> to rename the branch an unconfigured Git has created just once.
> 
> We do this without telling them how to permanently configure the
> default name of the initial branch, and that design choice is very
> much deliberate.  The whole point of switching the default name was
> because we did not want to force individual users to configure their
> default branch name but while the hard wired default was 'master',
> they _had_ to configure it away from 'master' in order to conform to
> the recent norm, and a hint that tells them how to do so is useful.
> 
> But once the default is renamed to 'main', that no longer is true.
> A narrower audience who are new users that follow an instruction
> that assumes the initial branch name is 'master' would only need to
> learn "here is how to change the branch name to match the tutorial
> you are following in the repository you created for practice", and
> "here is how you keep creating repositories with the first branch
> with a name everybody hates" is unnecessary.
> 
> It also needs to be noted that the advise token to squelch the
> message is the same advice.defaultBranchName as before, which is
> also very much deliberate.  The users who do have that configured
> are those who _have_ been using Git since before 3.0, and they are
> not the target audience for the new advice message.  Reusing the
> same advise token ensures that they do not have to turn the message
> off.
> 
> Helped-by: Phillip Wood <[email-masked]>
> Signed-off-by: Junio C Hamano <[email-masked]>
> ---
>   * With simplified tests, thanks to Phillip's help.

This looks good. The only thing I wondered about was whether we should
keep

-test_expect_success !WITH_BREAKING_CHANGES 'advice on unconfigured init.defaultBranch' '
+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 &&

in t0001-init.sh from the previous version as we're still printing some
advice.

Thanks

Phillip

> 
>   advice.c      |  2 --
>   advice.h      |  4 +---
>   refs.c        | 12 ++++++++++--
>   t/test-lib.sh | 10 +++++++---
>   4 files changed, 18 insertions(+), 10 deletions(-)
> 
> diff --git a/advice.c b/advice.c
> index 48c49ee414..e5f0ff8449 100644
> --- a/advice.c
> +++ b/advice.c
> @@ -51,9 +51,7 @@ static struct {
>   	[ADVICE_AM_WORK_DIR] 				= { "amWorkDir" },
>   	[ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME] 	= { "checkoutAmbiguousRemoteBranchName" },
>   	[ADVICE_COMMIT_BEFORE_MERGE]			= { "commitBeforeMerge" },
> -#ifndef WITH_BREAKING_CHANGES
>   	[ADVICE_DEFAULT_BRANCH_NAME]			= { "defaultBranchName" },
> -#endif /* WITH_BREAKING_CHANGES */
>   	[ADVICE_DETACHED_HEAD]				= { "detachedHead" },
>   	[ADVICE_DIVERGING]				= { "diverging" },
>   	[ADVICE_FETCH_SET_HEAD_WARN]			= { "fetchRemoteHEADWarn" },
> diff --git a/advice.h b/advice.h
> index fc1dc87204..8def280688 100644
> --- a/advice.h
> +++ b/advice.h
> @@ -18,9 +18,7 @@ enum advice_type {
>   	ADVICE_AM_WORK_DIR,
>   	ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
>   	ADVICE_COMMIT_BEFORE_MERGE,
> -#ifndef WITH_BREAKING_CHANGES
> -	ADVICE_DEFAULT_BRANCH_NAME,
> -#endif /* WITH_BREAKING_CHANGES */
> +	ADVICE_DEFAULT_BRANCH_NAME, /* To be retired sometime after Git 3.0 */
>   	ADVICE_DETACHED_HEAD,
>   	ADVICE_DIVERGING,
>   	ADVICE_FETCH_SET_HEAD_WARN,
> diff --git a/refs.c b/refs.c
> index 149a8d1cec..f15366bfce 100644
> --- a/refs.c
> +++ b/refs.c
> @@ -641,9 +641,17 @@ static const char default_branch_name_advice[] = N_(
>   "\n"
>   "\tgit branch -m <name>\n"
>   );
> +#else
> +static const char default_branch_name_advice[] = N_(
> +"Using '%s' as the name for the initial branch since Git 3.0.\n"
> +"If you expected Git to create 'master', the just-created\n"
> +"branch can be renamed via this command:\n"
> +"\n"
> +"\tgit branch -m master\n"
> +);
>   #endif /* WITH_BREAKING_CHANGES */
>   
> -char *repo_default_branch_name(struct repository *r, MAYBE_UNUSED int quiet)
> +char *repo_default_branch_name(struct repository *r, int quiet)
>   {
>   	const char *config_key = "init.defaultbranch";
>   	const char *config_display_key = "init.defaultBranch";
> @@ -660,10 +668,10 @@ char *repo_default_branch_name(struct repository *r, MAYBE_UNUSED int quiet)
>   		ret = xstrdup("main");
>   #else
>   		ret = xstrdup("master");
> +#endif /* WITH_BREAKING_CHANGES */
>   		if (!quiet)
>   			advise_if_enabled(ADVICE_DEFAULT_BRANCH_NAME,
>   					  _(default_branch_name_advice), ret);
> -#endif /* WITH_BREAKING_CHANGES */
>   	}
>   
>   	full_ref = xstrfmt("refs/heads/%s", ret);
> diff --git a/t/test-lib.sh b/t/test-lib.sh
> index b191954c3c..562f950fb0 100644
> --- a/t/test-lib.sh
> +++ b/t/test-lib.sh
> @@ -127,13 +127,17 @@ then
>   	export GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS
>   fi
>   
> +# Explicitly set the default branch name for testing, to squelch hints
> +# from "git init" during the transition period.  Should be removed
> +# after we decide to remove ADVICE_DEFAULT_BRANCH_NAME
>   if test -z "$WITH_BREAKING_CHANGES"
>   then
> -	# Explicitly set the default branch name for testing, to avoid the
> -	# transitory "git init" warning under --verbose.
>   	: ${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME:=master}
> -	export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME
> +else
> +	: ${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME:=main}
>   fi
> +export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME
> +
>   
>   ################################################################
>   # It appears that people try to run tests without building...