Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Configuration Options

init.defaultBranch setting

Reference for init.defaultBranch: choose the branch name git init creates, override it with --initial-branch, and rename an existing branch to match.

When git init creates a repository, it points HEAD at an unborn branch, a name that exists only as a pointer until the first commit. init.defaultBranch is that name. Without it, Git 2.56 still uses master for compatibility and prints a hint recommending that you choose one.

Most teams now set the value to main, matching the default of the big hosting services. The setting affects only new repositories made with git init (and the first commit of git clone of an empty remote); it never renames branches that already exist.

Terminal
git config --global init.defaultBranch main
git init -b trunk project            # one-off: --initial-branch
git branch -m master main            # rename in an existing repository

Try it

Bash Three ways to name the first branch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Renaming an existing branch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git config [--global] init.defaultBranch <name>
git init [-b <name> | --initial-branch=<name>] [<directory>]
Name Description
init.defaultBranch Branch name used by git init when no -b is given. Must be a valid branch name.
-b, --initial-branch Per-command override; beats the configuration.

Errors: an invalid name (spaces, .., a trailing .lock) makes git init fail with "invalid initial branch name".

Usage notes

  • Set it once, globally on every machine, so that local repositories match what the remote calls the branch.
  • git clone ignores it for existing remotes: the clone checks out whatever branch the remote's HEAD points to. For an empty remote it uses your setting.
  • Server side: a bare repository created on a server with git init --bare follows the server's own configuration, not yours. A mismatch is why a first push of main sometimes arrives while the server HEAD still names master.
  • Renaming a shared branch also needs the remote and every clone updated: push the new name, change the hosting service's default branch, then git push origin --delete master. People then run git branch -u origin/main main (and git remote set-head origin -a).
  • Tooling that hard-codes master (old CI scripts, deploy hooks) breaks silently when new repositories use another name; search for it before renaming.
  • Templates: init.templateDir is a separate setting that copies hooks and info files into new repositories.
  • git init on an existing repository is safe: it re-reads templates and does not change HEAD.
  • The GIT_CONFIG_COUNT environment trick (used by this site's runner) can supply the setting without a config file.