What does git do, when I push a local branch that does not exist on remote server?

Pushing a New Local Branch to a Remote Git Repository

Understand what happens when you push a local Git branch that doesn't exist on the remote server, and how Git handles this common scenario.

When working with Git, it's common to create new branches locally for developing features or fixing bugs. Eventually, you'll want to share this work with your team or back it up to a remote server. But what exactly happens when you execute a git push command for a branch that only exists on your local machine and not yet on the remote repository?

The Default Behavior: Creating a Remote Branch

By default, when you push a local branch that has no corresponding remote branch, Git will create a new branch on the remote repository with the same name as your local branch. It then pushes your local branch's commits to this newly created remote branch. This is a very convenient feature that streamlines the workflow for sharing new development lines.

git branch new-feature
git checkout new-feature
# ... make some commits ...
git push origin new-feature

Creating a new local branch and pushing it to the remote

flowchart TD
    A[Local Repository] --> B{git push origin new-feature}
    B --> C{Remote Repository: Does 'new-feature' exist?}
    C -- No --> D[Create 'new-feature' on Remote]
    D --> E[Push Commits to Remote 'new-feature']
    C -- Yes --> F[Push Commits to Existing Remote 'new-feature']

Flowchart of pushing a new local branch to remote

Setting Upstream Tracking

After the first successful push of a new branch, Git often automatically sets up a 'tracking relationship' between your local branch and the new remote branch. This means that subsequent git pull and git push commands for that local branch will automatically know which remote branch to interact with, without you having to specify origin new-feature every time.

git push -u origin new-feature
# Or, if you've already pushed once:
git branch --set-upstream-to=origin/new-feature new-feature

Explicitly setting an upstream tracking branch

Configuring Push Behavior

Git's behavior for git push can be configured using the push.default setting. While the default behavior (creating a new remote branch) is usually what you want, understanding these settings can be helpful for specific workflows:

• simple: (Default in Git 2.0+) Pushes the current branch to its upstream branch. If no upstream is set, it fails. If the upstream branch has a different name, it fails. This is generally the safest option.
• matching: Pushes all branches that exist on both the local and remote repositories. This can be dangerous as it might push branches you didn't intend to.
• current: Pushes the current branch to a remote branch of the same name. This is similar to simple but doesn't require an upstream to be set and will create the remote branch if it doesn't exist.
• upstream: Pushes the current branch to its upstream branch. Fails if no upstream is set.
• nothing: Disables git push without arguments.

git config --global push.default current
# Now, 'git push' from 'new-feature' will push to 'origin/new-feature' and create it if it doesn't exist.

Changing the global push.default configuration