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

[Felipe Contreras <felipe.contreras@gmail.com>]

On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> 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).

>  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