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

From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com>,
	git@vger.kernel.org
Subject: Re: [PATCH 3/3] init: provide useful advice about init.defaultBranch
Date: Mon, 23 Nov 2020 21:46:09 +0100 (CET)	[thread overview]
Message-ID: <nycvar.QRO.7.76.6.2011232136191.56@tvgsbejvaqbjf.bet> (raw)
In-Reply-To: <xmqqv9dvor27.fsf@gitster.c.googlers.com>

Hi Junio,

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

> 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.

> > "\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

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