Re* Keeping the original init.defaultBranch config value

Commit Message

Junio C Hamano Nov. 18, 2020, 5:35 p.m. UTC

Peter Hadlaw <[e-mail]> writes:

> Hello,
>
> Just wanted to confirm that in order to keep new repositories
> initializing with `master` as the default branch the command would be:
>
> ```
> git config --global init.defaultBranch master
> ```

Yes.

If you have to ask the above question, that would mean the
documentation we have right now probably is not clear enough.  

It is understandable, given that our documentation does not mention
any future plan to change 'master' to other value, but it may still
be a good idea.

The following patch is on 'seen' with Dscho's "prepare for main but
do not flip the final switch yet" series.  I am not committed to the
phrasing, but just showing it as a discussion starter.

Thanks.

--- >8 ------ >8 ------ >8 --- cut here --- >8 ------ >8 ---
Subject: "init" doc: mention the configurability more clearly

Update the description for the '--initial-branch' option to mention
that the historical default has been `master` and it can be
configured to use any name.  When actual transition happens to
another fixed name, say 'main', the description would further be
updated to mention like:

	... fall back to the default name 'main', but it can be
	customized with the `init.defaultBranch` configuration
	variable.  Note that the default name historically was
	'master'.

in order to help people who wonder why more mature projects or
documentation tend not to say 'main'.

While we are at it, stop referring to "HEAD file", which was a
remnant from 2005 that talks too much about implementation detail.
The most important fact is that the current branch is set to an
unborn branch and not detached HEAD.

Signed-off-by: Junio C Hamano <[e-mail]>
---
 Documentation/git-init.txt | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

o

Comments

Johannes Schindelin Nov. 22, 2020, 7 p.m. UTC | #1

Hi Junio,

On Wed, 18 Nov 2020, Junio C Hamano wrote:

> --- >8 ------ >8 ------ >8 --- cut here --- >8 ------ >8 ---
> Subject: "init" doc: mention the configurability more clearly
>
> Update the description for the '--initial-branch' option to mention
> that the historical default has been `master` and it can be
> configured to use any name.  When actual transition happens to
> another fixed name, say 'main', the description would further be
> updated to mention like:
>
> 	... fall back to the default name 'main', but it can be
> 	customized with the `init.defaultBranch` configuration
> 	variable.  Note that the default name historically was
> 	'master'.
>
> in order to help people who wonder why more mature projects or
> documentation tend not to say 'main'.
>
> While we are at it, stop referring to "HEAD file", which was a
> remnant from 2005 that talks too much about implementation detail.
> The most important fact is that the current branch is set to an
> unborn branch and not detached HEAD.
>
> Signed-off-by: Junio C Hamano <[e-mail]>
> ---

Just to make sure to mention it: I transmogrified this patch into
https://lore.kernel.org/git/1518[e-mail]/

Thanks,
Dscho

>  Documentation/git-init.txt | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
>
> diff --git i/Documentation/git-init.txt w/Documentation/git-init.txt
> index 59ecda6c17..62c7552a12 100644
> --- i/Documentation/git-init.txt
> +++ w/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 unborn branch (see the
> +`--initial-branch` option below for its name) is made to the current
> +branch.
>
>  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
> +'master', but it can be customized with the `init.defaultBranch`
> +configuration variable.
>
>  --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
>
> o
>

Patch

diff --git i/Documentation/git-init.txt w/Documentation/git-init.txt
index 59ecda6c17..62c7552a12 100644
--- i/Documentation/git-init.txt
+++ w/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 unborn branch (see the
+`--initial-branch` option below for its name) is made to the current
+branch.
 
 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
+'master', but it can be customized with the `init.defaultBranch`
+configuration variable.
 
 --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::