Re: [PATCH v4 1/4] init: document `init.defaultBranch` better

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 11, 2020, 05:47 UTC
Message-ID: <xmqqblf0opwn.fsf@gitster.c.googlers.com>
In-Reply-To: <CAMP44s3mtCd9RnZdW7-HLcKVG13UW8u_1VNC0_7jByQRv61+vw@mail.gmail.com>

Felipe Contreras <felipe.contreras@gmail.com> writes:

Show 9 quoted lines

>> -`refs/tags`, and template files.  An initial `HEAD` file that
>> -references the HEAD of the master branch is also created.
>> +`refs/tags`, and template files.  An initial branch without any
>> +commits will be created (see the `--initial-branch` option below
>> +for its name).
>
> The current sentence: "An initial `HEAD` file that references the HEAD
> of the master branch is also created." is still true. There's no need
> to change that (yet).

The change updates the description for readability, lowering the technical level of description, and correcting inaccuracies.

 - The readers in the context of understanding what "git init"
   performs does not have to know nor care that HEAD is implemented
   as a file.  In fact, there is an effort to introduce HEAD and
   other refs that are implemented as individual files under
   $GIT_DIR/.  Dropping the word "file" is to correct these.

 - Also we no longer say "the HEAD of" a branch, even if we used to
   use that expression.  When we really need to refer to the commit
   directly pointed at by a branch ref, we say "the tip of" instead
   there days.

 - It used to be left unsaid that the initial branch begins its life
   without any commit.  Now it does.

None of these is about "'master' or any other name?" issue.

> Perhaps: (see the `--initial-branch` option below to choose another name).

That changes the meaning of the explanation. It is compensating for not saying what the name of the initial branch is, and is not trying to teach that the name can be changed. The text in the patch is good as-is.