This error occurs when you try to push a local branch that has no tracking relationship with a remote branch. Git doesn't know where to push your changes because no upstream branch has been configured. The fix is to either set the upstream with the -u flag or configure Git to do it automatically.
When you create a new branch locally and try to push it with just `git push`, Git doesn't know which remote branch to push to. Unlike branches created by `git checkout -b` from a remote-tracking branch (which inherits the tracking relationship), a purely local branch has no "upstream" configured. An **upstream branch** (also called a tracking branch) is a remote branch that your local branch is linked to. This linkage enables: 1. `git push` and `git pull` to work without specifying the remote and branch name 2. Git to show you how many commits you are ahead/behind the remote 3. `git status` to display tracking information Git intentionally requires explicit action to create remote branches because pushing to a remote is a "major action" that could affect collaborators. The designers wanted to prevent accidental remote branch creation from a simple `git push`. This error commonly appears when: - You've created a new feature branch and are pushing it for the first time - You've cloned a repo and created a local branch without setting up tracking - Your Git `push.default` is set to `simple` (the default since Git 2.0), which requires explicit upstream configuration
The simplest fix is to push while setting the upstream at the same time:
git push -u origin <branch-name>Or using the long form:
git push --set-upstream origin <branch-name>The -u (or --set-upstream) flag tells Git to:
1. Push the branch to the remote
2. Set up the tracking relationship
From this point forward, you can use just git push and git pull without arguments.
Tip: Use HEAD to avoid typing the branch name:
git push -u origin HEADThis pushes the current branch to a branch of the same name on the remote.
If the remote branch already exists (perhaps created by someone else), you can set the tracking relationship without pushing:
git branch --set-upstream-to=origin/<branch-name>Or the shorter form:
git branch -u origin/<branch-name>This is useful when:
- The remote branch exists but your local branch isn't tracking it
- You want to change which remote branch your local branch tracks
If you want Git to automatically set up tracking whenever you push a new branch, configure push.autoSetupRemote (available in Git 2.37+):
git config --global push.autoSetupRemote trueWith this setting, running git push on a branch with no upstream will automatically create the remote branch and set up tracking.
Alternative: Set push.default to current:
git config --global push.default currentThis makes git push push to a branch of the same name on the remote, but note it doesn't set up tracking like push.autoSetupRemote does.
After setting the upstream, verify it's configured correctly:
git branch -vvThis shows all local branches with their upstream branch in brackets:
* feature abc1234 [origin/feature] Your commit message
main def5678 [origin/main] Another commitYou can also check with:
git statusWhich should now show:
On branch feature
Your branch is up to date with 'origin/feature'.### Understanding push.default Settings
Git's push.default configuration controls what happens when you run git push without arguments:
| Value | Behavior |
|-------|----------|
| simple | Push current branch to upstream branch with same name (default since Git 2.0) |
| current | Push current branch to branch of same name on remote |
| upstream | Push current branch to its upstream branch |
| matching | Push all matching branches (old default, before Git 2.0) |
| nothing | Don't push anything without explicit refspec |
The simple setting is safest for most workflows as it prevents accidentally pushing to the wrong branch.
### Working with Multiple Remotes
If you have multiple remotes (e.g., origin and upstream), you must specify which remote to push to:
git push -u upstream featureTo see all configured remotes:
git remote -v### Git Aliases for Convenience
Add these aliases to avoid typing the full command:
git config --global alias.pushup 'push -u origin HEAD'
git config --global alias.pu '!git push -u origin $(git branch --show-current)'Then use:
git pushup
# or
git pu### Why Git Requires Explicit Upstream
The Git maintainers designed this behavior intentionally. Creating a branch on a shared remote is a significant action that:
1. Affects all collaborators who fetch from that remote
2. Could conflict with branches others are creating
3. Should be a deliberate decision, not an accident
This "friction" helps teams maintain clean remote repositories.
warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server