patch, 3 partsget_default_branch_name(): prepare for showing some advice

It is our designated intention [https://sfconservancy.org/news/2020/jun/23/gitbranchname/] to "to explore changing the name of the first branch created automatically for new repositories away from ‘master’". Further, we promised that we "will minimize disruption for Git's users and will include appropriate deprecation periods".

To that end, introduce a message giving advice to users running git init that the fall-back for init.defaultBranch is subject to change, and how to configure it.

The beauty of this patch series, if I may say so, is that it does not commit us to any concrete plan, but opens the door for all options regarding the default branch name.

Johannes Schindelin (3):
  init: document `init.defaultBranch` better
  get_default_branch_name(): prepare for showing some advice
  init: provide useful advice about init.defaultBranch

 Documentation/git-init.txt    | 11 +++++++----
 builtin/clone.c               |  2 +-
 builtin/init-db.c             |  8 +++++---
 refs.c                        | 19 +++++++++++++++----
 refs.h                        |  4 ++--
 remote.c                      |  5 +++--
 t/t0001-init.sh               |  9 ++++++++-
 t/t1510-repo-setup.sh         |  2 +-
 t/t7414-submodule-mistakes.sh |  2 +-
 t/test-lib-functions.sh       |  3 ++-
 10 files changed, 45 insertions(+), 20 deletions(-)

base-commit: faefdd61ec7c7f6f3c8c9907891465ac9a2a1475
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-921%2Fdscho%2Finit.defaultBranch-advice-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-921/dscho/init.defaultBranch-advice-v1
Pull-Request: https://github.com/git/git/pull/921

From: Johannes Schindelin <johannes.schindelin@gmx.de>

We are about to introduce a message giving users running `git init` some advice about `init.defaultBranch`. This will necessarily be done in `repo_default_branch_name()`.

Not all code paths want to show that advice, though. In particular, the `git clone` codepath _specifically_ asks for `init_db()` to be quiet, via the `INIT_DB_QUIET` flag.

In preparation for showing users above-mentioned advice, let's change the function signature of `get_default_branch_name()` to accept the parameter `quiet`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/clone.c   | 2 +-
 builtin/init-db.c | 8 +++++---
 refs.c            | 6 +++---
 refs.h            | 4 ++--
 remote.c          | 5 +++--
 5 files changed, 14 insertions(+), 11 deletions(-)

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

"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes:

It would have been nicer to have a reference to the original patch <xmqqd00a36wc.fsf@gitster.c.googlers.com> here after the three-dash lines, which would have made it easier for me to say that the updated phrasing is much better.

I do not think I deserve credit for this step in the series. Please drop "initial-patch-by" when you do a v2.

"branch without any commits" is certainly easier to understand than "unborn branch", which was in my weatherballoon patch.

Stepping back a bit more, I wonder if we want to make reference to implementation details even less, e.g.

    ... an empty Git repository---a `.git` directory to store
    objects, branches and tags, hooks, and template files.

which would be in the same spirit as not mentioning 'HEAD file'.

s/The/the/ after semicolon that ends a half-sentence. Or alternatively, s/in the future;/in the future./

Hi Junio,

On Sun, 22 Nov 2020, Junio C Hamano wrote:

This is unfortunately not possible with GitGitGadget, which I use because it takes away so much of my burden when contributing patches.

This is not about "deserving". More than half of the patch is still identical to what you wrote, I only pasted it. This is yours, not mine.

Hmm. I'm of two minds there. On the one hand, it is nice to have a conciser description. On the other hand, it is nice to have a little bit depth in the description.

For the time being, I'll leave it as-is.

Okay.

Thanks for the thorough review, Dscho

From: Johannes Schindelin <johannes.schindelin@gmx.de>

To give ample warning in case we decide to change the fall-back for an unconfigured `init.defaultBranch`, let's introduce some advice that is shown upon `git init` when that value is not set.

Note: three test cases in Git's test suite want to verify that the
`stderr` output of `git init` is empty. With this patch, that is only
true if `init.defaultBranch` is configured, so let's do exactly that in
those test cases. The same reasoning applies to `test_create_repo()`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 refs.c                        | 13 ++++++++++++-
 t/t0001-init.sh               |  9 ++++++++-
 t/t1510-repo-setup.sh         |  2 +-
 t/t7414-submodule-mistakes.sh |  2 +-
 t/test-lib-functions.sh       |  3 ++-
 5 files changed, 24 insertions(+), 5 deletions(-)

"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes:

I know this means well.  

I however doubt "ample warning" before we announce an actual decision makes user's life any easier in practice, though. Until they know what it will be changed to (if we decide not to change anything, treat it as changing it to 'master'), they would not be able to decide if the name is more suitable for their use case.

I further suspect that their choice will be influenced the most by the choice made by the projects they most often interact with, and not by our plan.

s/new repositories/all of your new repositories/ as that is the whole point of using --global option below.

It is a bit subtle that this not only tests whatever "git submodule" test it originally wanted to do but also serves as a test that the new advice message is squelched by the presence of the configuration.

I wonder if this should be more like

	-c init.defaultBranch=${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME-master}

so that tests that want a particular branch name would get what they want?

Eventually we would need to do the s/master/X/ if/when the actual default change happens.

Junio C Hamano <gitster@pobox.com> writes:

The above may give a valuable lesson to those who want to use one branch name across new repositories, but it does not tell those who wanted 'trunk' (to match the project, perhaps github.com/cli/cli, with which they intend to interact) how to recover from having already created the 'master' branch. We may want to add some text to suggest "branch -M" after giving the advice for the permanent option.

Also, it is unclear to those who do not have a good <name> in mind (or, those who do not care to choose a <name> for themselves), what <name> they should give to take the "or to silence this warning" part of the advice. It probably is a good idea to rephrase and say either:

    ... To configure ... in all your new repositories and squelch
    this message, run:

	git config --global init.defaultBranch <name>

or

    ... To configure ... in all your new repositories, run:

	git config --global init.defaultBranch <name>

    Note that this message won't appear after doing so.

I am offhand not sure which one is better.

Thanks.

Hi Junio,

On Sun, 22 Nov 2020, Junio C Hamano wrote:

Good point.

Also a good point.

I came up with this, which I intend to submit with v2:

static const char default_branch_name_advice[] = N_( "Using '%s' as the name for the initial branch. This name is subject\n" "to change. To configure the initial branch name to use in all of your\n" "new repositories (or to suppress this warning), run:\n" "\n" "\tgit config --global init.defaultBranch <name>\n" "\n" "Common names are 'main', 'trunk' and 'development'. The initial branch\n" "can be renamed via this command:\n" "\n" "\tgit branch -m <name>\n" );

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

The same issue around "to suppress" is here, though.

It is very likely that the users are on an unborn branch when they see this message and "git branch -m/-M <name>" does not work. We'd probably want to update "git branch" to allow renaming the current branch that is unborn.

In the meantime, you could do "git checkout --orphan <name>" here, but once <name> exists as a branch that would not work, so...

Hi Junio,

On Mon, 23 Nov 2020, Junio C Hamano wrote:

Hmm. I would like to believe that readers understand that setting it to _any_ name would suppress this warning.

Ouch, good point, I had not even realized that that does not work. In v2, I will include a patch that lets it work.

Careful. We should start thinking about phasing out either `checkout` or `switch`. The latter was intended to supersede the former with respect to working on branches, so I would think of phasing out `checkout` and favor `switch` instead.

That issue aside, `git switch --orphan <name>` is not necessarily a good UI here. Its documentation talks about creating a new branch, deleting all tracked files. While it is technically still correct that this command, when run on an unborn branch, does the same as renaming said branch, it is highly unintuitive to think about it that way. ("I don't want to create a new branch, I want to rename the current one! And whoa, delete tracked files? I don't want to delete _any_ files! What do you mean: there aren't any tracked files, so none are deleted? Why do you talk about deleting files, then?")

So in the interest of _reducing_ confusion, I would really, really, _really_ like to avoid mentioning that command in this advice.

It really is much better to make `git branch -m <name>` work in this scenario.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Yes, and the point raised in an earlier messages was that it is not clear that there is no recourse for those who do NOT want to choose but still want to suppress.

Yes, if we can make it work, that is much more preferred.

Hi Junio,

On Sun, 22 Nov 2020, Junio C Hamano wrote:

I reworded the commit message to make the rationale more obvious: the ample warning is to give users a chance to override whatever is Git's default branch name by configuring `init.defaultBranch`. If they care at all.

Makes sense.

Thank you for catching this. It is a debugging left-over.

The real fix for the underlying issue is in the previous commit, which silences the warning when `init_db()` is called via `clone`, as is the case here.

I removed it from v2.

As is custom with our `GIT_TEST_*` variables, `GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME` overrides `init.defaultBranch`.

Therefore, _technically_ what you suggested is not even necessary here.

However, _practically_, what you suggested is very helpful, as it will make it easy to find when (if?) we finish the transition to a new fall-back.

Thank you for your thorough feedback, Dscho

hi dscho,

On 22/11/2020 23:23, Johannes Schindelin via GitGitGadget wrote:

This sounds like Git will change the branch name within the user's repo, rather than "The default" being subject to change.  So maybe s/This/The default/   ?

Philip

Hi Philip,

On Mon, 23 Nov 2020, Philip Oakley wrote:

Yes, that sounds clearer to me. Thank you, Dscho

It is our designated intention [https://sfconservancy.org/news/2020/jun/23/gitbranchname/] to "to explore changing the name of the first branch created automatically for new repositories away from ‘master’". Further, we promised that we "will minimize disruption for Git's users and will include appropriate deprecation periods".

To that end, we first clarify git init's documentation (a lightly edited version of Junio's patch [https://lore.kernel.org/git/xmqqd00a36wc.fsf@gitster.c.googlers.com]), and then introduce a message giving advice to users running git init that the fall-back for init.defaultBranch is subject to change, and how to override Git's fall-back manually.

The beauty of this patch series, if I may say so, is that it does not commit us to any concrete plan, but opens the door for all options regarding the default branch name.

Changes since v1:

 * Grammar fix
 * Reworded advice and commit messages
 * test_create_repo already respected GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME,
   but now does so more obviously
 * Allowed git branch -m <name> to rename unborn branches, so that the
   advice actually works

Johannes Schindelin (4):
  init: document `init.defaultBranch` better
  branch -m: allow renaming a yet-unborn branch
  get_default_branch_name(): prepare for showing some advice
  init: provide useful advice about init.defaultBranch

 Documentation/git-init.txt | 11 +++++++----
 builtin/branch.c           |  3 ++-
 builtin/clone.c            |  2 +-
 builtin/init-db.c          |  8 +++++---
 refs.c                     | 25 +++++++++++++++++++++----
 refs.h                     |  4 ++--
 remote.c                   |  5 +++--
 t/t0001-init.sh            | 15 ++++++++++++++-
 t/t1510-repo-setup.sh      |  2 +-
 t/test-lib-functions.sh    |  3 ++-
 10 files changed, 58 insertions(+), 20 deletions(-)

base-commit: faefdd61ec7c7f6f3c8c9907891465ac9a2a1475
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-921%2Fdscho%2Finit.defaultBranch-advice-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-921/dscho/init.defaultBranch-advice-v2
Pull-Request: https://github.com/git/git/pull/921

Range-diff vs v1:

 1:  1518387eaa ! 1:  483e490349 init: document `init.defaultBranch` better
     @@ Documentation/git-init.txt: If this is reinitialization, the repository will be
      -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
     ++`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)]::
 -:  ---------- > 2:  8de0c0eb22 branch -m: allow renaming a yet-unborn branch
 2:  42f6940043 = 3:  03314f7ac6 get_default_branch_name(): prepare for showing some advice
 3:  253d6706e6 ! 4:  bccef95391 init: provide useful advice about init.defaultBranch
     @@ Metadata
       ## Commit message ##
          init: provide useful advice about init.defaultBranch
      
     -    To give ample warning in case we decide to change the fall-back for an
     -    unconfigured `init.defaultBranch`, let's introduce some advice that is
     -    shown upon `git init` when that value is not set.
     +    To give ample warning for users wishing to override Git's the fall-back
     +    for an unconfigured `init.defaultBranch` (in case we decide to change it
     +    in a future Git version), let's introduce some advice that is shown upon
     +    `git init` when that value is not set.
      
     -    Note: three test cases in Git's test suite want to verify that the
     +    Note: two test cases in Git's test suite want to verify that the
          `stderr` output of `git init` is empty. With this patch, that is only
          true if `init.defaultBranch` is configured, so let's do exactly that in
          those test cases. The same reasoning applies to `test_create_repo()`.
     @@ refs.c: void expand_ref_prefix(struct strvec *prefixes, const char *prefix)
       }
       
      +static const char default_branch_name_advice[] = N_(
     -+"Using '%s' as the name for the initial branch. This name is subject\n"
     -+"to change. To configure the name to use as the initial branch name in\n"
     -+"new repositories, or to silence this warning, run:\n"
     ++"Using '%s' as the name for the initial branch. This default branch name\n"
     ++"is subject to change. To configure the initial branch name to use in all\n"
     ++"of your new repositories, run:\n"
      +"\n"
      +"\tgit config --global init.defaultBranch <name>\n"
     ++"\n"
     ++"Common names are 'main', 'trunk' and 'development'. If you merely wish\n"
     ++"to suppress this warning, you can also use the current default branch\n"
     ++"name. The current branch can be renamed via this command:\n"
     ++"\n"
     ++"\tgit branch -m <name>\n"
      +);
      +
       char *repo_default_branch_name(struct repository *r, int quiet)
     @@ t/t1510-repo-setup.sh: setup_repo () {
       	maybe_config "$name/.git/config" core.bare "$barecfg" &&
       	mkdir -p "$name/sub/sub" &&
      
     - ## t/t7414-submodule-mistakes.sh ##
     -@@ t/t7414-submodule-mistakes.sh: test_expect_success 'no warning when updating entry' '
     - 
     - test_expect_success 'submodule add does not warn' '
     - 	test_when_finished "git rm -rf submodule .gitmodules" &&
     --	git submodule add ./embed submodule 2>stderr &&
     -+	git -c init.defaultBranch=x submodule add ./embed submodule 2>stderr &&
     - 	test_i18ngrep ! warning stderr
     - '
     - 
     -
       ## t/test-lib-functions.sh ##
      @@ t/test-lib-functions.sh: test_create_repo () {
       	mkdir -p "$repo"
     @@ t/test-lib-functions.sh: test_create_repo () {
       		cd "$repo" || error "Cannot setup test environment"
      -		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" init \
      +		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" \
     -+			-c init.defaultBranch=master init \
     ++			-c init.defaultBranch=${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME-master} init \
       			"--template=$GIT_BUILD_DIR/templates/blt/" >&3 2>&4 ||
       		error "cannot run git init -- have you built things yet?"
       		mv .git/hooks .git/hooks-disabled

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

From: Johannes Schindelin <johannes.schindelin@gmx.de>

We are about to introduce a message giving users running `git init` some advice about `init.defaultBranch`. This will necessarily be done in `repo_default_branch_name()`.

Not all code paths want to show that advice, though. In particular, the `git clone` codepath _specifically_ asks for `init_db()` to be quiet, via the `INIT_DB_QUIET` flag.

In preparation for showing users above-mentioned advice, let's change the function signature of `get_default_branch_name()` to accept the parameter `quiet`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/clone.c   | 2 +-
 builtin/init-db.c | 8 +++++---
 refs.c            | 6 +++---
 refs.h            | 4 ++--
 remote.c          | 5 +++--
 5 files changed, 14 insertions(+), 11 deletions(-)

From: Johannes Schindelin <johannes.schindelin@gmx.de>

In one of the next commits, we would like to give users some advice regarding the initial branch name, and how to modify it.

To that end, it would be good if `git branch -m <name>` worked in a freshly initialized repository without any commits. Let's make it so.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/branch.c | 3 ++-
 t/t0001-init.sh  | 6 ++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes:

It always makes readers uneasy to see pointer comparison of two strings.

Does this mean, after "git -c init.defaultbranch=master init",

	git branch -m master main

would not work while

	git branch -m main

would? It would be easy to see with the attached patch to the test, I guess.

Thanks.

 t/t0001-init.sh | 6 ++++++
 1 file changed, 6 insertions(+)

Hi Junio,

On Mon, 23 Nov 2020, Junio C Hamano wrote:

Even if it was on purpose ;-)

At first, I thought that it would be inappropriate to do that because it would not work with unborn branches in a worktree other than the current one. Like,

	git worktree add --no-checkout --detach other
	git -C other switch --orphan start-over-again
	git branch -m start-over-again fresh-new-start

On second thought, that's a really obscure use case, anyway. It is not even possible to create a secondary worktree! I started down that rabbit hole, but think I'd better let it be. This is where I stopped:

-- snip --

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

FWIW, for fun I dropped "oldname != head ||" and tried to run the whole testsuite (plus the "branch -m src dst" form test I gave earlier), and it almost passed all of them except one, which was surprising.

Yeah, a helper function makes it much more clear what is going on.

;-)

From: Johannes Schindelin <johannes.schindelin@gmx.de>

To give ample warning for users wishing to override Git's the fall-back for an unconfigured `init.defaultBranch` (in case we decide to change it in a future Git version), let's introduce some advice that is shown upon `git init` when that value is not set.

Note: two test cases in Git's test suite want to verify that the
`stderr` output of `git init` is empty. With this patch, that is only
true if `init.defaultBranch` is configured, so let's do exactly that in
those test cases. The same reasoning applies to `test_create_repo()`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 refs.c                  | 19 ++++++++++++++++++-
 t/t0001-init.sh         |  9 ++++++++-
 t/t1510-repo-setup.sh   |  2 +-
 t/test-lib-functions.sh |  3 ++-
 4 files changed, 29 insertions(+), 4 deletions(-)

"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes:

I think this is good, assuming that "subject to change" covers the case where we end up doing nothing after all. I'd feel safer if we said "s/is subject to change/may change in the future/", but this is not a strong preference.

I think this is worse than the previous one. Those who merely wish to suppress the message without wanting to commit to a particular name (i.e. they just want to take whatever the default we give them) would be mislead and be frozen in time forever. We do not give "I'll just accept the default of the day" choice, and that is OK, but we want to be clear about it, which is why I've kept raising this as an issue.

    To configure the initial branch name to use in all of your new
    repositories and squelch this message, run:

may be better---it makes it clear that the offered two choices are (1) do nothing and see this message every time, or (2) commit to a name and not see this message again.

Thanks.

Hi Junio,

On Mon, 23 Nov 2020, Junio C Hamano wrote:

I'd rather keep the current form, as it sounds a bit more firm to me.

Well, I think I finally understand what you are saying: there is a legitimate need for a way to go with Git's preference but still suppress that message.

I introduced `advice.defaultBranchName` to that end, and now display prominently, at the top of the message, how to use that flag to avoid seeing this advice ever again.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

I am not saying it is a legitimate need. I just wanted to make it clear that we deliberately chose not to grant that wish in the message. An advice flag in this context means that the users can choose to let their distro and sysadm to flip the default silently, which is much worse than having to see the message every time they start a new repository with "git init".

Hi Junio,

On Tue, 24 Nov 2020, Junio C Hamano wrote:

The distribution already can add patches, so this objection is a red herring. The sysadm can pick a different value for `init.defaultBranch` and dictate to the user silently what initial branch name to use, so that is also a red herring.

I still think that there is a legitimate need for this config option to turn the advice off, without having to override Git's default branch name.

In particular in this context, I would think that most users will want to just go with whatever is Git's default.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

The "setting init.defaultBranch is the only way to squelch" approach means the ~/.gitconfig will have the settings soon after the user starts using Git and /etc/gitconfig will not allow administrators to force their will over what the user decides to use. Distros adding patches to strip configurability by setting init.defaultBranch in user's ~/.gitconfig? Is that the kind of possibilities worth discussing?

So, no, your counter-argument above is nothing but a red-herring.

If you want a counter-argument, please explain why "I am fine to see the default flipped to whatever the tool picks and having no control over when the flipping happens" can be a sensible choice for users with what kind of workflows. The only folks I can think of who would be fine with that are (1) those who do not create the second branch in the repository and will stay on the primary branch forever, and (2) those who immediately rename the branch to what they want after "git init". For other folks, such a choice is a disaster waiting to happen, and it just feels irresponsible to offer such a choice, at least to me.

Thanks.

Hi Junio,

On Wed, 9 Dec 2020, Junio C Hamano wrote:

I'll make this short.

I talked to a couple Git users whether they'd be fine if `git init` used a different branch name by default, and everybody I asked said essentially "yeah, whatever, I don't really care".

For that reason, Git for Windows' installer has that option, and will keep offering it.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Yeah, I would expect that, too. They would not have asked about the details on when that switchover of the default would happen, and would not have been told that the timing is not under their control. I would answer to such a question with "yeah, whatever." that does not give you an assurance that I won't complain when the switchover actually happens ;-).

On Wed, Dec 9, 2020 at 5:24 PM Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

Yes, but if they do; they have picked the ball. The user would blame them--and not Git--for any unexpected change in behavior.

Cheers.

It is our designated intention [https://sfconservancy.org/news/2020/jun/23/gitbranchname/] to "to explore changing the name of the first branch created automatically for new repositories away from ‘master’". Further, we promised that we "will minimize disruption for Git's users and will include appropriate deprecation periods".

To that end, we first clarify git init's documentation (a lightly edited version of Junio's patch [https://lore.kernel.org/git/xmqqd00a36wc.fsf@gitster.c.googlers.com]), and then introduce a message giving advice to users running git init that the fall-back for init.defaultBranch is subject to change, and how to override Git's fall-back manually.

The beauty of this patch series, if I may say so, is that it does not commit us to any concrete plan, but opens the door for all options regarding the default branch name.

Changes since v2:

 * git branch -m <initial> <renamed> now works, too
 * The config setting advice.defaultBranchName was introduced to allow
   suppressing this warning specifically
 * The advice now first talks about the current default branch name, then
   how to suppress the advice, and only then explains how to override the
   default branch name (and that that will also prevent the message from
   being shown)

Changes since v1:

 * Grammar fix
 * Reworded advice and commit messages
 * test_create_repo already respected GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME,
   but now does so more obviously
 * Allowed git branch -m <name> to rename unborn branches, so that the
   advice actually works

Johannes Schindelin (4):
  init: document `init.defaultBranch` better
  branch -m: allow renaming a yet-unborn branch
  get_default_branch_name(): prepare for showing some advice
  init: provide useful advice about init.defaultBranch

 Documentation/git-init.txt | 11 +++++++----
 advice.c                   |  1 +
 advice.h                   |  1 +
 builtin/branch.c           |  4 +++-
 builtin/clone.c            |  2 +-
 builtin/init-db.c          |  8 +++++---
 refs.c                     | 29 +++++++++++++++++++++++++----
 refs.h                     |  4 ++--
 remote.c                   |  5 +++--
 t/t0001-init.sh            | 17 ++++++++++++++++-
 t/t1510-repo-setup.sh      |  2 +-
 t/test-lib-functions.sh    |  3 ++-
 12 files changed, 67 insertions(+), 20 deletions(-)

base-commit: faefdd61ec7c7f6f3c8c9907891465ac9a2a1475
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-921%2Fdscho%2Finit.defaultBranch-advice-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-921/dscho/init.defaultBranch-advice-v3
Pull-Request: https://github.com/git/git/pull/921

Range-diff vs v2:

 1:  483e490349 = 1:  483e490349 init: document `init.defaultBranch` better
 2:  8de0c0eb22 ! 2:  6cbd6692c6 branch -m: allow renaming a yet-unborn branch
     @@ builtin/branch.c: static void copy_or_rename_branch(const char *oldname, const c
       			    oldref.buf, newref.buf);
       
      -	if (!copy && rename_ref(oldref.buf, newref.buf, logmsg.buf))
     -+	if (!copy && (oldname != head || !is_null_oid(&head_oid)) &&
     ++	if (!copy &&
     ++	    (!head || strcmp(oldname, head) || !is_null_oid(&head_oid)) &&
      +	    rename_ref(oldref.buf, newref.buf, logmsg.buf))
       		die(_("Branch rename failed"));
       	if (copy && copy_existing_ref(oldref.buf, newref.buf, logmsg.buf))
     @@ t/t0001-init.sh: test_expect_success 'invalid default branch name' '
       '
       
      +test_expect_success 'branch -m with the initial branch' '
     -+	git init rename-initial-branch &&
     -+	git -C rename-initial-branch branch -m renamed &&
     -+	test renamed = $(git -C rename-initial-branch symbolic-ref --short HEAD)
     ++	git init rename-initial &&
     ++	git -C rename-initial branch -m renamed &&
     ++	test renamed = $(git -C rename-initial symbolic-ref --short HEAD) &&
     ++	git -C rename-initial branch -m renamed again &&
     ++	test again = $(git -C rename-initial symbolic-ref --short HEAD)
      +'
      +
       test_done
 3:  03314f7ac6 = 3:  5fc15f7b9a get_default_branch_name(): prepare for showing some advice
 4:  bccef95391 ! 4:  87c9306877 init: provide useful advice about init.defaultBranch
     @@ Commit message
          `git init` when that value is not set.
      
          Note: two test cases in Git's test suite want to verify that the
     -    `stderr` output of `git init` is empty. With this patch, that is only
     -    true if `init.defaultBranch` is configured, so let's do exactly that in
     -    those test cases. The same reasoning applies to `test_create_repo()`.
     +    `stderr` output of `git init` is empty. It is now necessary to suppress
     +    the advice using the newly-added `advice.defaultBranchName` setting.
     +    While not strictly necessary, we also set this to `false` in
     +    `test_create_repo()`.
      
          Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
      
     + ## advice.c ##
     +@@ advice.c: static struct {
     + 	[ADVICE_AM_WORK_DIR] 				= { "amWorkDir", 1 },
     + 	[ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME] 	= { "checkoutAmbiguousRemoteBranchName", 1 },
     + 	[ADVICE_COMMIT_BEFORE_MERGE]			= { "commitBeforeMerge", 1 },
     ++	[ADVICE_DEFAULT_BRANCH_NAME]			= { "defaultBranchName", 1 },
     + 	[ADVICE_DETACHED_HEAD]				= { "detachedHead", 1 },
     + 	[ADVICE_FETCH_SHOW_FORCED_UPDATES]		= { "fetchShowForcedUpdates", 1 },
     + 	[ADVICE_GRAFT_FILE_DEPRECATED]			= { "graftFileDeprecated", 1 },
     +
     + ## advice.h ##
     +@@ advice.h: extern int advice_add_empty_pathspec;
     + 	ADVICE_AM_WORK_DIR,
     + 	ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
     + 	ADVICE_COMMIT_BEFORE_MERGE,
     ++	ADVICE_DEFAULT_BRANCH_NAME,
     + 	ADVICE_DETACHED_HEAD,
     + 	ADVICE_FETCH_SHOW_FORCED_UPDATES,
     + 	ADVICE_GRAFT_FILE_DEPRECATED,
     +
       ## refs.c ##
     +@@
     + #include "strvec.h"
     + #include "repository.h"
     + #include "sigchain.h"
     ++#include "advice.h"
     + 
     + /*
     +  * List of all available backends
      @@ refs.c: void expand_ref_prefix(struct strvec *prefixes, const char *prefix)
       		strvec_pushf(prefixes, *p, len, prefix);
       }
       
      +static const char default_branch_name_advice[] = N_(
      +"Using '%s' as the name for the initial branch. This default branch name\n"
     -+"is subject to change. To configure the initial branch name to use in all\n"
     -+"of your new repositories, run:\n"
     ++"is subject to change. To suppress this warning, run:\n"
     ++"\n"
     ++"\tgit config --global advice.defaultBranchName false\n"
     ++"\n"
     ++"Alternatively, you can configure the initial branch name to use in all\n"
     ++"of your new repositories, which will also suppress this warning:\n"
      +"\n"
      +"\tgit config --global init.defaultBranch <name>\n"
      +"\n"
     -+"Common names are 'main', 'trunk' and 'development'. If you merely wish\n"
     -+"to suppress this warning, you can also use the current default branch\n"
     -+"name. The current branch can be renamed via this command:\n"
     ++"Common names are 'main', 'trunk' and 'development'. The initial branch\n"
     ++"that was created can be renamed via this command:\n"
      +"\n"
      +"\tgit branch -m <name>\n"
      +);
     @@ refs.c: char *repo_default_branch_name(struct repository *r, int quiet)
      -	if (!ret)
      +	if (!ret) {
       		ret = xstrdup("master");
     -+		if (!quiet)
     ++		if (!quiet && advice_enabled(ADVICE_DEFAULT_BRANCH_NAME))
      +			advise(_(default_branch_name_advice), ret);
      +	}
       
     @@ t/t0001-init.sh: test_expect_success 'reinit' '
       		mkdir again &&
       		cd again &&
      -		git init >out1 2>err1 &&
     -+		git -c init.defaultBranch=initial init >out1 2>err1 &&
     ++		git -c advice.defaultBranchName=false init >out1 2>err1 &&
       		git init >out2 2>err2
       	) &&
       	test_i18ngrep "Initialized empty" again/out1 &&
     @@ t/t1510-repo-setup.sh: setup_repo () {
       	sane_unset GIT_DIR GIT_WORK_TREE &&
       
      -	git init "$name" &&
     -+	git -c init.defaultBranch=repo init "$name" &&
     ++	git -c advice.defaultBranchName=false init "$name" &&
       	maybe_config "$name/.git/config" core.worktree "$worktreecfg" &&
       	maybe_config "$name/.git/config" core.bare "$barecfg" &&
       	mkdir -p "$name/sub/sub" &&
     @@ t/test-lib-functions.sh: test_create_repo () {
       		cd "$repo" || error "Cannot setup test environment"
      -		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" init \
      +		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" \
     -+			-c init.defaultBranch=${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME-master} init \
     ++			-c advice.defaultBranchName=false init \
       			"--template=$GIT_BUILD_DIR/templates/blt/" >&3 2>&4 ||
       		error "cannot run git init -- have you built things yet?"
       		mv .git/hooks .git/hooks-disabled

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

From: Johannes Schindelin <johannes.schindelin@gmx.de>

To give ample warning for users wishing to override Git's the fall-back for an unconfigured `init.defaultBranch` (in case we decide to change it in a future Git version), let's introduce some advice that is shown upon `git init` when that value is not set.

Note: two test cases in Git's test suite want to verify that the
`stderr` output of `git init` is empty. It is now necessary to suppress
the advice using the newly-added `advice.defaultBranchName` setting.
While not strictly necessary, we also set this to `false` in
`test_create_repo()`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 advice.c                |  1 +
 advice.h                |  1 +
 refs.c                  | 23 ++++++++++++++++++++++-
 t/t0001-init.sh         |  9 ++++++++-
 t/t1510-repo-setup.sh   |  2 +-
 t/test-lib-functions.sh |  3 ++-
 6 files changed, 35 insertions(+), 4 deletions(-)

From: Johannes Schindelin <johannes.schindelin@gmx.de>

In one of the next commits, we would like to give users some advice regarding the initial branch name, and how to modify it.

To that end, it would be good if `git branch -m <name>` worked in a freshly initialized repository without any commits. Let's make it so.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/branch.c | 4 +++-
 t/t0001-init.sh  | 8 ++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

From: Johannes Schindelin <johannes.schindelin@gmx.de>

We are about to introduce a message giving users running `git init` some advice about `init.defaultBranch`. This will necessarily be done in `repo_default_branch_name()`.

Not all code paths want to show that advice, though. In particular, the `git clone` codepath _specifically_ asks for `init_db()` to be quiet, via the `INIT_DB_QUIET` flag.

In preparation for showing users above-mentioned advice, let's change the function signature of `get_default_branch_name()` to accept the parameter `quiet`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/clone.c   | 2 +-
 builtin/init-db.c | 8 +++++---
 refs.c            | 6 +++---
 refs.h            | 4 ++--
 remote.c          | 5 +++--
 5 files changed, 14 insertions(+), 11 deletions(-)

It is our designated intention [https://sfconservancy.org/news/2020/jun/23/gitbranchname/] to "to explore changing the name of the first branch created automatically for new repositories away from ‘master’". Further, we promised that we "will minimize disruption for Git's users and will include appropriate deprecation periods".

To that end, we first clarify git init's documentation (a lightly edited version of Junio's patch [https://lore.kernel.org/git/xmqqd00a36wc.fsf@gitster.c.googlers.com]), and then introduce a message giving advice to users running git init that the fall-back for init.defaultBranch is subject to change, and how to override Git's fall-back manually.

The beauty of this patch series, if I may say so, is that it does not commit us to any concrete plan, but opens the door for all options regarding the default branch name.

Changes since v3:

 * Kicked out advice.defaultBranchName again. The advice can now only be
   suppressed by setting init.defaultBranch.

Changes since v2:

 * git branch -m <initial> <renamed> now works, too
 * The config setting advice.defaultBranchName was introduced to allow
   suppressing this warning specifically
 * The advice now first talks about the current default branch name, then
   how to suppress the advice, and only then explains how to override the
   default branch name (and that that will also prevent the message from
   being shown)

Changes since v1:

 * Grammar fix
 * Reworded advice and commit messages
 * test_create_repo already respected GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME,
   but now does so more obviously
 * Allowed git branch -m <name> to rename unborn branches, so that the
   advice actually works

Johannes Schindelin (4):
  init: document `init.defaultBranch` better
  branch -m: allow renaming a yet-unborn branch
  get_default_branch_name(): prepare for showing some advice
  init: provide useful advice about init.defaultBranch

 Documentation/git-init.txt | 11 +++++++----
 builtin/branch.c           |  4 +++-
 builtin/clone.c            |  2 +-
 builtin/init-db.c          |  8 +++++---
 refs.c                     | 24 ++++++++++++++++++++----
 refs.h                     |  4 ++--
 remote.c                   |  5 +++--
 t/t0001-init.sh            | 17 ++++++++++++++++-
 t/t1510-repo-setup.sh      |  2 +-
 t/test-lib-functions.sh    |  4 +++-
 10 files changed, 61 insertions(+), 20 deletions(-)

base-commit: faefdd61ec7c7f6f3c8c9907891465ac9a2a1475
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-921%2Fdscho%2Finit.defaultBranch-advice-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-921/dscho/init.defaultBranch-advice-v4
Pull-Request: https://github.com/git/git/pull/921

Range-diff vs v3:

 1:  483e4903491 = 1:  483e4903491 init: document `init.defaultBranch` better
 2:  6cbd6692c6a = 2:  6cbd6692c6a branch -m: allow renaming a yet-unborn branch
 3:  5fc15f7b9ad = 3:  5fc15f7b9ad get_default_branch_name(): prepare for showing some advice
 4:  87c93068771 ! 4:  2f21c505d56 init: provide useful advice about init.defaultBranch
     @@ Commit message
      
          Note: two test cases in Git's test suite want to verify that the
          `stderr` output of `git init` is empty. It is now necessary to suppress
     -    the advice using the newly-added `advice.defaultBranchName` setting.
     -    While not strictly necessary, we also set this to `false` in
     +    the advice, we now do that via the `init.defaultBranch` setting. While
     +    not strictly necessary, we also set this to `false` in
          `test_create_repo()`.
      
          Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
      
     - ## advice.c ##
     -@@ advice.c: static struct {
     - 	[ADVICE_AM_WORK_DIR] 				= { "amWorkDir", 1 },
     - 	[ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME] 	= { "checkoutAmbiguousRemoteBranchName", 1 },
     - 	[ADVICE_COMMIT_BEFORE_MERGE]			= { "commitBeforeMerge", 1 },
     -+	[ADVICE_DEFAULT_BRANCH_NAME]			= { "defaultBranchName", 1 },
     - 	[ADVICE_DETACHED_HEAD]				= { "detachedHead", 1 },
     - 	[ADVICE_FETCH_SHOW_FORCED_UPDATES]		= { "fetchShowForcedUpdates", 1 },
     - 	[ADVICE_GRAFT_FILE_DEPRECATED]			= { "graftFileDeprecated", 1 },
     -
     - ## advice.h ##
     -@@ advice.h: extern int advice_add_empty_pathspec;
     - 	ADVICE_AM_WORK_DIR,
     - 	ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
     - 	ADVICE_COMMIT_BEFORE_MERGE,
     -+	ADVICE_DEFAULT_BRANCH_NAME,
     - 	ADVICE_DETACHED_HEAD,
     - 	ADVICE_FETCH_SHOW_FORCED_UPDATES,
     - 	ADVICE_GRAFT_FILE_DEPRECATED,
     -
       ## refs.c ##
     -@@
     - #include "strvec.h"
     - #include "repository.h"
     - #include "sigchain.h"
     -+#include "advice.h"
     - 
     - /*
     -  * List of all available backends
      @@ refs.c: void expand_ref_prefix(struct strvec *prefixes, const char *prefix)
       		strvec_pushf(prefixes, *p, len, prefix);
       }
       
      +static const char default_branch_name_advice[] = N_(
      +"Using '%s' as the name for the initial branch. This default branch name\n"
     -+"is subject to change. To suppress this warning, run:\n"
     -+"\n"
     -+"\tgit config --global advice.defaultBranchName false\n"
     -+"\n"
     -+"Alternatively, you can configure the initial branch name to use in all\n"
     -+"of your new repositories, which will also suppress this warning:\n"
     ++"is subject to change. To configure the initial branch name to use in all\n"
     ++"of your new repositories, which will suppress this warning, call:\n"
      +"\n"
      +"\tgit config --global init.defaultBranch <name>\n"
      +"\n"
     @@ refs.c: char *repo_default_branch_name(struct repository *r, int quiet)
      -	if (!ret)
      +	if (!ret) {
       		ret = xstrdup("master");
     -+		if (!quiet && advice_enabled(ADVICE_DEFAULT_BRANCH_NAME))
     ++		if (!quiet)
      +			advise(_(default_branch_name_advice), ret);
      +	}
       
     @@ t/t0001-init.sh: test_expect_success 'reinit' '
       		mkdir again &&
       		cd again &&
      -		git init >out1 2>err1 &&
     -+		git -c advice.defaultBranchName=false init >out1 2>err1 &&
     ++		git -c init.defaultBranch=initial init >out1 2>err1 &&
       		git init >out2 2>err2
       	) &&
       	test_i18ngrep "Initialized empty" again/out1 &&
     @@ t/t1510-repo-setup.sh: setup_repo () {
       	sane_unset GIT_DIR GIT_WORK_TREE &&
       
      -	git init "$name" &&
     -+	git -c advice.defaultBranchName=false init "$name" &&
     ++	git -c init.defaultBranch=initial init "$name" &&
       	maybe_config "$name/.git/config" core.worktree "$worktreecfg" &&
       	maybe_config "$name/.git/config" core.bare "$barecfg" &&
       	mkdir -p "$name/sub/sub" &&
     @@ t/test-lib-functions.sh: test_create_repo () {
       	(
       		cd "$repo" || error "Cannot setup test environment"
      -		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" init \
     -+		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" \
     -+			-c advice.defaultBranchName=false init \
     ++		"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" -c \
     ++			init.defaultBranch="${GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME-master}" \
     ++			init \
       			"--template=$GIT_BUILD_DIR/templates/blt/" >&3 2>&4 ||
       		error "cannot run git init -- have you built things yet?"
       		mv .git/hooks .git/hooks-disabled

From: Johannes Schindelin <johannes.schindelin@gmx.de>

To give ample warning for users wishing to override Git's the fall-back for an unconfigured `init.defaultBranch` (in case we decide to change it in a future Git version), let's introduce some advice that is shown upon `git init` when that value is not set.

Note: two test cases in Git's test suite want to verify that the
`stderr` output of `git init` is empty. It is now necessary to suppress
the advice, we now do that via the `init.defaultBranch` setting. While
not strictly necessary, we also set this to `false` in
`test_create_repo()`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 refs.c                  | 18 +++++++++++++++++-
 t/t0001-init.sh         |  9 ++++++++-
 t/t1510-repo-setup.sh   |  2 +-
 t/test-lib-functions.sh |  4 +++-
 4 files changed, 29 insertions(+), 4 deletions(-)

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

This is disingenuous; the most common name is "master"... by far. In a couple years this might change, but not right now.

If you don't want to mention "master", then don't mention "common names" that are not really the most common names.

Cheers.

Felipe Contreras <felipe.contreras@gmail.com> writes:

Names commonly chosen by those who want to move away from 'master' are...

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

But we don't want to spill drama into the user interface.

I think the vast majority of users haven't heard of this drama. Just like the vast majority of users had not heard of the git-foo obsoletion even after several years. Our vantage point is skewed for being too close to Git development.

Those users will ask: "who wants to move away from 'master'?"

If we don't presume our users have the same knowledge as us, we have to explain:

  Names commonly chosen by those who want to move away from 'master'
  are; 'main', 'trunk', and 'development'. For more information read
  this post:
  https://dev.to/rhymu8354/git-renaming-the-master-branch-137b.

I say don't. If the user wants to know why anyone would want to change "the default branch name", she can google it and find out.

Cheer.

Hi Junio,

On Thu, 10 Dec 2020, Junio C Hamano wrote:

"those who want to move away" sounds a bit too non-committal for my liking. So I changed it to:

	Names commonly chosen instead of 'master' are 'main', 'trunk'
	and 'development'.

While at it, I also improved the next sentence:

	 The just-created branch can be renamed via this command:

Ciao, Dscho

From: Johannes Schindelin <johannes.schindelin@gmx.de>

In one of the next commits, we would like to give users some advice regarding the initial branch name, and how to modify it.

To that end, it would be good if `git branch -m <name>` worked in a freshly initialized repository without any commits. Let's make it so.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/branch.c | 4 +++-
 t/t0001-init.sh  | 8 ++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

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

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

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

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

Again; the default name has not changed.

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

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.

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.

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

OK.

Right.

Sure.

OK.

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

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

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.

From: Johannes Schindelin <johannes.schindelin@gmx.de>

We are about to introduce a message giving users running `git init` some advice about `init.defaultBranch`. This will necessarily be done in `repo_default_branch_name()`.

Not all code paths want to show that advice, though. In particular, the `git clone` codepath _specifically_ asks for `init_db()` to be quiet, via the `INIT_DB_QUIET` flag.

In preparation for showing users above-mentioned advice, let's change the function signature of `get_default_branch_name()` to accept the parameter `quiet`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/clone.c   | 2 +-
 builtin/init-db.c | 8 +++++---
 refs.c            | 6 +++---
 refs.h            | 4 ++--
 remote.c          | 5 +++--
 5 files changed, 14 insertions(+), 11 deletions(-)

It is our designated intention [https://sfconservancy.org/news/2020/jun/23/gitbranchname/] to "to explore changing the name of the first branch created automatically for new repositories away from ‘master’". Further, we promised that we "will minimize disruption for Git's users and will include appropriate deprecation periods".

To that end, we first clarify git init's documentation (a lightly edited version of Junio's patch [https://lore.kernel.org/git/xmqqd00a36wc.fsf@gitster.c.googlers.com]), and then introduce a message giving advice to users running git init that the fall-back for init.defaultBranch is subject to change, and how to override Git's fall-back manually.

The beauty of this patch series, if I may say so, is that it does not commit us to any concrete plan, but opens the door for all options regarding the default branch name.

Changes since v4:

 * Reworded the documentation to weaken the "will be changed in the future"
   to "is subject to change".
 * Reworded the advice to explicitly mention "instead of 'master'".

Changes since v3:

 * Kicked out advice.defaultBranchName again. The advice can now only be
   suppressed by setting init.defaultBranch.

Changes since v2:

 * git branch -m <initial> <renamed> now works, too
 * The config setting advice.defaultBranchName was introduced to allow
   suppressing this warning specifically
 * The advice now first talks about the current default branch name, then
   how to suppress the advice, and only then explains how to override the
   default branch name (and that that will also prevent the message from
   being shown)

Changes since v1:

 * Grammar fix
 * Reworded advice and commit messages
 * test_create_repo already respected GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME,
   but now does so more obviously
 * Allowed git branch -m <name> to rename unborn branches, so that the
   advice actually works

Johannes Schindelin (4):
  init: document `init.defaultBranch` better
  branch -m: allow renaming a yet-unborn branch
  get_default_branch_name(): prepare for showing some advice
  init: provide useful advice about init.defaultBranch

 Documentation/git-init.txt | 11 +++++++----
 builtin/branch.c           |  4 +++-
 builtin/clone.c            |  2 +-
 builtin/init-db.c          |  8 +++++---
 refs.c                     | 24 ++++++++++++++++++++----
 refs.h                     |  4 ++--
 remote.c                   |  5 +++--
 t/t0001-init.sh            | 17 ++++++++++++++++-
 t/t1510-repo-setup.sh      |  2 +-
 t/test-lib-functions.sh    |  4 +++-
 10 files changed, 61 insertions(+), 20 deletions(-)

base-commit: faefdd61ec7c7f6f3c8c9907891465ac9a2a1475
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-921%2Fdscho%2Finit.defaultBranch-advice-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-921/dscho/init.defaultBranch-advice-v5
Pull-Request: https://github.com/git/git/pull/921

Range-diff vs v4:

 1:  483e4903491 ! 1:  ce35cf3da65 init: document `init.defaultBranch` better
     @@ Documentation/git-init.txt: If this is reinitialization, the repository will be
      -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).
     ++`master`, but this is subject to change in the future; the name can be
     ++customized via the `init.defaultBranch` configuration variable).
       
       --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
       
 2:  6cbd6692c6a = 2:  ac7b352a0ba branch -m: allow renaming a yet-unborn branch
 3:  5fc15f7b9ad = 3:  aba72340c87 get_default_branch_name(): prepare for showing some advice
 4:  2f21c505d56 ! 4:  ce26446b1a2 init: provide useful advice about init.defaultBranch
     @@ refs.c: void expand_ref_prefix(struct strvec *prefixes, const char *prefix)
      +"\n"
      +"\tgit config --global init.defaultBranch <name>\n"
      +"\n"
     -+"Common names are 'main', 'trunk' and 'development'. The initial branch\n"
     -+"that was created can be renamed via this command:\n"
     ++"Names commonly chosen instead of 'master' are 'main', 'trunk' and\n"
     ++"'development'. The just-created branch can be renamed via this command:\n"
      +"\n"
      +"\tgit branch -m <name>\n"
      +);

From: Johannes Schindelin <johannes.schindelin@gmx.de>

In one of the next commits, we would like to give users some advice regarding the initial branch name, and how to modify it.

To that end, it would be good if `git branch -m <name>` worked in a freshly initialized repository without any commits. Let's make it so.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/branch.c | 4 +++-
 t/t0001-init.sh  | 8 ++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

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

From: Johannes Schindelin <johannes.schindelin@gmx.de>

We are about to introduce a message giving users running `git init` some advice about `init.defaultBranch`. This will necessarily be done in `repo_default_branch_name()`.

Not all code paths want to show that advice, though. In particular, the `git clone` codepath _specifically_ asks for `init_db()` to be quiet, via the `INIT_DB_QUIET` flag.

In preparation for showing users above-mentioned advice, let's change the function signature of `get_default_branch_name()` to accept the parameter `quiet`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 builtin/clone.c   | 2 +-
 builtin/init-db.c | 8 +++++---
 refs.c            | 6 +++---
 refs.h            | 4 ++--
 remote.c          | 5 +++--
 5 files changed, 14 insertions(+), 11 deletions(-)

From: Johannes Schindelin <johannes.schindelin@gmx.de>

To give ample warning for users wishing to override Git's the fall-back for an unconfigured `init.defaultBranch` (in case we decide to change it in a future Git version), let's introduce some advice that is shown upon `git init` when that value is not set.

Note: two test cases in Git's test suite want to verify that the
`stderr` output of `git init` is empty. It is now necessary to suppress
the advice, we now do that via the `init.defaultBranch` setting. While
not strictly necessary, we also set this to `false` in
`test_create_repo()`.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 refs.c                  | 18 +++++++++++++++++-
 t/t0001-init.sh         |  9 ++++++++-
 t/t1510-repo-setup.sh   |  2 +-
 t/test-lib-functions.sh |  4 +++-
 4 files changed, 29 insertions(+), 4 deletions(-)

On Fri, Dec 11, 2020 at 11:36:57AM +0000, Johannes Schindelin via GitGitGadget wrote:

This breaks GIT_TEST_INSTALLED when the given Git version doesn't yet contain 8b1fa77867 (Allow passing of configuration parameters in the command line, 2010-03-26):

  $ GIT_TEST_INSTALLED=.../v1.6.0/bin/ ./t9999-test.sh -x
  Unknown option: -c
  usage: git [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate|--no-pager] [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] [--help] COMMAND [ARGS]
  error: cannot run git init -- have you built things yet?

SZEDER Gábor <szeder.dev@gmail.com> writes:

Yes, but test-installed is about running an old version of Git on the current Git test suite. In the tests we make liberal use of "git -c <var>=<val>", which such an old version of Git has no chance of passing. So...

On Tue, Feb 02, 2021 at 02:25:01PM -0800, Junio C Hamano wrote:

I've never run the whole test suite with GIT_TEST_INSTALLED for the exact reason you mentioned. However, I do regularly use it with custom tests using only commands and options that already existed as early as v1.6.0 (my go-to "old" version) to check when some interesting or puzzling behavior appeared, and did just that yesterday as well.