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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Dec 11, 2020, 06:26 UTC
Message-ID: <CAMP44s1qW=_x6FeU7-dho+bxmY+0n4EehW8-Xy3PX_+sbhjmcg@mail.gmail.com>
In-Reply-To: <xmqqblf0opwn.fsf@gitster.c.googlers.com>

On Thu, Dec 10, 2020 at 11:47 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 15 quoted lines

>
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
> >> -`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.

OK.

Show 5 quoted lines

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

Right.

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

Sure.

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

OK.

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

Indeed, but the commit message clearly states:

  Our documentation does not mention any future plan to change 'master'
  to other value. It is a good idea to document this, though.

It doesn't say anything about improving the documentation of "git init", nor any of your three points. The main intention is clear.

On top of your three points it sneaks another change; avoiding the "master" branch name. If this really had nothing to do with the "master" branch name, it could very well be sent as a separate independent patch.

The following text has your three valid points, but doesn't sneak in the extra change:

  An initial "master" branch without any commits will be created (see
  the `--initial-branch` option below to choose another name).

Show 6 quoted lines

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

In English parentheses are used to clarify information, and typically it's *supplementary* information. That is; the sentence must stand on its own without them.

This sentence is missing crucial information and it doesn't stand on its own:

  An initial branch without any commits will be created.

This one does stand on its own:

  An initial "master" branch without any commits will be created.

(and doesn't omit any current information.)

Cheers.

-- 
Felipe Contreras