Change git init default branch name

Question

I'm trying to figure out how to make git init use a different default branch name other than master for the first commit, but I can't find a git config for it or anything that'd allow me to do this (e.g. aliases only work for commands, not branch names).

Is there any way to change the default first branch name that git init sets up?

T. Kiley · Answer 1 · 2020-07-28T19:57:58.653

As of Git 2.28 (released 27th July 2020), you can now configure the name of the branch created when you init a new repository:

$ git config --global init.defaultBranch main

After setting this variable, running git init will produce a repository whose initial branch is main:

$ git init
Initialised empty Git repository in /home/thomas/test-git-repo/.git/
$ git status
On branch main
No commits yet
nothing to commit (create/copy files and use "git add" to track)

Release notes: https://lore.kernel.org/git/xmqq5za8hpir.fsf@gitster.c.googlers.com/

score 33 · Answer 2 · edited Apr 22 '21 at 11:20

In Git versions prior to 2.28, HEAD is hardcoded to point to refs/heads/master.

if (create_symref("HEAD", "refs/heads/master", NULL) < 0)

So there is no config setting or option that you can pass to git init to change it to something else.

What is possible though is to change what HEAD points to right after git init with the help of git symbolic-ref:

$ git init
$ git symbolic-ref HEAD refs/heads/test

This will change HEAD to point to a (not yet existing) branch called test. Then when you create your first commit, the branch will be called test instead of master.

score 19 · Accepted Answer · answered Jun 10 '20 at 15:51

A simple way to change the default HEAD is to create a HEAD in the git template dir. First, configure your template dir to ~/Templates/git.git (or whatever you'd prefer):

$ git config --global init.templateDir '~/Templates/git.git'
$ cp -r /usr/share/git-core/templates ~/Templates/git.git

Then, create the file HEAD in the template dir:

$ echo 'ref: refs/heads/default' > ~/Templates/git.git/HEAD

And you're good to go! Whenever you run git init, you'll now get the message:

$ git init
Reinitialized existing Git repository in [...]

For some reason, git decides whether to use this message based on the presence of the HEAD file in .git, rather than relying on whether or not .git had to be created. However, it really doesn't matter what message it shows you. From the git-init man page:

Running git init in an existing repository is safe. It will not overwrite things that are already there. The primary reason for rerunning git init is to pick up newly added templates (or to move the repository to another place if --separate-git-dir is given).

That is to say, git init is guaranteed not to overwrite the HEAD you put in the template, and it won't use the template's HEAD to overwrite an existing HEAD either. Since this is explicitly documented, you can rely on it.

Additionally, it also says:

Files and directories in the template directory whose name do not start with a dot will be copied to the $GIT_DIR after it is created.

Which means you can also rely on the template being copied immediately after the creation of .git, and not at a later point.

(Of course, this is my personal interpretation of the manual. It's entirely possible that the git developers will disagree.)

score 15 · Answer 4 · answered May 03 '21 at 17:59

One way to set your default branch is to edit your ~/.gitconfig file. Add the following lines:

[init]
  defaultBranch = main

Now when you run git init, main will be your default branch. This is similar to running git config --global init.defaultBranch main as mentioned by @t-kiley.

score 3 · Answer 5 · edited Sep 05 '21 at 19:38

As mentioned HEAD is hardcoded to point to master. However, you could create a shell alias, to make git init do what you like. If you are using bash as your shell, put something like this in your .bashrc:

function git_init_fnc () {
  default_branch="main"
  if [[ $1 == "init" ]] && [[ $# -eq 1 ]];then
      git init
      if [[ ! -z $(git branch -a | grep $default_branch) ]]; then
          git checkout "$default_branch"
      else
          git checkout -b "$default_branch"
      fi
  else
      /usr/bin/git "$@"
  fi
}
alias "git"=git_init_fnc

This will replace the command git with a function. This function will make the command git run exactly the same, unless you are calling git init without any other arguments. When you call git init it will init the repository. Next it will check to see if the branch "daddy" already exists. If it does, it will check out that branch, otherwise it will create the branch and move you to it.

Thomas Praxl · Answer 6 · 2021-12-26T05:46:15.663

~~Most of the answers to this thread work for some git versions, but no answer worked for all of the versions I'm working with (git versions 2.7, 2.25 and 2.30).~~

~~But thanks to all of your answers, I was able to mix your shared ideas and I finally found a way to support all versions with one setting:~~

[Edit: Turned out, that my observation was wrong. It didn't work, because of my special setup.
If you have problems with the above solutions, here's another approach (tested for git versions 2.7, 2.25 and 2.30).]

init.defaultBranch combined with a wrapper function (only for git versions, that do not support init.defaultBranch, which is queried once, at the beginning of the session).

The wrapped function issues a git checkout to the configured default branch, directly after an init.

.gitconfig

…
   [init]
    # Usually only works for git >= 2.28.
    # Thus, these dotfiles provide a git wrapper that performs extra
    # action after git init. The git wrapper takes this setting
    # into account, so that it even works for git < 2.28.
    defaultBranch = "main"
…

bash aliases

#!/usr/bin/env bash
main() {
  wrap_git_if_necessary
}
if the current git version does not support a custom
default branch (init.defaultBranch, e.g. main),
then we wrap it in a function that performs
extra action on git init.
wrap_git_if_necessary() {
  if ! supports_default_branch &>/dev/null; then
    alias git=git_wrapper
  fi
}
supports_default_branch() {
  command git help --config | grep "init.defaultBranch"
}
wrap git to make main the default branch on init.
Is required for git versions < 2.28, which do
not support init.defaultBranch natively.
git_wrapper() {
  local defaultBranch
  if command git "$@"; then
    if [[ "$1" == "init" ]]; then
      defaultBranch=$(command git config init.defaultBranch || echo "main")
      command git checkout -b "${defaultBranch}"
    fi
  fi
}
main "$@"

score 1 · Answer 7 · answered Feb 13 '22 at 10:16

I found this question via search. I realize I'm answering an old question, but to others who may get here, GitHub has a page on configuring the primary branch name for any repositories created there, as well as instructions for changing the primary branch name:

Renaming the default branch from master

Change git init default branch name

7 Answers7

if the current git version does not support a custom

default branch (init.defaultBranch, e.g. main),

then we wrap it in a function that performs

extra action on git init.

wrap git to make main the default branch on init.

Is required for git versions < 2.28, which do

not support init.defaultBranch natively.