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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Dec 11, 2020, 00:24 UTC
Message-ID: <CAMP44s3mtCd9RnZdW7-HLcKVG13UW8u_1VNC0_7jByQRv61+vw@mail.gmail.com>
In-Reply-To: <483e490349165223a80a0bdf7716c5189560c977.1607637517.git.gitgitgadget@gmail.com>

On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 22 quoted lines

>
> From: Johannes Schindelin <johannes.schindelin@gmx.de>
>
> Our documentation does not mention any future plan to change 'master' to
> other value. It is a good idea to document this, though.
>
> Initial-patch-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
> ---
>  Documentation/git-init.txt | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> index 59ecda6c17d..2b399cb73d7 100644
> --- a/Documentation/git-init.txt
> +++ b/Documentation/git-init.txt
> @@ -20,8 +20,9 @@ DESCRIPTION
>
>  This command creates an empty Git repository - basically a `.git`
>  directory with subdirectories for `objects`, `refs/heads`,
> -`refs/tags`, and template files.  An initial `HEAD` file that
> -references the HEAD of the master branch is also created.

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

> +`refs/tags`, and template files.  An initial branch without any
> +commits will be created (see the `--initial-branch` option below
> +for its name).

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

Show 9 quoted lines

>  If the `$GIT_DIR` environment variable is set then it specifies a path
>  to use instead of `./.git` for the base of the repository.
> @@ -73,8 +74,10 @@ If this is reinitialization, the repository will be moved to the specified path.
>  -b <branch-name>::
>  --initial-branch=<branch-name>::
>
> -Use the specified name for the initial branch in the newly created repository.
> -If not specified, fall back to the default name: `master`.
> +Use the specified name for the initial branch in the newly created

Again; the default name has not changed.

> +repository.  If not specified, fall back to the default name (currently
> +`master`, but that will be changed in the future; the name can be customized
> +via the `init.defaultBranch` configuration variable).

Wait a second. The advice warning said "this is subject to change", and the documentation says "that will be changed in the future". Which is it?

"I might give you a fine", and "I will give you a fine" are most definitely not the same thing.

Either say "this is subject to change" in both the documentation and the warning. Or say "that will be changed in the future".

Don't say one thing in one and another thing in the other.

Cheers.

-- 
Felipe Contreras