diff mbox series

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

Message ID 483e490349165223a80a0bdf7716c5189560c977.1607637517.git.gitgitgadget@gmail.com (mailing list archive)
State New
Headers show
Series Add helpful advice about init.defaultBranch | expand

Commit Message

Johannes Schindelin Dec. 10, 2020, 9:58 p.m. UTC
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(-)

Comments

Felipe Contreras Dec. 11, 2020, 12:24 a.m. UTC | #1
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.
Junio C Hamano Dec. 11, 2020, 5:47 a.m. UTC | #2
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.

 - 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.
Junio C Hamano Dec. 11, 2020, 5:59 a.m. UTC | #3
Felipe Contreras <felipe.contreras@gmail.com> writes:

> On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget
>
>> +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.

I think we say "this is subject to change" in other places, and I
agree that this part should match to avoid confusing readers,
especially the non-native ones like me.

    If not specified, fall back to the default name (currently
    `master`, but this is subject to change in the future; ...

would be more consistent.
Felipe Contreras Dec. 11, 2020, 6:26 a.m. UTC | #4
On Thu, Dec 10, 2020 at 11:47 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> 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.

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

> > 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.
diff mbox series

Patch

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.
+`refs/tags`, and template files.  An initial branch without any
+commits will be created (see the `--initial-branch` option below
+for its 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
+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).
 
 --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::