How can I create a Git repository with the default branch name other than "master"?

In the Pro Git book, it says

“origin” is not special

Just like the branch name “master” does not have any special meaning in Git, neither does “origin”. While “master” is the default name for a starting branch when you run git init which is the only reason it’s widely used, “origin” is the default name for a remote when you run git clone. If you run git clone -o booyah instead, then you will have booyah/master as your default remote branch.

That means, we can use our default branch name as main or main-branch or something like that. I didn't see any option in man git-init which will initialize my repo with a different default branch name.

GitHub shows how to set the default branch name in its settings page. But I am not talking about how to set it on any specific Git hosting site. I am strictly asking in terms of Git only, not in regards to any specific Git hosting site.

Is there a way to do that?

Newer Git, New Repo

Since git version 2.28.0 the git init command now takes a --initial-branch (or -b for short) parameter. These two commands create a new Git repo with a branch named "trunk", which always made more sense to me than "master" (master of what?):

git init --initial-branch=trunk
git init -b trunk

This is configurable with the init.defaultBranch setting. If I want all new repos to have "trunk" as the default branch:

git config --global init.defaultBranch trunk

Older Git, New Repo

Some systems still have older Git installations. My Debian 10 server (Buster, the current stable version as of October 2020) comes with Git 2.20, which does not support the -b option. One option is to create the repository and then change the branch name. This technique works for normal (non-bare) repos:

git init
git checkout -b trunk

This creates a new repository with trunk as the current branch instead of master. The branch master does not actually exist--the branches don't get created until they have at least one commit. Until the branch gets created, the branch only exists in .git/HEAD, which explains why the master branch will disappear when you switch to trunk.

Bare Repos

For bare repos, you cannot run git checkout (that's what it means to be bare). Instead, you can change HEAD to point at a different branch:

git init --bare
git symbolic-ref HEAD refs/heads/trunk

Old Repos

If you've already committed, you can run git branch -m instead:

git init
touch file.txt
git add file.txt
git commit -m 'commit 1'
git branch -m trunk

This renames the branch from master to trunk once it's created.

This does seem a bit clunky since the mechanism is different depending on whether the repository is empty, but it works. You can also approach it as "creating a new branch and deleting master".

You can, indirectly, configure git init to use a different default branch: the current branch is defined by HEAD, which is “just” a textfile telling Git which ref is the current one.

Using init.templateDir, you can ask git init to use a different one:

# ~/.config/git/config or ~/.gitconfig
[init]
    templateDir = ~/.config/git/template/

and in ~/.config/git/template/HEAD, put a single line (+ linebreak): ref: refs/heads/main (to default to branch main).

The whole contents of templateDir are copied to the .git directory when creating a repository; the default (here /usr/share/git-core/templates) contains some sample hooks and other files, but you can use your new template directory to setup default hooks, for example.

$ tree /usr/share/git-core/templates
/usr/share/git-core/templates
├── branches
├── description
├── hooks
│   ├── applypatch-msg.sample
│   ├── commit-msg.sample
│   ├── fsmonitor-watchman.sample
│   ├── post-update.sample
│   ├── pre-applypatch.sample
│   ├── pre-commit.sample
│   ├── prepare-commit-msg.sample
│   ├── pre-push.sample
│   ├── pre-rebase.sample
│   ├── pre-receive.sample
│   └── update.sample
└── info
    └── exclude

3 directories, 13 files

How can I create a Git repository with the default branch name other than "master"?

You would use Git 2.28 (Q3 2020): the name of the primary branch in existing repositories, and the default name used for the first branch in newly created repositories, is made configurable, so that we can eventually wean ourselves off of the hardcoded 'master'.

And reminder from Aug. 2020 from GitHub:

On October 1, 2020, if you haven't changed the default branch for new repositories for your user, organization, or enterprise, it will automatically change from master to main.
You can opt out of this change at any time:

• For users, on the https://github.com/settings/repositories page
• For organization owners, on the https://github.com/organizations/YOUR-ORGANIZATION/settings/repository-defaults page
• For enterprise administrators, on the https://github.com/enterprises/YOUR-ENTERPRISE/settings/member_privileges page

This change is one of many changes GitHub is making to support projects and maintainers that want to rename their default branch.
To learn more about the changes we're making, see github/renaming.

But back to Git itself: (2.28, Q3 2020) See commit 508fd8e (29 Jun 2020) by Đoàn Trần Công Danh (sgn).
See commit 0068f21, commit a471214, commit 0cc1b47, commit 32ba12d, commit 6069ecc, commit f0a96e8, commit 4d04658 (24 Jun 2020), and commit 489947c (23 Jun 2020) by Johannes Schindelin (dscho).
See commit 8747ebb (24 Jun 2020) by Don Goodman-Wilson (DEGoodmanWilson).
^{(Merged by Junio C Hamano -- gitster -- in commit 11cbda2, 06 Jul 2020)}

init: allow specifying the initial branch name for the new repository

^{Signed-off-by: Johannes Schindelin}

There is a growing number of projects and companies desiring to change the main branch name of their repositories (see e.g. Mislav Marohnić's tweet for background on this).

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 a new option: --initial-branch=<branch-name>.

git init --initial-branch=hello myLocalRepo
# or
git config --global init.defaultBranch hello
git init myLocalRepo

And:

init: allow setting the default for the initial branch name via the config

^{Helped-by: Johannes Schindelin
Helped-by: Derrick Stolee
Signed-off-by: Don Goodman-Wilson}

We just introduced the command-line option --initial-branch=<branch-name> to allow initializing a new repository with a different initial branch than the hard-coded one.

To allow users to override the initial branch name more permanently (i.e. without having to specify the name manually for each and every git init invocation), let's introduce the init.defaultBranch config setting.

Note: commit 489947c, about the merge commit message, has since been reverted in Git 2.29, see "how can I customize git's merge commit message?".
The init.defaultBranch setting remains.

This impacts submodules:

submodule: fall back to remote's HEAD for missing remote..branch

^{Helped-by: Philippe Blain
Signed-off-by: Johannes Schindelin}

When remote.<name>.branch is not configured, git submodule update currently falls back to using the branch name master.
A much better idea, however, is to use the remote HEAD: on all Git servers running reasonably recent Git versions, the symref HEAD points to the main branch.

Note: t7419 demonstrates that there might be use cases out there that expect git submodule update --remote to update submodules to the remote master branch even if the remote HEAD points to another branch.
Arguably, this patch makes the behavior more intuitive, but there is a slight possibility that this might cause regressions in obscure setups.

Even so, it should be okay to fix this behavior without anything like a longer transition period:

• The git submodule update --remote command is not really common.
• Current Git's behavior when running this command is outright confusing, unless the remote repository's current branch is master (in which case the proposed behavior matches the old behavior).
• If a user encounters a regression due to the changed behavior, the fix is actually trivial: setting submodule.<name>.branch to master will reinstate the old behavior.

Note that, with Git 2.29 (Q4 2020), tests in contrib/ are adjusted to the recent change to fmt-merge-msg.

See commit b87528c (03 Aug 2020) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano -- gitster -- in commit 83b8250, 10 Aug 2020)}

Revert "contrib: subtree: adjust test to change in fmt-merge-msg"

^{Signed-off-by: Emily Shaffer}

This reverts commit 508fd8e8baf3e18ee40b2cf0b8899188a8506d07.

In 6e6029a8 (fmt-merge-msg: allow merge destination to be omitted again) we get back the behavior where merges against 'master', by default, do not include "into 'master'" at the end of the merge message. This test fix is no longer needed.

Also:

With Git 2.29 (Q4 2020), update the tests to drop word 'master' from them.

See commit f33f2d3, commit b6211b8 (26 Sep 2020), and commit 432f5e6, commit 5a0c32b, commit 659288c (21 Sep 2020) by Johannes Schindelin (dscho).
^{(Merged by Junio C Hamano -- gitster -- in commit 58138d3, 05 Oct 2020)}

tests: avoid variations of the master branch name

^{Signed-off-by: Johannes Schindelin}

The term master has a loaded history that serves as a constant reminder of racial injustice. The Git project has no desire to perpetuate this and already started avoiding it.

The test suite uses variations of this name for branches other than the default one. Apart from t3200, where we just addressed this in the previous commit, those instances can be renamed in an automated manner because they do not require any changes outside of the test script, so let's do that.

Seeing as the touched branches have very little (if anything) to do with the default branch, we choose to use a completely separate naming scheme: topic_<number> (it cannot be topic-<number> because t5515 uses the test_oid machinery with the term, and that machinery uses shell variables internally, whose names cannot contain dashes).

This trick was performed by this (GNU) sed invocation:

$ sed -i 's/master\([a-z0-9]\)/topic_\1/g' t/t*.sh

And, still with Git 2.29:

See commit 538228e, commit a15ad5d (08 Oct 2020) by Johannes Schindelin (dscho).
^{(Merged by Junio C Hamano -- gitster -- in commit 62564ba, 08 Oct 2020)}

t1415: avoid using main as ref name

^{Signed-off-by: Johannes Schindelin}

In preparation for a patch series that will change the fall-back for init.defaultBranch to main, let's not use main as ref name in this test script.

Otherwise, the git for-each-ref ... | grep main^(man) which wants to catch those refs would also unexpectedly catch refs/heads/main.

Since the refs in question are worktree-local ones (i.e. each worktree has their own, just like HEAD), and since the test case already uses a secondary worktree called "second", let's use the name "first" for those refs instead.

While at it, adjust the test titles that talk about a "repo" when they meant a "worktree" instead.