Make git push set the upstream automatically

Run git config --global push.autoSetupRemote true once, then a plain git push will create and track a matching remote branch.

Published

2025-01-03

Reading time

2 min read

Series

Dotfiles

• #git
• #dotfiles
• #tools

Run this once:

git config --global push.autoSetupRemote true

After that, the first plain git push on a new branch creates a matching branch on the default remote and records it as the upstream. This setting suits Git’s simple, upstream, and current push modes. Leave it disabled if you regularly need to choose among several plausible remotes.

Early in January 2025, I added this setting to my dotfiles. It removed a small interruption that I had accepted for far too long.

Whenever I created a local branch and pushed it for the first time, Git used to stop and tell me that the branch had no upstream. It also printed the command I was expected to run:

git push --set-upstream origin my-branch

The message was helpful once, but the repetition was not. Nearly every time, I wanted exactly what Git suggested: publish this branch to my normal remote under the same name, then track it.

Git could have gone one step further by suggesting the configuration that changes the default behavior, rather than only printing the immediate command.

With push.autoSetupRemote enabled, the first plain git push does that setup automatically. Later pushes work as before. This is not an alias wrapping Git and it does not invent a new workflow. It tells Git that, when no upstream exists, my usual intent is obvious enough to act on.

Convention over configuration, configuration over repetition

I am careful about convenience settings that hide meaningful state. Remotes matter. Tracking relationships matter. A push can publish work. I still want to know which repository I am changing.

But typing --set-upstream origin was not making me reconsider any of those things. In repositories with one conventional remote, it was ceremony after the decision had already been made.

That distinction is useful beyond Git. Automate repeated mechanics, not unresolved choices. If I regularly worked with several equally plausible push remotes, I would leave this setting off. Git stopping would then protect a real decision.

In my normal repositories, there is one clear remote and matching branch names are intentional. Working with multiple remotes is the exception for me.