Re: [PATCH 3/3] init: provide useful advice about init.defaultBranch

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Nov 23, 2020, 20:46 UTC
Message-ID: <nycvar.QRO.7.76.6.2011232136191.56@tvgsbejvaqbjf.bet>
In-Reply-To: <xmqqv9dvor27.fsf@gitster.c.googlers.com>

Hi Junio,

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

Show 27 quoted lines

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
> >> The above may give a valuable lesson to those who want to use one
> >> branch name across new repositories, but it does not tell those who
> >> wanted 'trunk' (to match the project, perhaps github.com/cli/cli,
> >> with which they intend to interact) how to recover from having
> >> already created the 'master' branch.  We may want to add some text
> >> to suggest "branch -M" after giving the advice for the permanent
> >> option.
> >
> > Good point.
> >
> >> Also, it is unclear to those who do not have a good <name> in mind
> >> (or, those who do not care to choose a <name> for themselves), what
> >> <name> they should give to take the "or to silence this warning"
> >> part of the advice.
> >
> > Also a good point.
>
> > I came up with this, which I intend to submit with v2:
> >
> > static const char default_branch_name_advice[] = N_(
> > "Using '%s' as the name for the initial branch. This name is subject\n"
> > "to change. To configure the initial branch name to use in all of your\n"
> > "new repositories (or to suppress this warning), run:\n"
>
> The same issue around "to suppress" is here, though.

Hmm. I would like to believe that readers understand that setting it to _any_ name would suppress this warning.

Show 12 quoted lines

> > "\n"
> > "\tgit config --global init.defaultBranch <name>\n"
> > "\n"
> > "Common names are 'main', 'trunk' and 'development'. The initial branch\n"
> > "can be renamed via this command:\n"
> > "\n"
> > "\tgit branch -m <name>\n"
>
> It is very likely that the users are on an unborn branch when they
> see this message and "git branch -m/-M <name>" does not work.  We'd
> probably want to update "git branch" to allow renaming the current
> branch that is unborn.

Ouch, good point, I had not even realized that that does not work. In v2, I will include a patch that lets it work.

> In the meantime, you could do "git checkout --orphan <name>" here,
> but once <name> exists as a branch that would not work, so...

Careful. We should start thinking about phasing out either `checkout` or `switch`. The latter was intended to supersede the former with respect to working on branches, so I would think of phasing out `checkout` and favor `switch` instead.

That issue aside, `git switch --orphan <name>` is not necessarily a good UI here. Its documentation talks about creating a new branch, deleting all tracked files. While it is technically still correct that this command, when run on an unborn branch, does the same as renaming said branch, it is highly unintuitive to think about it that way. ("I don't want to create a new branch, I want to rename the current one! And whoa, delete tracked files? I don't want to delete _any_ files! What do you mean: there aren't any tracked files, so none are deleted? Why do you talk about deleting files, then?")

So in the interest of _reducing_ confusion, I would really, really, _really_ like to avoid mentioning that command in this advice.

It really is much better to make `git branch -m <name>` work in this scenario.

Ciao, Dscho

Show 7 quoted lines

>
>
> > );
> >
> > Ciao,
> > Dscho
>