Subject: Re: [PATCH v2 1/4] breaking-changes: switch default branch to main

From: Junio C Hamano <[email-masked]>
Date: Fri, 05 Sep 2025 08:04:37 -0700

Phillip Wood <[email-masked]> writes:

>> Would there be folks who type "git init" to get a 'main' branch,
>> while trying to follow a recipe written in pre-3.0 days that assumes
>> the initial branch is called differently, and get confused after
>> seeing many commands written in the recipe for them to follow , like
>> "git checkout -b next master" fail?  Do they need a different advice
>> message to help them, i.e.e.g,
>>      $ git init
>>      Initialized empty Git repository in /a/b/c/.git/
>>      hint: Since Git 3.0, an initial branch is 'main' these days.
>>      hint: If you need its name to be different (e.g. 'frotz'),
>>      hint: you can immediately rename it with "git branch -m frotz".
>>      hint: Disable this message with "got config set advice.foo false"
>> or something?  I dunno.  In any case, that will have to be a new and
>> different advice message, and defaultBranchName should not be reused
>> for that purpose, so the change in the the above hunk is fine.  I am
>> wondering if we need a new entry protected by the same #ifdef on the
>> #else side.
>
> Personally I find the current advice pretty annoying and would be glad
> to see it go away. Are there really that many people who want to
> customize the initial branch name that it is worth adding some new
> advice post Git 3.0?

Given that the tutorial materials that were written when we gave the
init.defaultBranchName mechanism _all_ assumed that by default the
initial branch that gets created is called 'master', the current
advice messages were primarily not about usability but personal
preference.  The message targets those who dislike 'master' so much
that they are willing to replace all 'master' they read in the
tutorial material as 'main' if they are following an existing
tutorial material.  And the instruction is primarily about how to
switch to a new default permanently with the configuration.

But the one that I pointed out as missing in your proposal is quite
different.  It is meant for those who need help about usability, not
personal preference.  Even if they strongly prefer 'main' over
'master', in order to follow along an existing tutorial material,
they will find it less error prone if the initial branch used in
their practice repository were 'master'.  That is why the
instruction is only about recovering only _this_ repository they
just have created (Notice that I did not tell them how to use the
configuration mechanism to permanently live in the past in the above
"... or something?" example?  It is very deliberate---"the world has
moved, so should they, except for this single instance" is the
message they need to hear).

> Although I find it annoying, I do think the
> current advice serves a useful purpose as it informs people the
> default that they are used to is changing and that they can override
> it. Given how long we've been warning people I'm not sure we need to
> say anything once the default has changed.

You need to remember that there always are new users who use Git
seriously for the first time _after_ switchover happens.

Because it is more about usability than preference, I see at least
the same degree of need, if not more, to help these people who still
need to use the old name to follow along the tutorial material than
those who have been helped by the existing "Sorry you got 'master',
but you may prefer a different name, and you can do so by doing
these things" message,