Allow overriding the default name of the default branch

A growing number of open source projects aims to avoid the branch name master due to its negative connotation. See [1] for an existing discussion on this. The links [2], [3], and [4] describe community-driven ways for users to rename their default branches or use template edits to set a new default branch name.

[1]
https://lore.kernel.org/git/CAOAHyQwyXC1Z3v7BZAC+Bq6JBaM7FvBenA-1fcqeDV==apdWDg@mail.gmail.com/

[2] https://twitter.com/mislav/status/1270388510684598272

[3]
https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx

[4] https://github.com/ethomson/retarget_prs

By necessity, existing repositories require a lot of manual work to move away from that branch name, but it should be much easier for new repositories.

This patch series allows overriding the branch name being used for new repositories' main branch. The main way to do this is the new core.defaultBranchName config option. This first patch was contributed by newcomer Dan Goodman-Wilson. Thanks for the contribution!

The other patches follow other places where "master" is hard-coded and use the new git_default_branch_name() method to consume the config option before falling back to "master".

The last patch updates documentation only after the config option is ready to apply to all of these scenarios.

This series DOES NOT change the default automatically, but only provides an opt-in mechanism for interested users. It also presents a way forward for such a transition, if and when we decide to do so. Specifically, the new GIT_TEST_DEFAULT_BRANCH_NAME environment variable could be used to update test scripts on an individual basis instead of all-at-once.

Don Goodman-Wilson (1):
init: allow overriding the default branch name for new repositories

Johannes Schindelin (8):
remote: respect core.defaultBranchName send-pack/transport-helper: respect core.defaultBranchName
testsvn: respect core.defaultBranchName
submodule: use the (possibly overridden) default branch name
clone: learn about the possibly-configured default branch name
fmt-merge-msg: learn about the possibly-configured default branch name
fast-export: respect the possibly-overridden default branch name Document how the default branch name can be overridden

 Documentation/config/core.txt |  4 ++++
 builtin/clone.c               | 14 +++++++++++---
 builtin/fast-export.c         | 10 +++++++---
 builtin/init-db.c             |  8 +++++---
 builtin/submodule--helper.c   | 10 ++++++++--
 fmt-merge-msg.c               |  6 ++++--
 refs.c                        | 34 ++++++++++++++++++++++++++++++++++
 refs.h                        |  6 ++++++
 remote-testsvn.c              | 11 ++++++++---
 remote.c                      | 12 ++++++++----
 send-pack.c                   |  6 +++++-
 t/README                      |  4 ++++
 t/t0001-init.sh               | 20 ++++++++++++++++++++
 t/t5609-clone-branch.sh       |  9 +++++++++
 t/t6200-fmt-merge-msg.sh      |  8 ++++++++
 transport-helper.c            |  6 +++++-
 16 files changed, 146 insertions(+), 22 deletions(-)

base-commit: 0313f36c6ebecb3bffe6f15cf25a4883100f0214
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-656%2Fdscho%2Fdefault-branch-name-option-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-656/dscho/default-branch-name-option-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/656

gitgitgadget

From: Don Goodman-Wilson <[email protected]>

There is a growing number of projects trying to avoid the non-inclusive name master in their repositories. For existing repositories, this requires manual work. For new repositories, the only way to do that automatically is by copying all of Git's template directory, then hard-coding the desired default branch name into the .git/HEAD file, and then configuring init.templateDir to point to those copied template files.

To make this process much less cumbersome, let's introduce support for core.defaultBranchName. That way, users won't need to keep their copied template files up to date, and won't interfere with default hooks installed by their administrators.

While at it, also let users set the default branch name via the environment variable GIT_TEST_DEFAULT_BRANCH_NAME, in preparation for adjusting Git's test suite to a more inclusive default branch name. As is common in Git, the GIT_TEST_* variable takes precedence over the config setting.

Note: we use the prefix core. instead of init. because we want to adjust also git clone, git fmt-merge-msg and other commands over the course of the next commits to respect this setting.

---
 builtin/init-db.c |  8 +++++---
 refs.c            | 34 ++++++++++++++++++++++++++++++++++
 refs.h            |  6 ++++++
 t/t0001-init.sh   | 20 ++++++++++++++++++++
 4 files changed, 65 insertions(+), 3 deletions(-)

index 0b7222e7188..99792adfd43 100644
@@ -258,15 +258,17 @@ static int create_default_files(const char *template_path,
 		die("failed to set up refs db: %s", err.buf);
 
 	/*
-	 * Create the default symlink from ".git/HEAD" to the "master"
-	 * branch, if it does not exist yet.
+	 * Create the default symlink from ".git/HEAD" to the default
+	 * branch name, if it does not exist yet.
 	 */
 	path = git_path_buf(&buf, "HEAD");
 	reinit = (!access(path, R_OK)
 		  || readlink(path, junk, sizeof(junk)-1) != -1);
 	if (!reinit) {
-		if (create_symref("HEAD", "refs/heads/master", NULL) < 0)
+		char *default_ref = git_default_branch_name(0);
+		if (create_symref("HEAD", default_ref, NULL) < 0)
 			exit(1);
+		free(default_ref);
 	}
 
 	initialize_repository_version(fmt->hash_algo);

index 224ff66c7bb..8499b3865cb 100644
@@ -560,6 +560,40 @@ void expand_ref_prefix(struct argv_array *prefixes, const char *prefix)
 		argv_array_pushf(prefixes, *p, len, prefix);
 }
 
+char *git_default_branch_name(int short_name)
+{
+	const char *branch_name = getenv("GIT_TEST_DEFAULT_BRANCH_NAME");
+	char *from_config = NULL, *prefixed;
+
+	/*
+	 * If the default branch name was not specified via the environment
+	 * variable GIT_TEST_DEFAULT_BRANCH_NAME, retrieve it from the config
+	 * setting core.defaultBranchName. If neither are set, fall back to the
+	 * hard-coded default.
+	 */
+	if (!branch_name || !*branch_name) {
+		if (git_config_get_string("core.defaultbranchname",
+					  &from_config) < 0)
+			die(_("Could not retrieve `core.defaultBranchName`"));
+
+		if (from_config)
+			branch_name = from_config;
+		else
+			branch_name = "master";
+	}
+
+	if (short_name)
+		return from_config ? from_config : xstrdup(branch_name);
+
+	/* prepend "refs/heads/" to the branch name */
+	prefixed = xstrfmt("refs/heads/%s", branch_name);
+	if (check_refname_format(prefixed, 0))
+		die(_("invalid default branch name: '%s'"), branch_name);
+
+	free(from_config);
+	return prefixed;
+}
+
 /*
  * *string and *len will only be substituted, and *string returned (for
  * later free()ing) if the string passed in is a magic short-hand form

index a92d2c74c83..e8d4f6e2f13 100644
@@ -154,6 +154,12 @@ int repo_dwim_log(struct repository *r, const char *str, int len, struct object_
 int dwim_ref(const char *str, int len, struct object_id *oid, char **ref);
 int dwim_log(const char *str, int len, struct object_id *oid, char **ref);
 
+/*
+ * Retrieves the name of the default branch. If `short_name` is non-zero, the
+ * branch name will be prefixed with "refs/heads/".
+ */
+char *git_default_branch_name(int short_name);
+
 /*
  * A ref_transaction represents a collection of reference updates that
  * should succeed or fail together.

index 1edd5aeb8f0..b144cd8f46b 100755
@@ -464,4 +464,24 @@ test_expect_success MINGW 'redirect std handles' '
 	grep "Needed a single revision" output.txt
 '
 
+test_expect_success 'custom default branch name from config' '
+	git config --global core.defaultbranchname nmb &&
+	GIT_TEST_DEFAULT_BRANCH_NAME= git init custom-config &&
+	git config --global --unset core.defaultbranchname &&
+	git -C custom-config symbolic-ref HEAD >actual &&
+	grep nmb actual
+'
+
+test_expect_success 'custom default branch name from env' '
+	GIT_TEST_DEFAULT_BRANCH_NAME=nmb git init custom-env &&
+	git -C custom-env symbolic-ref HEAD >actual &&
+	grep nmb actual
+'
+
+test_expect_success 'invalid custom default branch name' '
+	test_must_fail env GIT_TEST_DEFAULT_BRANCH_NAME="with space" \
+		git init custom-invalid 2>err &&
+	test_i18ngrep "invalid default branch name" err
+'
+
 test_done

gitgitgadget

Hi Eric,

I downcased it...

Good call.

I agree that it is a bit hard to follow, but then, the function is really short, so I hoped it is okay.

For such a tiny nuance, I'd rather keep it as one function...

Thank you,
Dscho

And you'd need two functions, default and primary, possibly full and short. Splitting these into two here would mean you'd need four.

Having seen one of the callers, might it be worth avoiding handing off ownership of the string entirely?

I.e., this comes from a string that's already owned for the lifetime of the process (either the environment, or a string stored by the config machinery). Could we just pass that back (or if we want to be more careful about getenv() lifetimes, we can copy it into a static owned by this function)?

Then all of the callers can stop dealing with the extra free(), and you can do:

const char *git_default_branch_name(void)

  {
	return skip_prefix("refs/heads/", git_default_ref_name());

}

-Peff

Actually, one small hiccup is that the config option specifies the branch name, not the ref name. So you really would have to prepare a static-owned copy of it to turn "foo" into "refs/heads/foo" to get the refname.

On the other hand, that would also be a good time to run check_ref_format(). In the patch as-is, the "short" return does not check that the branch is a valid name.

-Peff

Hi Peff,

Legit.

I will work on this.

Thanks,
Dscho

Hi Peff,

For git_default_branch_name(): yes. For repo_default_branch_name(), not really, as that is potentially repository-specific.

(Side note: while I cannot really think of a use case where you would want to set init.defaultBranch in a repository-local config, there _might_ be use cases for that out there, and it _is_ how our config machinery works.)

For ease of use, I decided to only ever return the branch name (but check the full ref).

Those callers that actually need the full ref usually also need the branch name, and it is easy enough to call xstrfmt("refs/heads/%s", ...).

It might make the code a bit less efficient (but who cares, it's not like we're setting up a gazillion repositories per second all the time), but quite a bit easier to reason about.

Ciao,
Dscho

I think it would be helpful to explain why 'master' is no-inclusive even if it originates from the concept of a master copy. i.e. it suggests master/slave even if git is not based on that concept.

Have you got some examples of projects that have changed and the names that they are using? I think it would be helpful if we can agree on a replacement for master - if every repository uses a different name for its main branch it adds an extra complication for new contributors to those projects.

For existing repositories, this

I'm not sure we usually promote the use of GIT_TEST_... environment variables outside of the test suite.

Hi Phillip,

Unfortunately, we do not even have that defense: the term master was copied from BitKeeper, which firmly uses it in the master/slave context. See e.g.
https://mail.gnome.org/archives/desktop-devel-list/2019-May/msg00066.html

I added a _brief_ extension to the context to the first commit's commit message. However, I do not want to go into details here because _this_ patch series is only about empowering users to change their default main branch name.

Yes, there are plenty examples, and I do not want to pick a tiny subset to demonstrate that. A more useful resource is probably this post:
https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx

Sure, and that's what I thought we'd discuss, too, maybe at the meeting I proposed elsewhere (Emily started a new thread about it:
https://lore.kernel.org/git/[email protected]/).

True. Together with Alban's suggestion to make this purely work in the test suite (i.e. not even adjust the C code to respect that environment variable), you convinced me to (re-)move that part of the commit.

No, unintentional. Thank you for pointing this out. It will be fixed in v2 (still working on it).

Absolutely. Thank you for your careful review, I read past this at least half a dozen times.

Right, and in this instance it is test_config_global.

Except that we'll make this a thing that is internal to the test suite now. So this test case can go.

Thank you for helping me improve the patch series! Dscho

Sensible.

And I do not think the planned follow-up work to rename 'master' to something else needs to be defended with lengthy history lessons.

Sufficiently large part of the user population are unhappy with the use of the word 'master' as the default name of the primary branch in a newly created repository, and the mere fact that we are aware of that is good enough justification to move _away_ from 'master'. In other words, we do not have to explain why 'master' was bad, as it does not have to be bad for everybody to be replaced.

But you need to defend that the new word you picked is something everybody is happy with. That is much harder ;-).

This expresses what I was trying to get at with my comments much more clearly than I managed - Thank you

Indeed, though I am more optimistic about that having seen a couple of people have indicated that they don't mind too much what we choose so long as it unlikely to cause future problems.

Best Wishes

Phillip

Hi Junio,

Yes, I agree. It is probably sufficient to just point at a couple high-profile projects that already made the switch to main.

Yes, even Pasky says he regrets the choice of term (see
https://twitter.com/xpasky/status/1271477451756056577):

I picked the names "master" (and "origin") in the early Git tooling back in 2005.

(this probably means you shouldn't give much weight to my name preferences :) )

I have wished many times I would have named them "main" (and "upstream") instead.

To be honest, I stopped looking for got arguments in favor of one name after a couple days, and instead focused on the consensus I
saw: Chrome [*1*] and node.js [*2*] apparently stated publicly that they want to change their main branches to main, and GitLab [*3*] and GitHub [*4*] seem to intend to change the default for new repositories accordingly.

It is not like we have to decide for the community (as we did back in 2005). I am actually quite relieved about that.

Ciao,
Dscho

URL *1*: https://twitter.com/Una/status/1271180494944829441
URL *2*: https://github.com/nodejs/node/issues/33864
URL *3*: https://gitlab.com/gitlab-org/gitlab/-/issues/221164
URL *4*: https://twitter.com/natfriedman/status/1271253144442253312
(this is not really a public announcement, I agree, but it is a public Tweet by the CEO)

Hi Don & Johannes,

Le 10/06/2020 à 23:19, Don Goodman-Wilson via GitGitGadget a écrit :

Why adding yet another environment variable instead of relying only on a config option? I understand it's for the tests, but can't we add a shell function in test-lib.sh (and friends) that tries to read GIT_TEST_DEFAULT_BRANCH_NAME', and, if it exists, sets core.defaultBranchName'?

Cheers,
Alban

Can you produce such a patch that does it cleanly? My knee jerk reaction is that I would suspect that you end up having to touch many places in the t/ scripts, but if you prove otherwise, that would certainly be appreciated.

And no,

    git () { command git -c core.defaultBranchName=master "$@" }

is not an acceptable solution.

I would also be delighted to see such a solution, but my experience with the SHA-256 work tells me there's unlikely to be one. We do a lot of "git init" operations in random places in the test suite and as a consequence it's very hard to make a change without touching a large number of tests.

If we were writing things today, perhaps we would use a function (e.g., test_init_repo or such) to wrap this case, but we unfortunately didn't think about that and we're stuck with what we have now unless someone retrofits the test suite.

brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

Hi brian,

That's a valid point, indeed.

There is actually test_create_repo (see
https://github.com/git/git/blob/v2.27.0/t/test-lib-functions.sh#L1145-L1159):

	# Most tests can use the created repository, but some may need to create
	# more.
	# Usage: test_create_repo <directory>
	test_create_repo () {
		test "$#" = 1 ||
		BUG "not 1 parameter to test-create-repo"
		repo="$1"
		mkdir -p "$repo"
		(
			cd "$repo" || error "Cannot setup test environment"
			"${GIT_TEST_INSTALLED:-$GIT_EXEC_PATH}/git$X" 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
		) || exit
	}

But I agree that few test scripts use it:

	$ git grep 'git init' v2.27.0 -- t/ | wc -l
	765

	$ git grep 'test_create_repo' v2.27.0 -- t/ | wc -l
	296

Ciao,
Dscho

Hi Junio,

Le 12/06/2020 à 01:14, Junio C Hamano a écrit :

I wanted to to do something like this:

if test -n "$GIT_TEST_DEFAULT_BRANCH_NAME";
then
git config core.defaultBranchName "$GIT_TEST_DEFAULT_BRANCH_NAME"
fi

But since we do not have a repository to store the config, it won't work. Sorry for the noise.

Alban

Hi Alban,

We actually would have ~/.gitconfig because HOME is set to t/trash directory.<test-name>/.

However, that would cause all kinds of issues when test scripts expect the directory to be pristine, containing only .git/ but not .gitconfig.

It was a good idea to bring up; I share brian's sentiment that it would have been nice if it would have worked out.

Ciao,
Dscho

Putting:

GIT_CONFIG_PARAMETERS="'core.defaultBranchName=...'"

into the environment would work (and yes, you need the single quotes embedded in the variable), and solves all of the complaints above. Further "git -c" invocations properly append to it. But:

- there are a few tests which explicitly tweak that variable

- it technically changes any tests of "-c" because now we'd never cover the case where we start without the variable defined

I think baking in a special environment variable like you have is not so bad. If this did become too common a pattern, though (special test-only environment variables that do have a separate config option), I wouldn't be opposed to a GIT_TEST_CONFIG_PARAMETERS which takes precedence over other config, and comes with a big warning label that it shouldn't be relied upon outside the test suite. That's equally ugly to GIT_TEST_DEFAULT_BRANCH_NAME, but at least solves the problem once for all of them. I'm just not sure we have enough "all of them" to make it worth doing.

-Peff

Hi Peff,

Indeed.

FWIW I do not plan on using that variable for a long time. And it is not in this here patch series any longer, so let's discuss it in the future patch contribution of mine.

Thanks,
Dscho

From: Johannes Schindelin <[email protected]>

When guessing the default branch name of a remote, and there are no refs to guess from, we want to go with the preference specified by the user for the fall-back.

---
 remote.c | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

index 534c6426f1e..95fa8cc78e0 100644
@@ -256,7 +256,7 @@ static void read_remotes_file(struct remote *remote)
 
 static void read_branches_file(struct remote *remote)
 {
-	char *frag;
+	char *frag, *default_branch_name = NULL;
 	struct strbuf buf = STRBUF_INIT;
 	FILE *f = fopen_or_warn(git_path("branches/%s", remote->name), "r");
 

@@ -276,7 +276,7 @@ static void read_branches_file(struct remote *remote)
 
 	/*
 	 * The branches file would have URL and optionally
-	 * #branch specified.  The "master" (or specified) branch is
+	 * #branch specified.  The default (or specified) branch is
 	 * fetched and stored in the local branch matching the
 	 * remote name.
 	 */

@@ -284,7 +284,7 @@ static void read_branches_file(struct remote *remote)
 	if (frag)
 		*(frag++) = '\0';
 	else
-		frag = "master";
+		frag = default_branch_name = git_default_branch_name(1);
 
 	add_url_alias(remote, strbuf_detach(&buf, NULL));
 	strbuf_addf(&buf, "refs/heads/%s:refs/heads/%s",

@@ -299,6 +299,7 @@ static void read_branches_file(struct remote *remote)
 	strbuf_addf(&buf, "HEAD:refs/heads/%s", frag);
 	refspec_append(&remote->push, buf.buf);
 	remote->fetch_tags = 1; /* always auto-follow */
+	free(default_branch_name);
 	strbuf_release(&buf);
 }
 

@@ -2099,7 +2100,10 @@ struct ref *guess_remote_head(const struct ref *head,
 
 	/* If refs/heads/master could be right, it is. */
 	if (!all) {
-		r = find_ref_by_name(refs, "refs/heads/master");
+		char *name = git_default_branch_name(0);
+
+		r = find_ref_by_name(refs, name);
+		free(name);
 		if (r && oideq(&r->old_oid, &head->old_oid))
 			return copy_ref(r);
 	}

gitgitgadget

Hi Peff,

Sure, we could just leave this alone, or we can just ditch the special-casing of master here.

As you say, this does not affect any modern Git version, and IIRC the code after that special-casing tries to find any remote ref that matches the remote HEAD.

So it's not like we _need_ this special-casing, anyway.

Ciao,
Dscho

I think we need to be a little careful with "any modern Git", because a modern client against an old (or perhaps an alternative implementation) server might still use it. I have to imagine it's pretty rare, but I think it's still useful to return _some_ value.

But as you note, even without a symref extension, we already try to guess based on a unique branch. Probably even choosing the first one alphabetically would be reasonable. But I'd rather err on the side of historical compatibility if we can do so easily. Looking for init.mainBranch, followed by master, accomplishes that and isn't many lines of code.

-Peff

Hi Peff,

I ended up using init.defaultBranch as preference, falling back to master, and then falling back to the first ref matching the given commit hash.

That should be safe enough.

Ciao,
Dscho

From: Johannes Schindelin <[email protected]>

When mentioning the default branch name in an error message, we want to go with the preference specified by the user.

---
 send-pack.c        | 6 +++++-
 transport-helper.c | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

index 0abee22283d..f7747bed1c9 100644
@@ -405,8 +405,12 @@ int send_pack(struct send_pack_args *args,
 	}
 
 	if (!remote_refs) {
+		char *branch_name = git_default_branch_name(1);
+
 		fprintf(stderr, "No refs in common and none specified; doing nothing.\n"
-			"Perhaps you should specify a branch such as 'master'.\n");
+			"Perhaps you should specify a branch such as '%s'.\n",
+			branch_name);
+		free(branch_name);
 		return 0;
 	}
 	if (args->atomic && !atomic_supported)

index a46afcb69db..cc8ae5c67ca 100644
@@ -1044,9 +1044,13 @@ static int push_refs(struct transport *transport,
 	}
 
 	if (!remote_refs) {
+		char *branch_name = git_default_branch_name(1);
+
 		fprintf(stderr,
 			_("No refs in common and none specified; doing nothing.\n"
-			  "Perhaps you should specify a branch such as 'master'.\n"));
+			  "Perhaps you should specify a branch such as '%s'.\n"),
+			branch_name);
+		free(branch_name);
 		return 0;
 	}
 

gitgitgadget

From: Johannes Schindelin <[email protected]>

Since the default branch name can now be configured, the testsvn remote helper needs to be told about it.

---
 remote-testsvn.c | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

index 3af708c5b67..a48d74f35cd 100644
@@ -13,7 +13,7 @@
 static const char *url;
 static int dump_from_file;
 static const char *private_ref;
-static const char *remote_ref = "refs/heads/master";
+static char *remote_ref;
 static const char *marksfilename, *notes_ref;
 struct rev_note { unsigned int rev_nr; };
 

@@ -286,7 +286,7 @@ int cmd_main(int argc, const char **argv)
 			private_ref_sb = STRBUF_INIT, marksfilename_sb = STRBUF_INIT,
 			notes_ref_sb = STRBUF_INIT;
 	static struct remote *remote;
-	const char *url_in;
+	const char *url_in, *default_branch;
 
 	setup_git_directory();
 	if (argc < 2 || argc > 3) {

@@ -294,6 +294,10 @@ int cmd_main(int argc, const char **argv)
 		return 1;
 	}
 
+	remote_ref = git_default_branch_name(0);
+	if (!skip_prefix(remote_ref, "refs/heads/", &default_branch))
+		BUG("unexpected remote_ref '%s'", remote_ref);
+
 	remote = remote_get(argv[1]);
 	url_in = (argc == 3) ? argv[2] : remote->url[0];
 

@@ -306,7 +310,8 @@ int cmd_main(int argc, const char **argv)
 		url = url_sb.buf;
 	}
 
-	strbuf_addf(&private_ref_sb, "refs/svn/%s/master", remote->name);
+	strbuf_addf(&private_ref_sb, "refs/svn/%s/%s",
+		    remote->name, default_branch);
 	private_ref = private_ref_sb.buf;
 
 	strbuf_addf(&notes_ref_sb, "refs/notes/%s/revs", remote->name);

gitgitgadget

From: Johannes Schindelin <[email protected]>

To allow for overriding the default branch name, we have introduced a config setting. With this patch, the git submodule command learns about this, too.

---
 builtin/submodule--helper.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

index 46c03d2a126..0b4abb5a64b 100644
@@ -1980,8 +1980,14 @@ static const char *remote_submodule_branch(const char *path)
 		branch = sub->branch;
 	free(key);
 
-	if (!branch)
-		return "master";
+	if (!branch) {
+		static char *default_branch;
+
+		if (!default_branch)
+			default_branch = git_default_branch_name(1);
+
+		return default_branch;
+	}
 
 	if (!strcmp(branch, ".")) {
 		const char *refname = resolve_ref_unsafe("HEAD", 0, NULL, NULL);

gitgitgadget

One thing to consider: in the future, if we move away from "master" or even allow the value to be configurable, we're gonna end up breaking a lot of repositories this way.

If a developer regularly pulls in submodule updates via git submodule update --remote, when the default branch name changes, this will suddenly stop working. This will require developers who use submodules to "fix" their .gitmodules file.

If it's configurable, this problem might be even worse. It could lead to scenarios where one developer might go "works for me" while another developer (who may set the configuration and forget about it) would be confused about why it's not working for them.

Just a couple thoughts I had while looking at this patch.

From: Johannes Schindelin <[email protected]>

When cloning a repository without any branches, Git chooses a default branch name for the as-yet unborn branch.

Now that we can configure what the default branch name should be, we will want git clone to respect that setting.

---
 builtin/clone.c         | 14 +++++++++++---
 t/t5609-clone-branch.sh |  9 +++++++++
 2 files changed, 20 insertions(+), 3 deletions(-)

index cb48a291caf..a21d3e99f82 100644
@@ -1263,9 +1263,17 @@ int cmd_clone(int argc, const char **argv, const char *prefix)
 		remote_head_points_at = NULL;
 		remote_head = NULL;
 		option_no_checkout = 1;
-		if (!option_bare)
-			install_branch_config(0, "master", option_origin,
-					      "refs/heads/master");
+		if (!option_bare) {
+			char *default_branch = git_default_branch_name(0);
+			const char *nick;
+
+			if (!skip_prefix(default_branch, "refs/heads/", &nick))
+				BUG("unexpected default branch '%s'",
+				    default_branch);
+			install_branch_config(0, nick, option_origin,
+					      default_branch);
+			free(default_branch);
+		}
 	}
 
 	write_refspec_config(src_ref_prefix, our_head_points_at,

index 6e7a7be0522..66af3ac2669 100755
@@ -67,4 +67,13 @@ test_expect_success 'clone -b not allowed with empty repos' '
 	test_must_fail git clone -b branch empty clone-branch-empty
 '
 
+test_expect_success 'chooses correct default branch name' '
+	GIT_TEST_DEFAULT_BRANCH_NAME= \
+		git -c core.defaultBranchName=up clone empty whats-up &&
+	test_write_lines refs/heads/up refs/heads/up >expect &&
+	git -C whats-up symbolic-ref HEAD >actual &&
+	git -C whats-up config branch.up.merge >>actual &&
+	test_cmp expect actual
+'
+
 test_done

gitgitgadget

"Johannes Schindelin via GitGitGadget" <[email protected]>

From: Johannes Schindelin <[email protected]>

When formatting the commit message for merge commits, Git appends "into <branch-name>" unless the current branch is the default branch.

Now that we can configure what the default branch name should be, we will want to respect that setting in that scenario rather than using the compiled-in default branch name.

---
 fmt-merge-msg.c          | 6 ++++--
 t/t6200-fmt-merge-msg.sh | 8 ++++++++
 2 files changed, 12 insertions(+), 2 deletions(-)

index 72d32bd73b1..5e5c1d86f1c 100644
@@ -407,7 +407,7 @@ static void fmt_merge_msg_title(struct strbuf *out,
 				const char *current_branch)
 {
 	int i = 0;
-	char *sep = "";
+	char *sep = "", *default_branch_name;
 
 	strbuf_addstr(out, "Merge ");
 	for (i = 0; i < srcs.nr; i++) {

@@ -451,10 +451,12 @@ static void fmt_merge_msg_title(struct strbuf *out,
 			strbuf_addf(out, " of %s", srcs.items[i].string);
 	}
 
-	if (!strcmp("master", current_branch))
+	default_branch_name = git_default_branch_name(1);
+	if (!strcmp(default_branch_name, current_branch))
 		strbuf_addch(out, '\n');
 	else
 		strbuf_addf(out, " into %s\n", current_branch);
+	free(default_branch_name);
 }
 
 static void fmt_tag_signature(struct strbuf *tagbuf,

index e4c2a6eca43..a23cd157ffd 100755
@@ -158,6 +158,14 @@ test_expect_success 'setup FETCH_HEAD' '
 	git fetch . left
 '
 
+test_expect_success 'with overridden default branch name' '
+	test_config core.defaultBranchName default &&
+	test_when_finished "git switch master" &&
+	git switch -c default &&
+	git fmt-merge-msg <.git/FETCH_HEAD >actual &&
+	! grep "into default" actual
+'
+
 test_expect_success 'merge.log=3 limits shortlog length' '
 	cat >expected <<-EOF &&
 	Merge branch ${apos}left${apos}

gitgitgadget

"Johannes Schindelin via GitGitGadget" <[email protected]>

From: Johannes Schindelin <[email protected]>

When anonymizing commit history, we are careful to leave the branch name of the default branch alone.

When the default branch name is overridden via the config or via the environment variable, we will want git fast-export to use that overridden name instead.

---
 builtin/fast-export.c | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

index 85868162eec..028dd9969a2 100644
@@ -515,13 +515,17 @@ static const char *anonymize_refname(const char *refname)
 	};
 	static struct hashmap refs;
 	static struct strbuf anon = STRBUF_INIT;
+	static char *default_branch_name;
 	int i;
 
 	/*
-	 * We also leave "master" as a special case, since it does not reveal
-	 * anything interesting.
+	 * We also leave the default branch name as a special case, since it
+	 * does not reveal anything interesting.
 	 */
-	if (!strcmp(refname, "refs/heads/master"))
+	if (!default_branch_name)
+		default_branch_name = git_default_branch_name(0);
+
+	if (!strcmp(refname, default_branch_name))
 		return refname;
 
 	strbuf_reset(&anon);

gitgitgadget

I wonder if anything bad happens if we keep *no* refs intact in this function. "Since it does not reveal anything interesting" is an excuse why not munging it may be OK, but it does not explain why we prefer not munging it actively.

If there is no reason to keep _some_ refs as-is, I agree that it is perfectly sensible not to have this special case at all.

Thanks.

I think this is fine because it only reveals the name of your particular choice of default branch. The goal of the --anonymize option is to allow people to maintain the structure of their repositories while stripping private information from them, primarily for debugging purposes (e.g., providing to us for troubleshooting).

The things people want to prevent exposing are their code, data, project names, user names, etc.: that is, anything identifying, privileged, or private. The default branch name isn't any of those things; we know you have one, and for troubleshooting purposes, we aren't that interested in what you called it. You've almost certainly picked it out of a set of one of 20 words that people use for this purpose, none of which are private, and all of which are shared by millions of other repositories.

In the extremely unlikely case that it does matter, invoking git with something like "-c default.branch=$(git hash-object /dev/null)" would be sufficient to anonymize all branches.

I should point out that people frequently ask for the output of "git config -l" for troubleshooting, and most people wouldn't consider their default branch name to be worth sanitizing there.

brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

I think that's not very convincing. If branch names in general are identifying enough to warrant anonymization then shouldn't the default name be too?

I think this is a little presumptuous, most people wouldn't consider it to be worth sanitizing because there isn't currently such a config setting. If I give you the the output of "git config -l" then I think it's obvious that all of my configuration settings will be included (and therefore I can choose to sanitize accordingly), but if I'm giving an exported repository I think should be anonymized, but my default branch, which someone could innocently base on a project or company name, could easily be accidentally included in that output which could lead to a frustrating experience

Matthew Rogers

It is a good argument. I also heard a rumor that often branch names contain codewords given to pre-released hardware that are highly confidential in certain circles, and heard that it is one of the reasons why Gerrit has server side ACL that lets you hide some branches from authenticated users that can access other branches.

Again, the original comment explains why 'master' without such a configuration knob was not worth protecting, but what it does not explain is why keeping it (and only that branch name) unmunged gives a more useful result than munging everything. From the point of view of "I want to debug the shape of the DAG, without the actual user data", munging 'master' to 'ref47' while other branches like 'next' are munged to 'ref%d' does not make it harder to use or less useful for the debugging than only 'master' is kept intact in the output stream.

Hi,

Yes, branch names in general _can_ contain information users may prefer to keep private.

However, we're not talking about branch names in general. We are talking about the default name of the main branch, to be picked in _all_ of your new repositories.

Yes. And you're unlikely to configure the default name to be used for all of your future git init operations to be something non-generic.

I am still highly doubtful of Matt's suggestion that it would be worth protecting the default name of the main branch to be used for _each_ and _any_ new repository.

Now, if you suggest that git fast-export --anonymize should either not special-case the main branch, or at least have a configurable set of names it skips from protecting, then I will be much more in favor of those suggestions. However, those suggestions are quite a bit orthogonal to the patch series at hand, so I would want to discuss them in their own code contribution instead of here.

Ciao,
Dscho

No, we are talking about the name of the branch, chosen to be the primary one, in one particular repository whose contents are exported via fast-export with explicit request from the user to anonymize end-user data.

I think after writing the message about your "two variable" approach, you would retract the "something non-generic" part in the above sentence. The original "we redact branch names but 'master' is used by and known by everybody so there is no need to redact" would have been a good argument. Perhaps there is a value to keep the primary branch identifiable even in an export stream that has all the refnames and payload anonymized, and leaving 'master' intact would have been a viable approach for solving that issue.

That trick NO LONGER applies once you allow the name of the primary branch customizable, and the end user has used a name that is not to be exposed. Yes, "we want to ensure that readers of the export stream can identify which ref is the primary branch of the repository" is orthogonal from "how do we make primary branch configurable in a live repository?" and "how do we make the default name used for the primary branch in repositories newly created?". But because the old solution would not work in the new world order this topic created, a new solution needs to be found when you move the world to the new order.

An easy solution would be to reserve "ref0" for the primary branch in the repository and anonymize other refs "ref1", "ref2", ...

That can be done as a preparatory step regardless of the "'master' may not be in the name of the primary branch in this repository" topic.

-- >8 --
Subject: [PATCH] fast-export: do anonymize the primary branch name

In a fast-export stream with --anonymize option, all the end-user data including refnames are munged to prevent exposure, but the 'master' branch is left intact.

There is a comment that explains why it is OK to leave 'master' unanonymized (because everybody calls the primary branch 'master' and it is no secret), but that does not justify why it is bad to anonymize 'master' and make it undistinguishable from other branches. Assuming there _is_ a need to allow the readers of the output to tell where the tip of the primary branch is, let's keep the special casing of 'master', but still anonymize it to "ref0". Because all other branches will be given ref+N where N is a positive integer, this will keep the primary branch identifiable in the output stream, without exposing what the name of the primary branch is in the repository the export stream was taken from.

This is in preparation for introducing a mechanism to affect the name of the primary branch used in the repository. Once the mechanism is in use, the name of the primary branch won't be 'master', and may not be allowed to be exposed.

---
 builtin/fast-export.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 85868162ee..a306a60d25 100644
@@ -497,7 +497,7 @@ static void *anonymize_ref_component(const void *old, size_t *len)
 {
 	static int counter;
 	struct strbuf out = STRBUF_INIT;
-	strbuf_addf(&out, "ref%d", counter++);
+	strbuf_addf(&out, "ref%d", ++counter);
 	return strbuf_detach(&out, len);
 }
 

@@ -522,7 +522,7 @@ static const char *anonymize_refname(const char *refname)
 	 * anything interesting.
 	 */
 	if (!strcmp(refname, "refs/heads/master"))
-		return refname;
+		return "ref0";
 
 	strbuf_reset(&anon);
 	for (i = 0; i < ARRAY_SIZE(prefixes); i++) {

... and the follow-up step to become part of the series you are working on to allow customing what the primary branch is called would turn the second hunk to

	-	if (!strcmp(refname, "refs/heads/master"))
	+	if (!strcmp(refname, get_primary_branch_name(0)))
			return "refs/heads/ref0";

By the way, with your "two variables" approach to make both the "default" (for 'init' and 'clone') and the "primary" (for 'fmt-merge-msg' and 'fast-export') configurable, we'd need accessor function(s) for the primary branch name for the given repository. The get_primary_branch_name() helper function might want to take a "struct repository *" argument in addition to "please give me an abbreviated refname" boolean, given the recent push to pass the struct to everybody.

Hi Junio,

Right.

My current state defines a repo_main_branch_name(flags) function where the flags can be MAIN_BRANCH_SHORT_NAME and MAIN_BRANCH_FOR_INIT.

So I think we're on the same page.

BTW I heard from a couple sides that "primary" would imply that there is also a "secondary" branch, and potentially an ordering of all branches, which is why I did not really consider "primary" as candidate. Besides, it is so much more awkward to type than "main" (especially when you're as tired as I am right now...).

That's why I try to stay with "main" for the moment.

Ciao,
Dscho

You are reading too much into it. I used "primary" because I needed a word that clearly conveys the concept of being a special among others, a word that is about the concept which is different from the concept of "default", and that is clearly different from any of the candidates floated as concrete words to replace 'master'. Because I wanted to say things like:

In the context of fast-export, you'd want to special case the "primary" branch name, because unlike the "default" branch name (which we envision to be 'main' for most people in the new world order, so it may be less worth anonymizing because of the same reason the current code keeps 'master' as-is), its name can be sensitive.

without becoming unnecessarily ambiguous (replace 'primary' with 'main' in the above).

It was not because I do not want us to pick 'main' as the replacement word for 'master' as the default branch name.

And a set of things, among which there is a concept of "one thing that is special and different from all the others", does not necessarily have to be a totally ordered set. When cloning, we say that the (often bare) repository at the other end indicates which branch is the primary branch of the project by pointing at it with its HEAD (which is the reason why we try to fork it to our local branch namespace and check it out after cloning). There is no "secondary" in such a use case, and there is no need to have one.

Hi Junio,

You are absolutely correct!

I like this approach a lot. Do you want me to integrate it into this patch series, or rather have it as a stand-alone patch?

Ciao,
Dscho

I do not see any need for an off-series preparation step. Without configurable primary branch, keeping 'master' as 'master' used in the current code is an OK way to anonymize refs and still keep the primary line of development in the output identifyable. The "ref0" trick becomes necessary only when we introduce configurable primary; even though it would not hurt to switch to the "ref0" approach to anonymize-but-still-the-primary-is-identifiable early, it just is not necessary to do so.

I'd say that we should take <[email protected]> with two changes,

- see if the "refname" matches the fully
spelled primary branch name by asking repo_main_branch_name(repo, 0), instead of comparing with "refs/heads/master", and

- if matches return "refs/heads/ref0" instead of "ref0".

and replace your [PATCH 8/9] (or whichever the counterpart patch is in the rerolled series) with it.

Thanks.

Hi Junio,

        /*
         * We special-case the main branch, anonymizing it to `ref0`.
         */

Hi Junio,

Also, t9351 obviously needs to be adjusted. This one works for me:

-- snipsnap --
From: Junio C Hamano <[email protected]>
Date: Thu, 11 Jun 2020 08:05:38 -0700
Subject: [PATCH] fast-export: do anonymize the primary branch name

In a fast-export stream with --anonymize option, all the end-user data including refnames are munged to prevent exposure, but the 'master' branch is left intact.

There is a comment that explains why it is OK to leave 'master' unanonymized (because everybody calls the primary branch 'master' and it is no secret), but that does not justify why it is bad to anonymize 'master' and make it undistinguishable from other branches. Assuming there _is_ a need to allow the readers of the output to tell where the tip of the primary branch is, let's keep the special casing of 'master', but still anonymize it to "ref0". Because all other branches will be given ref+N where N is a positive integer, this will keep the primary branch identifiable in the output stream, without exposing what the name of the primary branch is in the repository the export stream was taken from.

This is in preparation for introducing a mechanism to affect the name of the primary branch used in the repository. Once the mechanism is in use, the name of the primary branch won't be 'master', and may not be allowed to be exposed.

---
 builtin/fast-export.c            | 7 +++----
 t/t9351-fast-export-anonymize.sh | 9 +++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

index 85868162eec..f10e3b35e5b 100644
@@ -497,7 +497,7 @@ static void *anonymize_ref_component(const void *old, size_t *len)
 {
 	static int counter;
 	struct strbuf out = STRBUF_INIT;
-	strbuf_addf(&out, "ref%d", counter++);
+	strbuf_addf(&out, "ref%d", ++counter);
 	return strbuf_detach(&out, len);
 }
 

@@ -518,11 +518,10 @@ static const char *anonymize_refname(const char *refname)
 	int i;
 
 	/*
-	 * We also leave "master" as a special case, since it does not reveal
-	 * anything interesting.
+	 * We special-case the main branch, anonymizing it to `ref0`.
 	 */
 	if (!strcmp(refname, "refs/heads/master"))
-		return refname;
+		return "refs/heads/ref0";
 
 	strbuf_reset(&anon);
 	for (i = 0; i < ARRAY_SIZE(prefixes); i++) {

index 897dc509075..2415f0ec213 100755
@@ -26,8 +26,9 @@ test_expect_success 'stream omits path names' '
 	! grep xyzzy stream
 '
 
-test_expect_success 'stream allows master as refname' '
-	grep master stream
+test_expect_success 'stream translates master to ref0' '
+	grep refs/heads/ref0 stream &&
+	! grep master stream
 '
 
 test_expect_success 'stream omits other refnames' '

@@ -57,7 +58,7 @@ test_expect_success 'import stream to new repository' '
 test_expect_success 'result has two branches' '
 	git for-each-ref --format="%(refname)" refs/heads >branches &&
 	test_line_count = 2 branches &&
-	other_branch=$(grep -v refs/heads/master branches)
+	other_branch=$(grep -v refs/heads/ref0 branches)
 '
 
 test_expect_success 'repo has original shape and timestamps' '

@@ -65,7 +66,7 @@ test_expect_success 'repo has original shape and timestamps' '
 		git log --format="%m %ct" --left-right --boundary "$@"
 	} &&
 	(cd .. && shape master...other) >expect &&
-	shape master...$other_branch >actual &&
+	shape ref0...$other_branch >actual &&
 	test_cmp expect actual
 '
 

--
2.26.0.windows.1

Ah, I forgot to say, if you think it is easier to manage the main set of patches for the topic to eject as much preparatory changes as possible, I do not at all mind treating this as one of the preparatory step and queue it separately, making the main series depend on it. I just wanted to say that it is not necessary, even though it does not hurt.

Hi Junio,

Due to the need to adjust t9351, I think it is clearer if it is a two-part
change: one to introduce the "main branch -> ref0" change, and another one to respect core.mainBranch. Those are separate concerns in my mind.

I moved the first one to the beginning of the patch series so that you're still at liberty to take it early vs keeping it within the topic branch.

Thanks,
Dscho

If you are going to update it, why not make it useful?

I complained number of times during the discussion that the original comment explains why leaving 'master' as-is does not reveal anything useful to adversaries but does not justify what the code attempts to achieve by special casing 'master' in the first place.

It is not an improvement to literally adjust that inadequate comment to the new world order to just parrot what the code already says without explaining why it does so.

/*
* Anonymize the name used for the primary branch in this
* repository, but reserve ref0 for it, so that it can
* be identified among other refs in the output. */

is the minimum I would expect before calling it an improvement. We could add

It is often main for new repositories (and master for aged ones) and such well-known names may not need anonymizing, but it could be configured to use a secret word that the user may not want to reveal.

at the end to explain the motivation behind anonymizing even more, if we wanted to.

Now, "so that ..." part is totally a fabrication based on my best guess. I do not know what the original author was thinking when the decision to leave the master as-is was made.

Thanks.

Am 12.06.20 um 17:14 schrieb Junio C Hamano:

IMO, making the primary branch identifiable is a reasonable justification to treat it specially. But then, why does it have to be renamed to 'ref0'? Couldn't it just be renamed to Git's default primary branch name, be it 'master' today or 'main' or whatever in the future? After the anonymization, nobody will know whether that was the real name of the primary branch or not. Leaving it at 'master'/'main' reduces the mental burden of the recipient of the anonymous repo.

-- Hannes

That comes from https://lore.kernel.org/git/[email protected]/

But I agree with you 100% if you literally mean 'master' (or 'main') hardcoded without any end-user customization. What I rejected and replaced with the vanilla "ref0" was to return the configured name that will be used for the primary branch in new repositories. The above proposal suggested a faulty:

- if (!strcmp(refname, "refs/heads/master"))
- return refname;
+ if (!strcmp(refname, get_primary_branch_name(DO_NOT_ABBREV)))
+ return get_default_branch_name(DO_NOT_ABBREV);

A corrected code should return a hardwired constant 'main' (it probably gets behind a C preprocessor macro, but the point is that we do not want end-user customization) for the reason stated in that message.

Thanks.

Hi Junio & Hannes,

I like ref0 better, for two reasons:

- it is more consistent to just have all anonymized branches be named ref<N>, and

- using main both for an original main and an original master can be a bit confusing, as the reader might assume that this branch name (as it does not follow the ref<N> convention) was _not_ anonymized, when it very well might have been.

Ciao,
Dscho

A pro for keeping a hardcoded 'master' is that it is compatible with the current world order, and flipping it to hardcoded 'main' upon transition is just to use the moral equivalent, so we do not need to immediately have to change anything. The _new_ consistency across ref<N> does feel attractive, but because it is new, there always is a pushback not to "fix" what is not broken.

I am personally OK either way.

By the way, we'd need to devise a transition plan for switching the default branch name (i.e. the name used for the primary branch in a newly created repository unless the user configures it to some other value) to 'main' (oh, I just found one reason why I will not want to use that name in my project(s)---it is too close to 'maint').

It might roughly go like:

1. We introduce core.defaultBranchName; when it is not set, its value defaults to 'master' in the 1st phase of the transition. "git init" and "git clone" however issue a warning that says "unless you configure core.defaultBranchName, we use 'master' for now for backward compatibility but we will start using 'main' in three major releases of Git in the future". These commands use the default branch name when creating a new repository in the 1st phase, and set core.primaryBranchName to that name in the resulting repository.

This is to encourage early adopters to set it to 'maint'^W'main' (eek, see, I again made that typo), while allowing those who have toolset that depends more heavily on the current default branch name than other people to set it to 'master' for stability.

In the 1st phase, a few commands that care about what the primary branch is in a repository (i.e. fmt-merge-msg and fast-export are the two we have identified so far) pay attention to the core.primaryBranchName configuration, and default to 'master' if the configuration does not exist.

These commands issue a warning that says "unless you configure core.primaryBranchName in the repository, we use 'master' for now but we will start using 'main' in three major releases of Git in the future".

The above two warning messages will be squelched once the user sets respective configuration variable.

2. We flip the default for the two variables from 'master' to 'main' in three major releases of Git (i.e. 24-30 weeks from the 1st phase). The two warning messages added for the 1st phase will be reworded for the updated default. We no longer need to say "in three major releases" in there.

3. After long time passes, remove the warning.

Hi Junio,

Yes, the trouble with maint did cross my mind, but I try not to "overfit" to git/git. :-)

Yes, that's what I had in my mind, too (modulo the concrete part about the three major versions, which is something I would have asked about at some stage, thank you for answering that question already!).

Thank you,
Dscho

I do not think it is overfitting; if the solution cannot even support the originating project well, there is something wrong.

Most likely, I'd be tempted to rename it myself away from any name that is too similar to 'maint'; perhaps to 'stable' (or 'devo', h/t tla ;-).

Hi Junio,

You could also use next instead of master, which would make intuitive sense because the commits that make it into that branch are slated to be part of the next major Git version.

And a relatively obvious name for the current next might be cooking.

I refrained from proposing this earlier, thinking that this would be too disruptive, but since pu was renamed to seen...

:-)

Ciao,
Dscho

Renaming 'pu' away from two-letter has a positive technical and social effect. Using 'next' for anything but what it currently means does not have any such upside and only the downside of confusing people.

As to 'cooking', I am not sure. Personally I consider that the topics that are in 'next' plus those that are soon to be in 'next' are all 'cooking'. But I do not think anybody's dying to rename 'next', so...

Hi Junio,

True. Sorry about forgetting that when adjusting the code comment.

In my defense, I am/was much more worried about transmogrifying the patch series to reflect the separation between init.defaultBranch and core.mainBranch and the associated fall-out (I highly doubt that the range-diff between v1 and v2 will be useful...).

That is indeed an improvement, thank you so much.

Maybe we add that to the comment in the patch that teaches fast-export about core.mainBranch? Yeah, I think I like that idea best.

This comment comes from a8722750985 (teach fast-export an --anonymize option, 2014-08-27), and I agree that there is no explicit explanation why the main branch is special-cased.

However, I think that your guess is a good one: it might be an interesting aspect to identify the commits from the main branch, without necessarily needing to know the actual name of said branch, e.g. to reproduce a reported issue.

Ciao,
Dscho

Hi Matt,

I don't think that the name of the main branch should be subject to anonymizing, whether it be master or anything else.

Ciao,
Dscho

"Here is why" is missing ;-) I think you realized that it needs to be, after you wrote the "ah, we need two, the default for new ones and the name of the primary branch in a particular repository", as we are dealing with the latter here.

Thanks.

Hi Junio,

Yep, absolutely.

Thanks,
Dscho

From: Johannes Schindelin <[email protected]>

There is a GIT_TEST_* environment variable and a core. config setting (with the former taking precendence over the latter) to allow overriding what name Git uses by default as main branch of new repositories.

Now that all kinds of Git operations have learned to respect those, let's document them.

---
 Documentation/config/core.txt | 4 ++++
 t/README                      | 4 ++++
 2 files changed, 8 insertions(+)

index 74619a9c03b..a11e1abdf59 100644
@@ -626,3 +626,7 @@ core.abbrev::
 	in your repository, which hopefully is enough for
 	abbreviated object names to stay unique for some time.
 	The minimum length is 4.
+
+core.defaultBranchName::
+	Allows overriding the default branch name e.g. when initializing
+	a new repository or when cloning an empty repository.

index cf863837ab9..b32f520a27f 100644
@@ -421,6 +421,10 @@ GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=<boolean>, when true (which is
 the default when running tests), errors out when an abbreviated option
 is used.
 
+GIT_TEST_DEFAULT_BRANCH_NAME allows overriding the default branch name
+that is used for example when initializing new repositories, or when
+cloning a repository that has no branches yet.
+
 Naming Tests
 ------------
 

gitgitgadget

"Johannes Schindelin via GitGitGadget" <[email protected]>

"Johannes Schindelin via GitGitGadget" <[email protected]>

I scanned the series quickly and the patches seem to cover all the places I was aware of that has the hard-coded knowledge of the default branch name being 'master'. Looking good.

Yes. I've been thinking about a way that does not hurt workflows used in existing projects while allowing a "git init" that is run to create a new repository by a new user who does not have any special customization in ~/.gitconfig to use the branch name that replaces the 'master' (I do not mind changing away from 'master', but I am not yet convinced it should be 'main', by the way---the actual choice of the final name does not matter at this point of the design of backward compatibility plan).

I think "git init" that is creating a new repository (iow, do not do anything when reinitializing an existing repostiory) can

- look at config.defaultBranchName in /etc/gitconfig or ~/.gitconfig before initializing the per-repository config in $GIT_DIR/config it just created (or it is about to create).

- if there is no config.defaultBranchName configured, then set the per-repository configuration to 'main' in the per-repository configuration. Otherwise do not do anything.

And then we make sure Don's git_default_branch_name() works this way:

(0) if there is config.defaultBranchName in relevant config file (i.e. /etc/gitconfig, ~/.gitconfig or per-repo config), use the specified name.

(1) otherwise use 'master' (not 'main').

That way, an existing repository will keep using 'master' unless the user shows the preference (and accepts responsibilities for possible fallouts) in ~/.gitconfig or the repository's .git/config, while a new repository created by a user who does not show any particular preference will use 'main'.

A useful addition to these 9-patch series (i.e. even before the default for vanilla usage gets changed) might be to give an example to use "git config" to grab the default branch name, e.g.

    name=$(git config core.defaultBranchName || echo master)

Better yet (because the above forces the end users to write 'master' in their script), we might want to teach "git var" about the variable, so that the above can be written like so:

    name=$(git var defaultBranchName)

For those not so familiar with "git var", it is a command to query "magic" variables whose value can be retrieved from different places and is backed by non-trivial logic. "What's the editor to be used?" is queried by "git var GIT_EDITOR", but that is not a simple:

if test -n "$GIT_EDITOR"
then
echo "$GIT_EDITOR"
else
echo vi
fi

It takes the fallback EDITOR environment variable, and core.editor configuration variable, into account, for example.

Similarly, "what is the default branch name" is not just about the value of one configuration variable. GIT_TEST_DEFAULT_BRANCH_NAME environment needs to be consulted, and when there is nothing configured, it needs to say 'master', so that end-users who use "git var" do not have to hardcode the string 'master' in their script.

Hi Junio,

Thanks!

I read this (way too late) last night and slept over it. Together with your comment on the fmt-merge-msg patch, I think you are really on to
something: we need _two_ config settings, as there are two distinct concepts at play here:

- One setting to specify the default branch name for newly-initialized repositories (such as git init, unless it re-initializes, and git clone when the cloned repository does not yet contain any branches).

This should probably be called init.defaultBranchName (even if git clone picks it up, too), and be overrideable by GIT_TEST_DEFAULT_BRANCH_NAME.

- And another one, to define the default branch name for the _current_ repository. This setting would be configured implicitly upon git init and git clone. For repositories where it is not set, we would assume master for backwards-compatibility.

Technically, this should probably not even be a config option because it is _strictly_ per-repo. But maybe it is not _so_ much per-repo: if I want to rename all my main branches in all of my local repositories, I might opt to configure this in ~/.gitconfig.

Maybe a good name for this would be repo.mainBranch (and it would contain the full ref name, e.g. refs/heads/main, not just main).

And then git fmt-merge-msg (and your proposed git var addition, which I like a lot, maybe git var mainBranch?) will pick up the latter.

That way, existing repositories would not be affected by GIT_TEST_DEFAULT_BRANCH_NAME or init.defaultBranchName at all. Only new repositories would pick it up.

Does that sound like a plan?

Ciao,
Dscho

Yes.

Nit. This is not the "default" branch name. It is "which branch is the primary one in this repository?" There is no default.

I think core.* namespace originally were supposed to be about "this" repository, so instead of introducing "repo.*", I'd recommend just sticking it in "core.*", perhaps "core.primaryBranchName".

And for help the scripts in t/, GIT_TEST_PRIMARY_BRANCH_NAME would be a handy thing to have.

You may need "git fast-export" to know about it (I do not think you should special case the primary branch but that is a topic of another thread).

So the idea is that init.* one affects "init" and "clone" (and any other operation that creates a new repository and have to pick a branch to point the HEAD at), lack of which defaults to 'main', and the other one affects "fmt-merge-msg", "fast-export" (and any other operation that wants to know which branch is the primary one in the repository), lack of which defaults to 'master'?

And an updated version of Git would record the latter in the repository it just created, based on the former, so that things won't get broken when the user sets the latter in ~/.gitconfig?

I think such a two-variable configuration would also work.

I was aiming at not needing any configuration for new people and the approach I illustrated for you with just a single variable was an outcome from it. One possible downside of the one-variable approach is that existing users with repositories whose primary branch needs to stay 'master' cannot set the core.defaultBrnachName in ~/.gitconfig until they iterate over all the "sticking to 'master'" repositories and set the core.defaultBrnachName variable in them, but with the two variable approach, that particular downside is eliminated, which I like. I haven't thought things through to see if there are downside in the two variable approach, but just like "If you have some repositories that want to stick to 'master', set the config in them before you set the config globally to something different from 'master'" would be a semi-workable workaround for the downside in the one variable approach, I suspect any downside in the two variable approach we will identify would have an easy workaround, too.

Thanks.

I've looked over this series, and I have no additional comments beyond what I've mentioned and what Junio pointed out at the end of the series. With those provisos, I'm generally happy with it, and glad to see these patches hit the list.

brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

Hi Johannes (and Dan)

This is (somewhat) orthogonal to the topic here, but I wonder if we could be doing anything to make this easier for users.

Could servers remember that a branch has ``moved'' and alert users as such when they pull? Even better, it would be nice if this alert from the server could allow clients to automatically rename their refs appropriately so that this transition is as easy as possible, even for existing repositories.

Welcome, Dan! This is a fantastic first contribution, and I would be honored to help and move this forward in anyway that I can.

I should note that I am technically "out of office" (which normally wouldn't mean much, but this time means that I am on a road-trip, and so am only at my computer infrequently). I am catching up on just a few emails here, but I'll be able to help out more (and would be honored to do so) once I am really back next Monday.

Provided that the eventual plan is to seriously evaluate a name other than "master", I think that this is a good way forward that clears the way for us to make this change easily, without forcing us to come to a conclusion on what name will replace "master" today.

For what it's worth, I am completely in favor of abandoning this term. My colleagues at GitHub (as has been mentioned previously on the list) are in favor of this as well, and it is my understanding that other providers feel similarly.

I would be in favor of any non-offensive name that we can reach consensus on. "trunk" sounds nice to me, but I think that it may cause problems for non-native English speakers, so perhaps "main" or "default" would suffice (maybe "main" is better, since it retains muscle memory for the first two characters without being offensive--at least, as far as I can tell. If I am wrong, please correct me and we should consider something else).

All of that said, I can't emphasize enough how little I care about *what* name we replace "master" with, so long as it is (1) replaced with a non-offensive term, (2) that that change is done uniformly throughout the "Git Ecosystem" and (3) that the community can reach consensus on the new term in a respectful, appropriate, and considerate way. I only provided a few suggestions to get the conversation flowing, although I suspect that my help isn't needed there.

Thanks,
Taylor

Hi Taylor,

I would _love_ to have git fetch origin master work, spitting out a message the main branch name changed to [...] please update your configuration.

And then maybe an easy way to update the configuration (git remote set-main-branch <nick> <refname> might make sense).

As you say, it is orthogonal to this here patch series, but definitely related in spirit because we _want_ to make it easier for users to move away from the current main branch name.

Sorry, my typo: it's Don, not Dan ;-)

Well, go back enjoying your road trip! :-P See you on Monday.

That is exactly the intention of this patch series.

I _do_ want to put my weight behind changing the default. Obviously, this will take quite a bit of time (but maybe less than I originally thought, as we are only talking about changing the default for _new_ repositories).

Even if this endeavor fails, though, this here patch series will be good to have.

From what I read at https://gitlab.com/gitlab-org/gitlab/-/issues/221164,
GitLab is on board, too.

My personal preference was "default" on Monday, and "main" ever since.

Indeed. I laid out the patch series in such a way that we should be able to pick a different default main branch name than "main", even if it is my current working hypothesis that this will prevail.

As I said, my preference was "default", and that's how my big patch series looked like, so I know how much work it is to change to a different name (because I changed it to "main"). It is quite a bit of work, but manageable.

Ciao,
Dscho

Hi,

Many people have expressed reservations against this change. Some on the list here, others in private conversation. I personally don't have a strong opinion on either side. So I'll refrain from saying too much on the issue. Reading through the list, I sense that the Git maintainer has already decided it is something good for the project. And so I think this change has a high chance of making it in a near future Git release.

One argument from those in favor of this change is that it doesn't affect you if you don't care about the default branch name. You can just go on using 'master' for all _your_ repos. I'd like to highlight the "your" here. Sure, I can keep on using 'master' if I so prefer, but I don't just use my repos. I also pull repos from other people, and I have no control over what they call their main/primary/master branch (I'll use "main" for the rest of the email). The cost here is that people now need to update their scripts and workflow to account for other people's naming preferences.

For example, my vim plugins are submodules in the '~/.vim/bundle' directory. When I want to update them, I run:

git submodule foreach 'git remote update && git reset --hard origin/master'

With this change hitting a Git release, more and more people would call their main branch different names they like. So what is the recommended way to do something like this now? How do I checkout the tip of the main branch? How do I push to the main branch? How do I pull from the main branch? And so on...

Regards,
Pratyush Yadav

Hi Pratyush,

From what you wrote below, I take it that you are not talking about this patch series, nor the follow-up one(s) to change the default main branch name for new repositories.

This talks about the scenario where a project you use decides to change their main branch name.

While this is a scenario that my patch series tries to support (by introducing the concept of core.mainBranch), it is not something my patch series _causes_.

All _this_ patch series does is to _allow_ changing the main branch name (manually) in an existing repository, and to change the default main branch name to use in new repositories.

Even the follow-up patch series I plan on contributing that changes the hard-coded default for the default main branch name to use in new repositories won't affect any existing repository.

So I think this example...

... has less to do with a new Git release, but more with the decision of an existing project to change their main branch name.

That's something users already had to deal with, of course. For example, projects switching to the Git Flow model will start to use the main branch name development.

GitHub Desktop changed their main branch name to development, and it did not require any new Git release.

GitHub CLI changed their main branch name to trunk.

Chrome and node.js stated their intention to change their main branch name to main.

And https://github.com/microsoft/git uses vfs-<version> where <version> corresponds to the Git (for Windows) version on which it is based, therefore the main branch name changes whenever there is a new Git version.

These challenges have existed for every project that chooses to change their main branch name, for whatever reason.

In other words, I think you are talking about a challenge that is orthogonal (if related, on a high level) to the subject this patch series tries to address.

Ciao,
Johannes

Hi Dscho,

I brought this concern up in a parallel thread but I'll bring it up here too since it's relevant. Currently, in the .gitmodules file, if the branch is not specified, it defaults to 'master'.

When I want to update my vim plugins, I run
git submodule update --remote which pulls in all of my submodules' 'master' branches. By convention, a lack of branch key in .gitmodules conventionally means 'master'.

With your change, it becomes the value of git_main_branch_name(), which is fine for now. However, if this value changes to something else, then when I update my Git, suddenly git submodule update --remote will be broken for me as all of the new repositories that I pull will be for an incorrect (and possibly missing) branch.

This leaves us in a scenario where one developer running an older version of Git would have submodule updates work perfectly fine while a developer with a newer version would have it suddenly broken. This might be hard to debug, especially for someone who doesn't follow the release notes around Git and doesn't realise why the default has suddenly changed.

This problem gets much worse if we allow the main branch name to be configurable as then the *private* configurations that a developer has may have an effect on the *publicly visible* behaviour of a repository.

I think I see three possible solutions to this:

1. Special case 'master' in submodules to retain backwards compatibility.

I don't think this is very appealing as if the change is made to use another default branch name, then the "default" branch for submodules would be "master" even though the new default everywhere else would be different. And in the future, someone who doesn't know the context behind all of this would be very confused where there are two different default branch names.

2. Disable 'update --remote' support for submodules that don't specify a branch.

If Git detects that a branch key is missing when trying to do an 'update --remote', it should just quit out and refuse to do anything. Of course, this a very backwards incompatible change and it would require several release cycles to implement where we warn users about this impending change before we actually make it happen.

3. Make 'update --remote' get HEAD.

I argue that this is how it always should've been implemented but, alas, I can't go back in time and fix it. Regardless, it might be good to flip this to be the default if we're going to be making the change anyway.

Unfortunately, this suffers from both the problems of 1 and 2. As with 1, we'll end up in a situation where users with different versions of Git may experience different behaviours given the same public repository and I think this is definitely undesirable. With 2, this change will also require a long deprecation period which I don't think it compatible with how people seem to want the default branch switch to happen this release.

So I dunno. I think my opinion leans on not changing the default branch at all. Since it seems like the consensus is generally that it _will_ change, I think I would prefer options 3, 2 and 1 in that order.

Thoughts?

Hi Denton,

My intuition matches your preference, and I have a strong preference for 3.

It took some banging my head (not my HEAD...) against the code to convince myself that the patch I prepared for v3 is good: I managed to confuse myself what with all those submodules and clones in t7406.

Ciao,
Dscho

This is a common issue that's long existed but may become more common as people change their branches. I believe when you clone that it by default pulls down a HEAD reference for the remote. So you can use origin/HEAD (a symref) in this case to use the correct default branch, whatever it may be called. Then your code doesn't have to care about the actual name, which is probably better anyway.

If you want to know the actual name, you can use this: git rev-parse --abbrev-ref origin/HEAD.

If the owner of the repository chooses to change that name or if you lack the HEAD reference for a remote, you can fix it with "git remote set-head origin -a".

I'll see if I can find time this week to work up a FAQ entry about how to do this, since it seems to be a common question folks have. I myself wasn't aware of "git remote set-head" until the other day, so I don't expect others to be familiar with it, either.

brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

A growing number of open source projects aims to avoid the branch name master due to its negative connotation. See [1] for an existing discussion on this. The links [2], [3], and [4] describe community-driven ways for users to rename their default branches or use template edits to set a new default branch name.

[1]
https://lore.kernel.org/git/CAOAHyQwyXC1Z3v7BZAC+Bq6JBaM7FvBenA-1fcqeDV==apdWDg@mail.gmail.com/

[2] https://twitter.com/mislav/status/1270388510684598272

[3]
https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx

[4] https://github.com/ethomson/retarget_prs

By necessity, existing repositories require a lot of manual work to move away from that branch name, but it should be much easier for new repositories.

This patch series allows overriding the branch name being used for new repositories' main branch, as well as telling Git about a renamed main branch in an already-existing repository. The former would be configured via init.defaultBranch and the latter via core.mainBranch (which is now automatically configured in git init).

Shell scripts can find out what the current repository's main branch name is called via

main_branch=$(git config core.mainBranch || echo master)

This is even future proof because all future git init invocations will configure that setting.

The initial patch was started by newcomer Don Goodman-Wilson, as well as the bigger change that morphed into #655, where we demonstrate how to change Git's hard-coded default main branch name to main based on this here patch series, verifying the approach. Thanks for the contribution!

This series DOES NOT change the default automatically, but only provides an opt-in mechanism for interested users. The plan for that is to convert the test scripts incrementally (by introducing GIT_TEST_DEFAULT_MAIN_BRANCH_NAME , which overrides init.defaultBranch, and then converting the tricky test scripts first, one by one, using that environment variable).

Changes since v1:

* The modifications to respect GIT_TEST_DEFAULT_BRANCH_NAME have been backed out from this patch series, as they are only relevant once we start converting the test suite to accommodate for a new default main branch name.

* An error message that started with an upper-case letter was downcased.

* git_default_branch_name()'s logic was simplified by replacing an if ... else ... by a ternary assignment.

* The git_default_branch_name() function was renamed to git_main_branch_name() and a corresponding repo_main_branch_name() was introduced.

* The "init" commit message's first paragraph now elaborates a little bit on the reasoning why projects want to move away from the current default branch name.

* The "init" commit was split into two.

* There are now two config settings: init.defaultBranch (defining the branch name to use when initializing new repositories) and core.mainBranch (which is now configured by init_db(), declaring what the name of the main branch is in this repository).

* The commits were re-ordered to introduce the concept of core.mainBranch first because technically, this is something that we could do even without changing git init at all.

* git fast-export --anonymize now always uses the ref name ref0 for the main branch, no matter whether it was overridden or whether the fall-back is in effect.

* The code comment regarding anonymizing the main branch to ref0 in git fast-export --anonymize was enhanced.

* A new patch was added to rename core.mainBranch if the main branch is renamed via git branch -m.

* Added a patch that introduces support for git init --main-branch=<branch-name>.

* Where possible, I added tests (although I did not try to extend test coverage to all changes: the send-pack.c/transport-helper.c patch only adds a test for the send-pack.c adjustment, for example).

Don Goodman-Wilson (1):
init: allow overriding the default main branch name via the config

Johannes Schindelin (10):
fmt-merge-msg: introduce a way to override the main branch name send-pack/transport-helper: respect core.mainBranch git_main_branch_name(): optionally report the full ref name
fast-export: handle overridden main branch names correctly branch -m: adjust core.mainBranch if necessary
init: allow specifying the main branch name for the new repository
clone: handle overridden main branch names
remote: learn about the possibly-overridden default main branch name
submodule: use the correct default for the main branch name
testsvn: respect init.defaultBranch

Junio C Hamano (1):
fast-export: do anonymize the primary branch name

 Documentation/config/core.txt    |  5 +++++
 Documentation/config/init.txt    |  4 ++++
 Documentation/git-init.txt       |  7 +++++++
 builtin/branch.c                 |  9 ++++++++
 builtin/clone.c                  | 19 +++++++++++++----
 builtin/fast-export.c            | 20 +++++++++++++-----
 builtin/init-db.c                | 36 +++++++++++++++++++++++++-------
 builtin/submodule--helper.c      | 10 +++++++--
 cache.h                          |  2 +-
 fmt-merge-msg.c                  |  6 ++++--
 refs.c                           | 34 ++++++++++++++++++++++++++++++
 refs.h                           | 15 +++++++++++++
 remote-testsvn.c                 | 12 ++++++++---
 remote.c                         | 15 ++++++++-----
 send-pack.c                      |  6 +++++-
 t/t0001-init.sh                  | 31 +++++++++++++++++++++++++++
 t/t3200-branch.sh                |  9 ++++++++
 t/t5528-push-default.sh          |  7 +++++++
 t/t5606-clone-options.sh         | 26 +++++++++++++++++++++++
 t/t6200-fmt-merge-msg.sh         |  7 +++++++
 t/t7406-submodule-update.sh      |  7 +++++++
 t/t9020-remote-svn.sh            |  6 ++++++
 t/t9351-fast-export-anonymize.sh | 15 +++++++++----
 transport-helper.c               |  6 +++++-
 24 files changed, 279 insertions(+), 35 deletions(-)

base-commit: 0313f36c6ebecb3bffe6f15cf25a4883100f0214
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-656%2Fdscho%2Fdefault-branch-name-option-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-656/dscho/default-branch-name-option-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/656

Range-diff vs v1:

  -:  ----------- >  1:  ebd10f73cd7 fast-export: do anonymize the primary branch name
  7:  e849def4a8c !  2:  f4d54739153 fmt-merge-msg: learn about the possibly-configured default branch name
     @@ Metadata
      Author: Johannes Schindelin <[email protected]>
      
       ## Commit message ##
     -    fmt-merge-msg: learn about the possibly-configured default branch name
     +    fmt-merge-msg: introduce a way to override the main branch name
      
     -    When formatting the commit message for merge commits, Git appends "into
     -    <branch-name>" unless the current branch is the default branch.
     +    There is a growing number of projects and companies desiring to change
     +    the main branch name of their repositories (see e.g.
     +    https://twitter.com/mislav/status/1270388510684598272 for background on
     +    this).
      
     -    Now that we can configure what the default branch name should be, we
     -    will want to respect that setting in that scenario rather than using the
     -    compiled-in default branch name.
     +    However, there are a couple of hard-coded spots in Git's source code
     +    that make this endeavor harder than necessary. For example, when
     +    formatting the commit message for merge commits, Git appends "into
     +    <branch-name>" unless the current branch is the `master` branch.
     +
     +    Clearly, this is not what one wants when already having gone through all
     +    the steps to manually rename the main branch (and taking care of all the
     +    fall-out such as re-targeting existing Pull Requests).
     +
     +    Let's introduce a way to override Git's hard-coded default:
     +    `core.mainBranch`.
     +
     +    We will start supporting this config option in the `git fmt-merge-msg`
     +    command and successively adjust all other places where the main branch
     +    name is hard-coded.
      
          Signed-off-by: Johannes Schindelin <[email protected]>
      
     + ## Documentation/config/core.txt ##
     +@@ Documentation/config/core.txt: core.abbrev::
     + 	in your repository, which hopefully is enough for
     + 	abbreviated object names to stay unique for some time.
     + 	The minimum length is 4.
     ++
     ++core.mainBranch::
     ++	The name of the main (or: primary) branch in the current repository.
     ++	For historical reasons, `master` is used as the fall-back for this
     ++	setting.
     +
       ## fmt-merge-msg.c ##
      @@ fmt-merge-msg.c: static void fmt_merge_msg_title(struct strbuf *out,
       				const char *current_branch)
       {
       	int i = 0;
      -	char *sep = "";
     -+	char *sep = "", *default_branch_name;
     ++	char *sep = "", *main_branch;
       
       	strbuf_addstr(out, "Merge ");
       	for (i = 0; i < srcs.nr; i++) {
     @@ fmt-merge-msg.c: static void fmt_merge_msg_title(struct strbuf *out,
       	}
       
      -	if (!strcmp("master", current_branch))
     -+	default_branch_name = git_default_branch_name(1);
     -+	if (!strcmp(default_branch_name, current_branch))
     ++	main_branch = git_main_branch_name();
     ++	if (!strcmp(main_branch, current_branch))
       		strbuf_addch(out, '\n');
       	else
       		strbuf_addf(out, " into %s\n", current_branch);
     -+	free(default_branch_name);
     ++	free(main_branch);
       }
       
       static void fmt_tag_signature(struct strbuf *tagbuf,
      
     + ## refs.c ##
     +@@ refs.c: void expand_ref_prefix(struct argv_array *prefixes, const char *prefix)
     + 		argv_array_pushf(prefixes, *p, len, prefix);
     + }
     + 
     ++char *repo_main_branch_name(struct repository *r)
     ++{
     ++	const char *config_key = "core.mainbranch";
     ++	const char *config_display_key = "core.mainBranch";
     ++	const char *fall_back = "master";
     ++	char *name = NULL, *ret;
     ++
     ++	if (repo_config_get_string(r, config_key, &name) < 0)
     ++		die(_("could not retrieve `%s`"), config_display_key);
     ++
     ++	ret = name ? name : xstrdup(fall_back);
     ++
     ++	if (check_refname_format(ret, REFNAME_ALLOW_ONELEVEL))
     ++		die(_("invalid branch name: %s = %s"),
     ++		    config_display_key, name);
     ++
     ++	if (name != ret)
     ++		free(name);
     ++
     ++	return ret;
     ++}
     ++
     ++char *git_main_branch_name(void)
     ++{
     ++	return repo_main_branch_name(the_repository);
     ++}
     ++
     + /*
     +  * *string and *len will only be substituted, and *string returned (for
     +  * later free()ing) if the string passed in is a magic short-hand form
     +
     + ## refs.h ##
     +@@ refs.h: int repo_dwim_log(struct repository *r, const char *str, int len, struct object_
     + int dwim_ref(const char *str, int len, struct object_id *oid, char **ref);
     + int dwim_log(const char *str, int len, struct object_id *oid, char **ref);
     + 
     ++/*
     ++ * Retrieves the name of the main (or: primary) branch of the given
     ++ * repository.
     ++ */
     ++char *git_main_branch_name(void);
     ++char *repo_main_branch_name(struct repository *r);
     ++
     + /*
     +  * A ref_transaction represents a collection of reference updates that
     +  * should succeed or fail together.
     +
       ## t/t6200-fmt-merge-msg.sh ##
      @@ t/t6200-fmt-merge-msg.sh: test_expect_success 'setup FETCH_HEAD' '
       	git fetch . left
       '
       
      +test_expect_success 'with overridden default branch name' '
     -+	test_config core.defaultBranchName default &&
      +	test_when_finished "git switch master" &&
      +	git switch -c default &&
     -+	git fmt-merge-msg <.git/FETCH_HEAD >actual &&
     ++	git -c core.mainBranch=default fmt-merge-msg <.git/FETCH_HEAD >actual &&
      +	! grep "into default" actual
      +'
      +

3: c9c9c81068e ! 3: bd8af3755ad send-pack/transport-helper: respect core.defaultBranchName
@@ Metadata
Author: Johannes Schindelin <[email protected]>

## Commit message ##
- send-pack/transport-helper: respect core.defaultBranchName
+ send-pack/transport-helper: respect core.mainBranch

- When mentioning the default branch name in an error message, we want to
- go with the preference specified by the user.
+ When mentioning the main branch name in an error message, we want to go
+ with the preference specified by the user, only falling back to Git's
+ own, hard-coded default when none was configured explicitly.

@@ send-pack.c: int send_pack(struct send_pack_args *args,
}

if (!remote_refs) {
-+ char *branch_name = git_default_branch_name(1);
++ char *branch_name = git_main_branch_name();
+
fprintf(stderr, "No refs in common and none specified; doing nothing.\n"
- "Perhaps you should specify a branch such as 'master'.\n");
@@ send-pack.c: int send_pack(struct send_pack_args *args,
}
if (args->atomic && !atomic_supported)

+ ## t/t5528-push-default.sh ##
+@@ t/t5528-push-default.sh: test_expect_success 'push from/to new branch with upstream, matching and simple'
+ test_push_failure upstream
+ '
+
++test_expect_success '"matching" fails if none match' '
++ git init --bare empty &&
++ test_must_fail git -c core.mainBranch=unmatch push empty : 2>actual &&
++ needle="Perhaps you should specify a branch such as '\''unmatch'\''" &&
++ test_i18ngrep "$needle" actual
++'
++
+ test_expect_success 'push ambiguously named branch with upstream, matching and simple' '
+ git checkout -b ambiguous &&
+ test_config branch.ambiguous.remote parent1 &&
+
## transport-helper.c ##
@@ transport-helper.c: static int push_refs(struct transport *transport,
}

if (!remote_refs) {
-+ char *branch_name = git_default_branch_name(1);
++ char *branch_name = git_main_branch_name();
+
fprintf(stderr,
_("No refs in common and none specified; doing nothing.\n"

  -:  ----------- >  4:  ca1c63c3e01 git_main_branch_name(): optionally report the full ref name
  8:  1efe848f2b0 !  5:  a3be4f39aa2 fast-export: respect the possibly-overridden default branch name

@@ Metadata
Author: Johannes Schindelin <[email protected]>

## Commit message ##
- fast-export: respect the possibly-overridden default branch name
+ fast-export: handle overridden main branch names correctly

- When anonymizing commit history, we are careful to leave the branch name
- of the default branch alone.
+ When anonymizing commit history, we are careful to translate the main
+ branch name to ref0.

- When the default branch name is overridden via the config or via the
- environment variable, we will want git fast-export to use that
- overridden name instead.
+ When the main branch name is overridden via the config, we will want
+ git fast-export to use that overridden name instead.

@@ builtin/fast-export.c: static const char *anonymize_refname(const char *refname)
};
static struct hashmap refs;
static struct strbuf anon = STRBUF_INIT;
-+ static char *default_branch_name;
++ static char *main_branch;
int i;

/*
-- * We also leave "master" as a special case, since it does not reveal
-- * anything interesting.
-+ * We also leave the default branch name as a special case, since it
-+ * does not reveal anything interesting.
+ * In certain circumstances, it might be interesting to be able to
+ * identify the main branch. For that reason, let's force its name to
+ * be anonymized to ref0.
++ *
++ * While the main branch name might often be main for new
++ * repositories (and master for aged ones), and such well-known names
++ * may not necessarily need anonymizing, it could be configured to use
++ * a secret word that the user may not want to reveal.
*/
- if (!strcmp(refname, "refs/heads/master"))
-+ if (!default_branch_name)
-+ default_branch_name = git_default_branch_name(0);
++ if (!main_branch)
++ main_branch = git_main_branch_name(MAIN_BRANCH_FULL_NAME);
+
-+ if (!strcmp(refname, default_branch_name))
- return refname;
++ if (!strcmp(refname, main_branch))
+ return "refs/heads/ref0";

strbuf_reset(&anon);
+
+ ## t/t9351-fast-export-anonymize.sh ##
+@@ t/t9351-fast-export-anonymize.sh: test_expect_success 'stream translates master to ref0' '
+ ! grep master stream
+ '
+
++test_expect_success 'respects configured main branch' '
++ git -c core.mainBranch=does-not-exist \
++ fast-export --anonymize --all >stream-without-ref0 &&
++ ! grep ref0 stream-without-ref0
++'
++
+ test_expect_success 'stream omits other refnames' '
+ ! grep other stream &&
+ ! grep mytag stream

  -:  ----------- >  6:  933e314813d branch -m: adjust `core.mainBranch` if necessary
  1:  90912e32da1 !  7:  0ec04b2086e init: allow overriding the default branch name for new repositories

@@
## Metadata ##
-Author: Don Goodman-Wilson <[email protected]> +Author: Johannes Schindelin <[email protected]>

## Commit message ##
- init: allow overriding the default branch name for new repositories
+ init: allow specifying the main branch name for the new repository

There is a growing number of projects trying to avoid the non-inclusive
- name master in their repositories. For existing repositories, this
- requires manual work. For new repositories, the only way to do that
- automatically is by copying all of Git's template directory, then
- hard-coding the desired default branch name into the .git/HEAD file,
- and then configuring init.templateDir to point to those copied
+ name master in their repositories: The master/slave terminology is
+ insensitive and perpetuates injustice. This master/slave idea is
+ actually where Git's naming comes from, as it was inherited from
+ BitKeeper which uses the term in exactly this way, see
+ https://mail.gnome.org/archives/desktop-devel-list/2019-May/msg00066.html
+
+ To change that branch name for new repositories, currently the only way
+ to do that automatically is by copying all of Git's template directory,
+ then hard-coding the desired default branch name into the .git/HEAD
+ file, and then configuring init.templateDir to point to those copied
template files.

- To make this process much less cumbersome, let's introduce support for
- core.defaultBranchName. That way, users won't need to keep their
- copied template files up to date, and won't interfere with default hooks
- installed by their administrators.
+ To make this process much less cumbersome, let's introduce a new option:
+ --main-branch=<branch-name>.

- While at it, also let users set the default branch name via the
- environment variable GIT_TEST_DEFAULT_BRANCH_NAME, in preparation for
- adjusting Git's test suite to a more inclusive default branch name. As
- is common in Git, the GIT_TEST_* variable takes precedence over the
- config setting.
+ This will not only initialize the repository with the specified initial
+ branch; It will also record that branch name in core.mainBranch.

- Note: we use the prefix core. instead of init. because we want to
- adjust also git clone, git fmt-merge-msg and other commands over the
- course of the next commits to respect this setting.
+ Signed-off-by: Johannes Schindelin <[email protected]>

- Helped-by: Johannes Schindelin <[email protected]>
- Helped-by: Derrick Stolee <[email protected]>
- Signed-off-by: Don Goodman-Wilson <[email protected]>
+ ## Documentation/git-init.txt ##
+@@ Documentation/git-init.txt: SYNOPSIS
+ [verse]
+ 'git init' [-q | --quiet] [--bare] [--template=<template_directory>]
+ [--separate-git-dir <git dir>] [--object-format=<format]
++ [-b <branch-name> | --main-branch=<branch-name>]
+ [--shared[=<permissions>]] [directory]
+
+
+@@ Documentation/git-init.txt: repository.
+ +
+ If this is reinitialization, the repository will be moved to the specified path. +
++-b <branch-name::
++--main-branch=<branch-name>::
++
++Use the specified name for the main (or: initial) branch in the newly created ++repository. If not specified, fall back to the default name: master. ++
+ --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
+
+ Specify that the Git repository is to be shared amongst several users. This +
+ ## builtin/clone.c ##
+@@ builtin/clone.c: int cmd_clone(int argc, const char **argv, const char *prefix)
+ }
+ }
+
+- init_db(git_dir, real_git_dir, option_template, GIT_HASH_UNKNOWN, INIT_DB_QUIET);
++ init_db(git_dir, real_git_dir, option_template, GIT_HASH_UNKNOWN, NULL,
++ INIT_DB_QUIET);
+
+ if (real_git_dir)
+ git_dir = real_git_dir;

## builtin/init-db.c ##
+@@ builtin/init-db.c: void initialize_repository_version(int hash_algo) +
+ static int create_default_files(const char *template_path,
+ const char *original_git_dir,
++ const char *main_branch,
+ const struct repository_format *fmt)
+ {
+ struct stat st1;
@@ builtin/init-db.c: static int create_default_files(const char *template_path,
die("failed to set up refs db: %s", err.buf);

@@ builtin/init-db.c: static int create_default_files(const char *template_path,
|| readlink(path, junk, sizeof(junk)-1) != -1);
if (!reinit) {
- if (create_symref("HEAD", "refs/heads/master", NULL) < 0)
-+ char *default_ref = git_default_branch_name(0);
-+ if (create_symref("HEAD", default_ref, NULL) < 0)
++ char *ref;
++
++ if (!main_branch)
++ main_branch = "master";
++
++ ref = xstrfmt("refs/heads/%s", main_branch);
++ if (check_refname_format(ref, 0) < 0)
++ die(_("invalid main branch name: '%s'"), main_branch);
++
++ if (create_symref("HEAD", ref, NULL) < 0)
exit(1);
-+ free(default_ref);
- }
+- }
++ free(ref);
++
++ git_config_set("core.mainbranch", main_branch);
++ } else if (main_branch)
++ warning(_("re-init: ignoring --main-branch=%s"), main_branch);

initialize_repository_version(fmt->hash_algo);
-
- ## refs.c ##
-@@ refs.c: void expand_ref_prefix(struct argv_array *prefixes, const char *prefix)
- argv_array_pushf(prefixes, *p, len, prefix);
+
+@@ builtin/init-db.c: static void validate_hash_algorithm(struct repository_format *repo_fmt, int hash
}

-+char *git_default_branch_name(int short_name)
-+{
-+ const char *branch_name = getenv("GIT_TEST_DEFAULT_BRANCH_NAME");
-+ char *from_config = NULL, *prefixed;
-+
-+ /*
-+ * If the default branch name was not specified via the environment
-+ * variable GIT_TEST_DEFAULT_BRANCH_NAME, retrieve it from the config
-+ * setting core.defaultBranchName. If neither are set, fall back to the
-+ * hard-coded default.
-+ */
-+ if (!branch_name || !*branch_name) {
-+ if (git_config_get_string("core.defaultbranchname",
-+ &from_config) < 0)
-+ die(_("Could not retrieve core.defaultBranchName"));
-+
-+ if (from_config)
-+ branch_name = from_config;
-+ else
-+ branch_name = "master";
-+ }
-+
-+ if (short_name)
-+ return from_config ? from_config : xstrdup(branch_name);
-+
-+ /* prepend "refs/heads/" to the branch name */
-+ prefixed = xstrfmt("refs/heads/%s", branch_name);
-+ if (check_refname_format(prefixed, 0))
-+ die(_("invalid default branch name: '%s'"), branch_name);
-+
-+ free(from_config);
-+ return prefixed;
-+}
-+
- /*
- * *string and *len will only be substituted, and *string returned (for
- * later free()ing) if the string passed in is a magic short-hand form
+ int init_db(const char *git_dir, const char *real_git_dir,
+- const char *template_dir, int hash, unsigned int flags)
++ const char *template_dir, int hash, const char *main_branch,
++ unsigned int flags)
+ {
+ int reinit;
+ int exist_ok = flags & INIT_DB_EXIST_OK;
+@@ builtin/init-db.c: int init_db(const char *git_dir, const char *real_git_dir, +
+ validate_hash_algorithm(&repo_fmt, hash);
+
+- reinit = create_default_files(template_dir, original_git_dir, &repo_fmt);
++ reinit = create_default_files(template_dir, original_git_dir,
++ main_branch, &repo_fmt);
+
+ create_object_directory();
+
+@@ builtin/init-db.c: int cmd_init_db(int argc, const char **argv, const char *prefix)
+ const char *template_dir = NULL;
+ unsigned int flags = 0;
+ const char *object_format = NULL;
++ const char *main_branch = NULL;
+ int hash_algo = GIT_HASH_UNKNOWN;
+ const struct option init_db_options[] = {
+ OPT_STRING(0, "template", &template_dir, N_("template-directory"),
+@@ builtin/init-db.c: int cmd_init_db(int argc, const char **argv, const char *prefix)
+ OPT_BIT('q', "quiet", &flags, N_("be quiet"), INIT_DB_QUIET),
+ OPT_STRING(0, "separate-git-dir", &real_git_dir, N_("gitdir"),
+ N_("separate git dir from working tree")),
++ OPT_STRING('b', "main-branch", &main_branch, N_("name"),
++ N_("override the name of the main branch")),
+ OPT_STRING(0, "object-format", &object_format, N_("hash"),
+ N_("specify the hash algorithm to use")),
+ OPT_END()
+@@ builtin/init-db.c: int cmd_init_db(int argc, const char **argv, const char *prefix)
+ UNLEAK(work_tree);
+
+ flags |= INIT_DB_EXIST_OK;
+- return init_db(git_dir, real_git_dir, template_dir, hash_algo, flags);
++ return init_db(git_dir, real_git_dir, template_dir, hash_algo,
++ main_branch, flags);
+ }

- ## refs.h ##
-@@ refs.h: int repo_dwim_log(struct repository *r, const char *str, int len, struct object_
- int dwim_ref(const char *str, int len, struct object_id *oid, char **ref);
- int dwim_log(const char *str, int len, struct object_id *oid, char **ref); -
-+/*
-+ * Retrieves the name of the default branch. If short_name is non-zero, the -+ * branch name will be prefixed with "refs/heads/".
-+ */
-+char *git_default_branch_name(int short_name);
-+
- /*
- * A ref_transaction represents a collection of reference updates that
- * should succeed or fail together.
+ ## cache.h ##
+@@ cache.h: int path_inside_repo(const char *prefix, const char *path);
+
+ int init_db(const char *git_dir, const char *real_git_dir,
+ const char *template_dir, int hash_algo,
+- unsigned int flags);
++ const char *main_branch, unsigned int flags);
+ void initialize_repository_version(int hash_algo);
+
+ void sanitize_stdfds(void);

## t/t0001-init.sh ##
@@ t/t0001-init.sh: test_expect_success MINGW 'redirect std handles' '
grep "Needed a single revision" output.txt
'

-+test_expect_success 'custom default branch name from config' '
-+ git config --global core.defaultbranchname nmb &&
-+ GIT_TEST_DEFAULT_BRANCH_NAME= git init custom-config &&
-+ git config --global --unset core.defaultbranchname &&
-+ git -C custom-config symbolic-ref HEAD >actual &&
-+ grep nmb actual
-+'
-+
-+test_expect_success 'custom default branch name from env' '
-+ GIT_TEST_DEFAULT_BRANCH_NAME=nmb git init custom-env &&
-+ git -C custom-env symbolic-ref HEAD >actual &&
-+ grep nmb actual
-+'
++test_expect_success '--main-branch' '
++ git init --main-branch=hello main-branch-option &&
++ git -C main-branch-option symbolic-ref HEAD >actual &&
++ echo refs/heads/hello >expect &&
++ test_cmp expect actual &&
+
-+test_expect_success 'invalid custom default branch name' '
-+ test_must_fail env GIT_TEST_DEFAULT_BRANCH_NAME="with space" \
-+ git init custom-invalid 2>err &&
-+ test_i18ngrep "invalid default branch name" err
++ : re-initializing should not change the main branch name &&
++ git init --main-branch=ignore main-branch-option 2>err &&
++ test_i18ngrep "ignoring --main-branch" err &&
++ git -C main-branch-option symbolic-ref HEAD >actual &&
++ grep hello actual &&
++ git -C main-branch-option config core.mainBranch >actual &&
++ grep hello actual
+'
+
test_done

  -:  ----------- >  8:  c711eba7e76 init: allow overriding the default main branch name via the config
  6:  cce86c06bbf !  9:  0e59b618169 clone: learn about the possibly-configured default branch name
     @@ Metadata
      Author: Johannes Schindelin <[email protected]>
      
       ## Commit message ##
     -    clone: learn about the possibly-configured default branch name
     +    clone: handle overridden main branch names
      
          When cloning a repository without any branches, Git chooses a default
          branch name for the as-yet unborn branch.
      
     -    Now that we can configure what the default branch name should be, we
     -    will want `git clone` to respect that setting.
     +    As part of the implicit initialization of the local repository, Git
     +    just learned to respect `init.defaultBranch` to choose a different main
     +    branch name. We now really want that branch name to be used as a
     +    fall-back.
     +
     +    At the same time, we also want to make sure that `core.mainBranch` is
     +    set correctly, reflecting the name of the main branch. In case we detect
     +    a main branch, we do have to do that explicitly, otherwise `init_db()`
     +    will already have done that for us.
      
          Signed-off-by: Johannes Schindelin <[email protected]>
      
     + ## Documentation/config/init.txt ##
     +@@ Documentation/config/init.txt: init.templateDir::
     + 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
     + 
     + init.defaultBranch::
     +-	Allows overriding the default branch name when initializing
     +-	a new repository.
     ++	Allows overriding the default branch name e.g. when initializing
     ++	a new repository or when cloning an empty repository.
     +
       ## builtin/clone.c ##
     +@@ builtin/clone.c: static void update_head(const struct ref *our, const struct ref *remote,
     + 		/* Local default branch link */
     + 		if (create_symref("HEAD", our->name, NULL) < 0)
     + 			die(_("unable to update HEAD"));
     ++		git_config_set("core.mainbranch", head);
     + 		if (!option_bare) {
     + 			update_ref(msg, "HEAD", &our->old_oid, NULL, 0,
     + 				   UPDATE_REFS_DIE_ON_ERR);
      @@ builtin/clone.c: int cmd_clone(int argc, const char **argv, const char *prefix)
       		remote_head_points_at = NULL;
       		remote_head = NULL;
     @@ builtin/clone.c: int cmd_clone(int argc, const char **argv, const char *prefix)
      -			install_branch_config(0, "master", option_origin,
      -					      "refs/heads/master");
      +		if (!option_bare) {
     -+			char *default_branch = git_default_branch_name(0);
     ++			char *main_branch =
     ++				git_main_branch_name(MAIN_BRANCH_FULL_NAME);
      +			const char *nick;
      +
     -+			if (!skip_prefix(default_branch, "refs/heads/", &nick))
     ++			if (!skip_prefix(main_branch, "refs/heads/", &nick))
      +				BUG("unexpected default branch '%s'",
     -+				    default_branch);
     ++				    main_branch);
      +			install_branch_config(0, nick, option_origin,
     -+					      default_branch);
     -+			free(default_branch);
     ++					      main_branch);
     ++			free(main_branch);
      +		}
       	}
       
       	write_refspec_config(src_ref_prefix, our_head_points_at,
      
     - ## t/t5609-clone-branch.sh ##
     -@@ t/t5609-clone-branch.sh: test_expect_success 'clone -b not allowed with empty repos' '
     - 	test_must_fail git clone -b branch empty clone-branch-empty
     + ## t/t5606-clone-options.sh ##
     +@@ t/t5606-clone-options.sh: test_expect_success 'redirected clone -v does show progress' '
     + 
       '
       
     -+test_expect_success 'chooses correct default branch name' '
     -+	GIT_TEST_DEFAULT_BRANCH_NAME= \
     -+		git -c core.defaultBranchName=up clone empty whats-up &&
     -+	test_write_lines refs/heads/up refs/heads/up >expect &&
     -+	git -C whats-up symbolic-ref HEAD >actual &&
     -+	git -C whats-up config branch.up.merge >>actual &&
     -+	test_cmp expect actual
     ++test_expect_success 'chooses correct default main branch name' '
     ++	git init --bare empty &&
     ++	git -c init.defaultBranch=up clone empty whats-up &&
     ++	test refs/heads/up = $(git -C whats-up symbolic-ref HEAD) &&
     ++	test up = $(git -C whats-up config core.mainBranch) &&
     ++	test refs/heads/up = $(git -C whats-up config branch.up.merge)
     ++'
     ++
     ++test_expect_success 'guesses main branch name correctly' '
     ++	git init --main-branch=guess main-branch &&
     ++	test_commit -C main-branch no-spoilers &&
     ++	git -C main-branch branch abc guess &&
     ++	git clone main-branch is-it &&
     ++	test guess = $(git -C is-it config core.mainBranch) &&
     ++	test refs/heads/guess = $(git -C is-it symbolic-ref HEAD)
      +'
      +
       test_done
  2:  06a2cea051c ! 10:  59b8f4cfbb2 remote: respect `core.defaultBranchName`
     @@ Metadata
      Author: Johannes Schindelin <[email protected]>
      
       ## Commit message ##
     -    remote: respect `core.defaultBranchName`
     +    remote: learn about the possibly-overridden default main branch name
      
          When guessing the default branch name of a remote, and there are no refs
          to guess from, we want to go with the preference specified by the user
     -    for the fall-back.
     +    for the fall-back, i.e. the default name to be used for the main branch
     +    of new repositories (because as far as the user is concerned, a remote
     +    that has no branches yet is a new repository).
      
          Signed-off-by: Johannes Schindelin <[email protected]>
      
     @@ remote.c: static void read_remotes_file(struct remote *remote)
       static void read_branches_file(struct remote *remote)
       {
      -	char *frag;
     -+	char *frag, *default_branch_name = NULL;
     ++	char *frag, *main_branch = NULL;
       	struct strbuf buf = STRBUF_INIT;
       	FILE *f = fopen_or_warn(git_path("branches/%s", remote->name), "r");
       
     @@ remote.c: static void read_branches_file(struct remote *remote)
       	/*
       	 * The branches file would have URL and optionally
      -	 * #branch specified.  The "master" (or specified) branch is
     -+	 * #branch specified.  The default (or specified) branch is
     ++	 * #branch specified.  The main (or specified) branch is
       	 * fetched and stored in the local branch matching the
       	 * remote name.
       	 */
     @@ remote.c: static void read_branches_file(struct remote *remote)
       		*(frag++) = '\0';
       	else
      -		frag = "master";
     -+		frag = default_branch_name = git_default_branch_name(1);
     ++		frag = main_branch = git_main_branch_name(MAIN_BRANCH_FOR_INIT);
       
       	add_url_alias(remote, strbuf_detach(&buf, NULL));
       	strbuf_addf(&buf, "refs/heads/%s:refs/heads/%s",
     @@ remote.c: static void read_branches_file(struct remote *remote)
       	strbuf_addf(&buf, "HEAD:refs/heads/%s", frag);
       	refspec_append(&remote->push, buf.buf);
       	remote->fetch_tags = 1; /* always auto-follow */
     -+	free(default_branch_name);
     ++	free(main_branch);
       	strbuf_release(&buf);
       }
       
      @@ remote.c: struct ref *guess_remote_head(const struct ref *head,
     + 	if (head->symref)
     + 		return copy_ref(find_ref_by_name(refs, head->symref));
       
     - 	/* If refs/heads/master could be right, it is. */
     +-	/* If refs/heads/master could be right, it is. */
     ++	/* If a remote branch exists with the main branch name, let's use it. */
       	if (!all) {
      -		r = find_ref_by_name(refs, "refs/heads/master");
     -+		char *name = git_default_branch_name(0);
     ++		char *name = git_main_branch_name(MAIN_BRANCH_FULL_NAME |
     ++						  MAIN_BRANCH_FOR_INIT);
      +
      +		r = find_ref_by_name(refs, name);
      +		free(name);
       		if (r && oideq(&r->old_oid, &head->old_oid))
       			return copy_ref(r);
       	}
     +
     + ## t/t5606-clone-options.sh ##
     +@@ t/t5606-clone-options.sh: test_expect_success 'guesses main branch name correctly' '
     + 	git -C main-branch branch abc guess &&
     + 	git clone main-branch is-it &&
     + 	test guess = $(git -C is-it config core.mainBranch) &&
     +-	test refs/heads/guess = $(git -C is-it symbolic-ref HEAD)
     ++	test refs/heads/guess = $(git -C is-it symbolic-ref HEAD) &&
     ++
     ++	git -c init.defaultBranch=none init --bare no-head &&
     ++	git -C main-branch push ../no-head guess abc &&
     ++	git clone no-head is-it2 &&
     ++	test_must_fail git -C is-it2 symbolic-ref refs/remotes/origin/HEAD &&
     ++	git -C no-head update-ref --no-deref HEAD refs/heads/guess &&
     ++	git -c init.defaultBranch=guess clone no-head is-it3 &&
     ++	test refs/remotes/origin/guess = \
     ++		$(git -C is-it3 symbolic-ref refs/remotes/origin/HEAD)
     + '
     + 
     + test_done
  5:  06ef42052d5 ! 11:  59d6267f099 submodule: use the (possibly overridden) default branch name
     @@ Metadata
      Author: Johannes Schindelin <[email protected]>
      
       ## Commit message ##
     -    submodule: use the (possibly overridden) default branch name
     +    submodule: use the correct default for the main branch name
      
          To allow for overriding the default branch name, we have introduced a
          config setting. With this patch, the `git submodule` command learns
     @@ builtin/submodule--helper.c: static const char *remote_submodule_branch(const ch
      -	if (!branch)
      -		return "master";
      +	if (!branch) {
     -+		static char *default_branch;
     ++		static char *fall_back;
      +
     -+		if (!default_branch)
     -+			default_branch = git_default_branch_name(1);
     ++		if (!fall_back)
     ++			fall_back = git_main_branch_name(MAIN_BRANCH_FOR_INIT);
      +
     -+		return default_branch;
     ++		return fall_back;
      +	}
       
       	if (!strcmp(branch, ".")) {
       		const char *refname = resolve_ref_unsafe("HEAD", 0, NULL, NULL);
     +
     + ## t/t7406-submodule-update.sh ##
     +@@ t/t7406-submodule-update.sh: test_expect_success 'setup a submodule tree' '
     + 	)
     + '
     + 
     ++test_expect_success 'update --remote uses configured default main branch' '
     ++	git clone super main-branch &&
     ++	test_must_fail git -C main-branch -c init.defaultBranch=hello \
     ++		submodule update --init --remote submodule 2>err &&
     ++	test_i18ngrep origin/hello err
     ++'
     ++
     + test_expect_success 'submodule update detaching the HEAD ' '
     + 	(cd super/submodule &&
     + 	 git reset --hard HEAD~1
  4:  73cb567cd33 ! 12:  e09f857f068 testsvn: respect `core.defaultBranchName`
     @@ Metadata
      Author: Johannes Schindelin <[email protected]>
      
       ## Commit message ##
     -    testsvn: respect `core.defaultBranchName`
     +    testsvn: respect `init.defaultBranch`
      
     -    Since the default branch name can now be configured, the `testsvn`
     -    remote helper needs to be told about it.
     +    The default name of the main branch in new repositories can now be
     +    configured. The `testsvn` remote helper translates the remote Subversion
     +    repository's branch name `trunk` to the hard-coded name `master`.
     +    Clearly, the intention was to make the name align with Git's detaults.
     +
     +    So while we are not talking about a newly-created repository in the
     +    `testsvn` context, it _still_ makes sense to use the overridden default
     +    name for the main branch whenever users configured it.
      
          Signed-off-by: Johannes Schindelin <[email protected]>
      
     @@ remote-testsvn.c: int cmd_main(int argc, const char **argv)
       			notes_ref_sb = STRBUF_INIT;
       	static struct remote *remote;
      -	const char *url_in;
     -+	const char *url_in, *default_branch;
     ++	const char *url_in, *remote_ref_short;
       
       	setup_git_directory();
       	if (argc < 2 || argc > 3) {
     @@ remote-testsvn.c: int cmd_main(int argc, const char **argv)
       		return 1;
       	}
       
     -+	remote_ref = git_default_branch_name(0);
     -+	if (!skip_prefix(remote_ref, "refs/heads/", &default_branch))
     ++	remote_ref = git_main_branch_name(MAIN_BRANCH_FULL_NAME |
     ++					  MAIN_BRANCH_FOR_INIT);
     ++	if (!skip_prefix(remote_ref, "refs/heads/", &remote_ref_short))
      +		BUG("unexpected remote_ref '%s'", remote_ref);
      +
       	remote = remote_get(argv[1]);
     @@ remote-testsvn.c: int cmd_main(int argc, const char **argv)
       
      -	strbuf_addf(&private_ref_sb, "refs/svn/%s/master", remote->name);
      +	strbuf_addf(&private_ref_sb, "refs/svn/%s/%s",
     -+		    remote->name, default_branch);
     ++		    remote->name, remote_ref_short);
       	private_ref = private_ref_sb.buf;
       
       	strbuf_addf(&notes_ref_sb, "refs/notes/%s/revs", remote->name);
     +
     + ## t/t9020-remote-svn.sh ##
     +@@ t/t9020-remote-svn.sh: test_expect_success REMOTE_SVN 'incremental imports must lead to the same head'
     + 	test_cmp master.good .git/refs/remotes/svnsim/master
     + '
     + 
     ++test_expect_success REMOTE_SVN 'respects configured default main branch' '
     ++	git -c init.defaultBranch=trunk remote add -f trunk \
     ++		"testsvn::file://$TEST_DIRECTORY/t9154/svn.dump" &&
     ++	git rev-parse --verify refs/remotes/trunk/trunk
     ++'
     ++
     + test_debug 'git branch -a'
     + 
     + test_done

9: f680e66dd6d < -: ----------- Document how the default branch name can be overridden

gitgitgadget

From: Junio C Hamano <[email protected]>

In a fast-export stream with --anonymize option, all the end-user data including refnames are munged to prevent exposure, but the 'master' branch is left intact.

There is a comment that explains why it is OK to leave 'master' unanonymized (because everybody calls the primary branch 'master' and it is no secret), but that does not justify why it is bad to anonymize 'master' and make it indistinguishable from other branches. Assuming there _is_ a need to allow the readers of the output to tell where the tip of the primary branch is, let's keep the special casing of 'master', but still anonymize it to "ref0". Because all other branches will be given ref+N where N is a positive integer, this will keep the primary branch identifiable in the output stream, without exposing what the name of the primary branch is in the repository the export stream was taken from.

This is in preparation for introducing a mechanism to affect the name of the primary branch used in the repository. Once the mechanism is in use, the name of the primary branch won't be 'master', and may not be allowed to be exposed.

---
 builtin/fast-export.c            | 9 +++++----
 t/t9351-fast-export-anonymize.sh | 9 +++++----
 2 files changed, 10 insertions(+), 8 deletions(-)

index 85868162eec..1072bbf041f 100644
@@ -497,7 +497,7 @@ static void *anonymize_ref_component(const void *old, size_t *len)
 {
 	static int counter;
 	struct strbuf out = STRBUF_INIT;
-	strbuf_addf(&out, "ref%d", counter++);
+	strbuf_addf(&out, "ref%d", ++counter);
 	return strbuf_detach(&out, len);
 }
 

@@ -518,11 +518,12 @@ static const char *anonymize_refname(const char *refname)
 	int i;
 
 	/*
-	 * We also leave "master" as a special case, since it does not reveal
-	 * anything interesting.
+	 * In certain circumstances, it might be interesting to be able to
+	 * identify the main branch. For that reason, let's force its name to
+	 * be anonymized to `ref0`.
 	 */
 	if (!strcmp(refname, "refs/heads/master"))
-		return refname;
+		return "refs/heads/ref0";
 
 	strbuf_reset(&anon);
 	for (i = 0; i < ARRAY_SIZE(prefixes); i++) {

index 897dc509075..2415f0ec213 100755
@@ -26,8 +26,9 @@ test_expect_success 'stream omits path names' '
 	! grep xyzzy stream
 '
 
-test_expect_success 'stream allows master as refname' '
-	grep master stream
+test_expect_success 'stream translates master to ref0' '
+	grep refs/heads/ref0 stream &&
+	! grep master stream
 '
 
 test_expect_success 'stream omits other refnames' '

@@ -57,7 +58,7 @@ test_expect_success 'import stream to new repository' '
 test_expect_success 'result has two branches' '
 	git for-each-ref --format="%(refname)" refs/heads >branches &&
 	test_line_count = 2 branches &&
-	other_branch=$(grep -v refs/heads/master branches)
+	other_branch=$(grep -v refs/heads/ref0 branches)
 '
 
 test_expect_success 'repo has original shape and timestamps' '

@@ -65,7 +66,7 @@ test_expect_success 'repo has original shape and timestamps' '
 		git log --format="%m %ct" --left-right --boundary "$@"
 	} &&
 	(cd .. && shape master...other) >expect &&
-	shape master...$other_branch >actual &&
+	shape ref0...$other_branch >actual &&
 	test_cmp expect actual
 '
 

gitgitgadget

I think this is fine. The reason I left "master" as-is in the original is that it is potentially helpful to have an idea of its specialness when reproducing a traversal in the anonymized. I.e., if you know that a bug is shown by "git rev-list master~17..master~3", then you can reproduce it with the same command in the anonymized repo. Losing any idea of where the primary branch is would make that impossible. But with this patch, you can swap it out for "ref0~17", etc, which is OK.

Of course that only helps you for _one_ branch. A more generally useful mechanism would be to teach fast-export to write the ref mapping (and perhaps file mappings, etc) to a separate file. Then you could convert any reproduction recipe to use the anonymized names, and share only that recipe along with the anonymized dump. But that's _way_ outside the scope of your series. This seems like a good interim step to retain the status quo.

-Peff

Actually, dropping this special case, and dropping the other special case with fmt-merge-msg, we can do without the notion of the "primary" branch.

We still need to have the default name, when user does not specify one, given to the first branch "git init" creates and "git clone" that cannot figure out what the HEAD at the origin points at uses, but one less thing to worry about is always better ;-)

That leaves us in the interim with a "fast-export --anonymize" that is a little harder to use (you have no way to know which branch was which).

But I don't mind at all implementing the map-dumping feature to help move this along. As long as both make it into the same release, then fast-export only gets better, and never regresses. :)

-Peff

Why does fast-export special case on "master" rather than on HEAD? Isn't it more relevant to know the active branch than what _might_ have been the initial branch? It kind of feels like a bug to me that HEAD isn't the special case construct.

(Speaking as someone whose company a number of years ago had most their big repos and lots of little repos switch their main branch to be named "develop", and in some of those repos deleted "master" but didn't in others. If I had needed some steps to reproduce a problem, and hadn't been on the inside, any special casing from fast-export would make more sense to me to apply to "develop" than to "master".)

I am torn on that one. Surely HEAD is often the branch that has our current attention. It may well be what we are exporting and we may want to see the topology formed by other refs relative to it.

On the other hand, the current branch may not necessarily be what we are exporting. Historically a project has a single branch that is the focus of most users' attention when they talk about the general state of the project's progress, so it is understandable to expect that the topology may want to be seen relative to that one central line of development.

Yes, absolutely. You either check "develop" out temporarily just to take anonymized export to make "develop" discoverable in the output, or you would have set core.primaryBranch to "develop" once sometime in the past to tell Git that "develop" is that special one, not "master", so you can take such an export from any branch. As the anonymized export is primarily/solely a debugging aid, convenience would not be of much value, but the latter feels more convenient to me.

Hi Junio,

I'm trying to understand here, but I feel like I'm missing something. Let me try to explain what I understand and hopefully you can figure out what I'm not seeing...

Regardless of what is mainline and whether or not it is important, users probably trigger their bug when a certain branch is checked out. Their bug may also trigger on other branches, but it at least triggers on one, and some bugs will only trigger on one branch. It seems logical to me that we would want to have the same branch checked out (it's the one most likely to trigger the same issue), and thus identifying the HEAD branch is generally important. (Mainline may be too, I'm merely asserting that HEAD is important at this point.)

If users trigger their bug by providing various revision specifications on the command line that compare multiple branches or something, then we're already in the situation of needing to know how to map more than one reference to anonymized ones in order to be able to replicate their issue. However, knowing the mainline might not even help in this case; we instead need to know the anonymized form of the references they are using, whatever those are, and mainline is only useful if it happens to be one of them.

So, I think HEAD is always useful. Additional references would sometimes be useful, but it's not clear to me that mainline is one of those additional references. Maybe I'm just being dense, and I apologize if so, but under what circumstances does knowing the mainline help with debugging a user issue where an anonymized fast-export is provided?

That makes sense; if the bug triggers while they are on develop then I'd expect them to be on develop when they export. If it triggers on some other branch, I'd expect them to stay on that other branch when they export even if "develop" is the mainline.

This doesn't make sense to me. The person who changed the primary branch to "develop" for some repository did so years ago. That individual might not even still be at the company, and even if they are, may well be working on a totally different project (and repository) today. Perhaps that individual set core.primaryBranch at the time, but git-config settings aren't copied by fetch/clone/push, so I don't see how this one helps at all. We could tell all future developers who clone any of these repositories that they also need to set core.primaryBranch when they clone the repo, but that seems super lame to me especially since the odds that any one of them will ever need or benefit from it are approximately 0. And yet, it'll be one of these developers who joined the project long after the switchover who runs into problems and provides fast-export dumps.

It feels like I'm probably just missing something obvious, but I really don't see how the mainline is special here. Please do point out what I'm missing.

Thanks,
Elijah

I don't really remember my exact thought at the time, but it was probably along the lines of: "master" is special not because it's inherently special, but because revealing it doesn't compromise the anonymity, since it's not a user-selected name.

That's not true of other names we might see in HEAD. But if we're turning it into "ref0" or some other special name anyway, then we haven't revealed anything.

That said, I still lean towards just being able to dump the whole mapping by request. That solves this problem and many more.

-Peff

From: Johannes Schindelin <[email protected]>

There is a growing number of projects and companies desiring to change the main branch name of their repositories (see e.g.
https://twitter.com/mislav/status/1270388510684598272 for background on this).

However, there are a couple of hard-coded spots in Git's source code that make this endeavor harder than necessary. For example, when formatting the commit message for merge commits, Git appends "into <branch-name>" unless the current branch is the master branch.

Clearly, this is not what one wants when already having gone through all the steps to manually rename the main branch (and taking care of all the fall-out such as re-targeting existing Pull Requests).

Let's introduce a way to override Git's hard-coded default:
core.mainBranch.

We will start supporting this config option in the git fmt-merge-msg command and successively adjust all other places where the main branch name is hard-coded.

---
 Documentation/config/core.txt |  5 +++++
 fmt-merge-msg.c               |  6 ++++--
 refs.c                        | 27 +++++++++++++++++++++++++++
 refs.h                        |  7 +++++++
 t/t6200-fmt-merge-msg.sh      |  7 +++++++
 5 files changed, 50 insertions(+), 2 deletions(-)

index 74619a9c03b..32bb5368ebb 100644
@@ -626,3 +626,8 @@ core.abbrev::
 	in your repository, which hopefully is enough for
 	abbreviated object names to stay unique for some time.
 	The minimum length is 4.
+
+core.mainBranch::
+	The name of the main (or: primary) branch in the current repository.
+	For historical reasons, `master` is used as the fall-back for this
+	setting.

index 72d32bd73b1..43f4f829242 100644
@@ -407,7 +407,7 @@ static void fmt_merge_msg_title(struct strbuf *out,
 				const char *current_branch)
 {
 	int i = 0;
-	char *sep = "";
+	char *sep = "", *main_branch;
 
 	strbuf_addstr(out, "Merge ");
 	for (i = 0; i < srcs.nr; i++) {

@@ -451,10 +451,12 @@ static void fmt_merge_msg_title(struct strbuf *out,
 			strbuf_addf(out, " of %s", srcs.items[i].string);
 	}
 
-	if (!strcmp("master", current_branch))
+	main_branch = git_main_branch_name();
+	if (!strcmp(main_branch, current_branch))
 		strbuf_addch(out, '\n');
 	else
 		strbuf_addf(out, " into %s\n", current_branch);
+	free(main_branch);
 }
 
 static void fmt_tag_signature(struct strbuf *tagbuf,

index 224ff66c7bb..f1854cffa2f 100644
@@ -560,6 +560,33 @@ void expand_ref_prefix(struct argv_array *prefixes, const char *prefix)
 		argv_array_pushf(prefixes, *p, len, prefix);
 }
 
+char *repo_main_branch_name(struct repository *r)
+{
+	const char *config_key = "core.mainbranch";
+	const char *config_display_key = "core.mainBranch";
+	const char *fall_back = "master";
+	char *name = NULL, *ret;
+
+	if (repo_config_get_string(r, config_key, &name) < 0)
+		die(_("could not retrieve `%s`"), config_display_key);
+
+	ret = name ? name : xstrdup(fall_back);
+
+	if (check_refname_format(ret, REFNAME_ALLOW_ONELEVEL))
+		die(_("invalid branch name: %s = %s"),
+		    config_display_key, name);
+
+	if (name != ret)
+		free(name);
+
+	return ret;
+}
+
+char *git_main_branch_name(void)
+{
+	return repo_main_branch_name(the_repository);
+}
+
 /*
  * *string and *len will only be substituted, and *string returned (for
  * later free()ing) if the string passed in is a magic short-hand form

index a92d2c74c83..a207ef01348 100644
@@ -154,6 +154,13 @@ int repo_dwim_log(struct repository *r, const char *str, int len, struct object_
 int dwim_ref(const char *str, int len, struct object_id *oid, char **ref);
 int dwim_log(const char *str, int len, struct object_id *oid, char **ref);
 
+/*
+ * Retrieves the name of the main (or: primary) branch of the given
+ * repository.
+ */
+char *git_main_branch_name(void);
+char *repo_main_branch_name(struct repository *r);
+
 /*
  * A ref_transaction represents a collection of reference updates that
  * should succeed or fail together.

index e4c2a6eca43..7a873f4a05c 100755
@@ -158,6 +158,13 @@ test_expect_success 'setup FETCH_HEAD' '
 	git fetch . left
 '
 
+test_expect_success 'with overridden default branch name' '
+	test_when_finished "git switch master" &&
+	git switch -c default &&
+	git -c core.mainBranch=default fmt-merge-msg <.git/FETCH_HEAD >actual &&
+	! grep "into default" actual
+'
+
 test_expect_success 'merge.log=3 limits shortlog length' '
 	cat >expected <<-EOF &&
 	Merge branch ${apos}left${apos}

gitgitgadget

Hi dscho

I think this is a good way of phrasing the rationale for the change

This didn't quite scan for me maybe s/already having/one has already/ ?