Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Configuration Options

branch.* settings

Reference for branch.* settings: branch.<name>.remote, merge, rebase, pushRemote and description, plus branch.autoSetupMerge and autoSetupRebase.

The branch.* settings describe how each branch relates to a remote. A branch becomes a "tracking" branch when branch.<name>.remote and branch.<name>.merge are set; those two keys tell git pull, git push and git status what the branch's upstream is. Git writes them for you when you use git push -u, git branch -u or git switch on a remote branch.

Two global switches, branch.autoSetupMerge and branch.autoSetupRebase, decide what Git does automatically when it creates a new branch.

Terminal
git config branch.main.remote origin
git config branch.main.merge refs/heads/main
git config branch.main.rebase true
git config branch.autoSetupRebase always

Try it

Bash What push -u writes

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 autoSetupMerge and autoSetupRebase

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 branch.<name>.remote <remote>
git config branch.<name>.merge <ref>
git config branch.<name>.rebase (true | false | merges | interactive)
git config branch.<name>.pushRemote <remote>
git config branch.<name>.description <text>
git config branch.autoSetupMerge (true | false | always | inherit | simple)
git config branch.autoSetupRebase (never | local | remote | always)
git config branch.sort <for-each-ref-key>
Name Description
branch.<name>.remote Remote that <name> pulls from and pushes to. The value . means "this repository".
branch.<name>.merge Full ref on that remote (refs/heads/main) that <name> follows. Together with remote, this is the upstream.
branch.<name>.rebase Overrides pull.rebase for this branch.
branch.<name>.pushRemote Remote used by git push (not pull) for this branch; overrides remote.pushDefault.
branch.<name>.description Free text shown in git format-patch cover letters and git request-pull; edit it with git branch --edit-description.
branch.autoSetupMerge Whether a new branch starts tracking its start point. Default true (only when the start point is a remote-tracking branch). always also tracks local branches, inherit copies the start branch's upstream, simple tracks only when the names match, false never tracks.
branch.autoSetupRebase Whether new tracking branches also get rebase = true. never (default), local, remote or always.
branch.sort Default sort key for git branch listings, for example -committerdate.

Errors and edge cases: a branch name containing dots or slashes is written as a subsection, so feature/x.y becomes [branch "feature/x.y"]; the key is case-sensitive for the branch name and case-insensitive for the variable name.

Usage notes

  • You rarely type these by hand. git push -u origin <branch>, git branch -u origin/<branch> and git switch <name> (when it creates a branch from a unique remote branch) write remote and merge for you; git branch --unset-upstream removes them.
  • merge holds a ref on the remote, not a local name. It reads refs/heads/main even though you work with origin/main locally.
  • pushRemote is how fork workflows work: pull from upstream, push to origin. Set remote.pushDefault once if every branch should do this.
  • autoSetupRebase only affects branches created afterwards. Existing branches keep their settings; it also never overrides an explicit branch.<name>.rebase.
  • branch.<name>.rebase beats pull.rebase. If one branch behaves differently from the rest, look here first. See pull.rebase.
  • description is local. It is never pushed; it only matters for tools that generate patch series and pull requests.
  • Renaming a branch moves its section. git branch -m old new renames [branch "old"] to [branch "new"] automatically; deleting the branch removes it.
  • Check what is set with git branch -vv or git config --get-regexp '^branch\.'.