January 17, 2024

Resolving git push errors

Git can be tricky, especially when you get errors. It’s important to understand what these error messages mean. In this article, we’ll look at two common Git push errors and explain in simple terms how to fix them.

Error 1: Mismatched Branch Names

fatal: The upstream branch of your current branch does not match
the name of your current branch.  To push to the upstream branch
on the remote, use

    git push origin HEAD:main

To push to the branch of the same name on the remote, use

    git push origin HEAD

To choose either option permanently, see push.default in 'git help config'.

To avoid automatically configuring an upstream branch when its name
won't match the local branch, see option 'simple' of branch.autoSetupMerge
in 'git help config'.

This message appears when you’re trying to push changes to a remote repository, but Git gets confused about where exactly you want your changes to go. This typically happens in two scenarios:

  1. The name of your current local branch doesn’t match any branch on the remote.
  2. You haven’t specified which branch on the remote you want to push to.

The error message suggests a couple of solutions.

  1. Pushing to a different branch on the remote.
git push origin HEAD:main

This command push your current branch to a branch named main on the remote origin.

Here’s a better representation of the command:

git push <remote> <local-branch>:<remote-branch>
  1. Pushing to a branch with the same name:
git push origin HEAD

This command push your current branch to a branch with the same name on the remote.

You can replace HEAD by the name of your branch.

  1. Setting Default behaviour

Furthermore, Git allows you to set a default behaviour for git push. push.default in Git config defines how Git behaves when the branch is not specified while pushing. The possible values are:

  • nothing : Do not push anything without specifying a branch.
  • matching : Push all local branches that have matching branches on the remotes.
  • upstream : Push the current branch to its upstream branch.
  • current : Push only the current branch to a remote branch with the same name.
  • simple: Push the current branch to a branch of the same name, but only if the current branch is set to track a remote branch.

Here’s how to configure git push for all repositories:

git config --global push.default simple

Likewise, The option simple in branch.autoSetupMerge prevents Git from automatically configuring an upstream branch when the branch names don’t match. This means that if you create a local branch with a name that doesn’t exist on the remote, Git won’t automatically set up an upstream tracking relationship for this branch. This behavior is particularly useful for preventing accidental creation of tracking relationships which might lead to confusion or errors.

Error 2: No Upstream branch

fatal: The current branch pizza  has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin pizza

To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.

This error signifies that your current local branch does not have an associated upstream branch on the remote repository, leaving Git uncertain about where to push your changes.

The solution provided in the error message does two things:

  1. Pushes your local branch to the remote repository. It creates a new branch on the remote named pizza and pushes your commits to it.

  2. Sets the newly created remote branch as the upstream for your local branch. This means that future git push and git pull commands from this branch will default to this remote branch.

The upstream for new branches can be automatically set with the option push.autoSetupRemote in Git config.


Understanding and resolving Git push errors are crucial for a smooth development process. The key to mastering Git is in understanding its nuances and leveraging its configuration options to work for you. Happy coding!


Git config

Powered by Hugo & Kiss.