How to Push a New Local Branch to Remote Git Repository and Track It

When you create a new branch locally in Git, it exists only on your local machine until you push it to a remote repository. Additionally, you'll want to set up tracking so that a plain git push and git pull know where to go. This tutorial covers the complete process of pushing a new local branch to a remote repository and establishing proper tracking relationships.
Prerequisites
Before following this tutorial, you should have:
- Git installed on your system
- A local Git repository connected to a remote repository
- Basic understanding of Git branches and remote repositories
- Permissions to push to the remote repository
Understanding Branch Tracking
When you create a local branch, Git doesn't automatically know which remote branch it should sync with. Setting up tracking (also called upstream) creates a relationship between your local branch and a remote branch, enabling:
- Simple
git pushandgit pullcommands without specifying remote and branch names - Status information about how many commits you're ahead or behind
- Automatic completion in many Git tools
Method 1: Push and Set Upstream in One Command
The most efficient way to push a new branch and set up tracking simultaneously:
Using the --set-upstream Flag
git push --set-upstream origin <branch-name>
Or using the shorter -u flag:
git push -u origin <branch-name>
Example:
git checkout -b feature/user-authentication
git push -u origin feature/user-authentication
This command:
- Creates the branch on the remote repository
- Pushes all commits from your local branch
- Sets up tracking between local and remote branches
Verification
After pushing, verify the tracking relationship:
git branch -vv
Output should show something like:
* feature/user-authentication 3a7b9f2 [origin/feature/user-authentication] Add user login functionality
main 8c4d1e9 [origin/main] Initial commit
Method 2: Push First, Set Tracking Later
If you've already pushed a branch without setting up tracking, you can establish the relationship afterward.
Initial Push Without Tracking
git push origin <branch-name>
Set Upstream Branch
git branch --set-upstream-to=origin/<branch-name>
Or use the shorter form:
git branch -u origin/<branch-name>
Example:
git push origin feature/payment-integration
git branch -u origin/feature/payment-integration
Method 3: Push Current Branch
If you're already on the branch you want to push:
git push -u origin HEAD
The HEAD refers to your current branch, so Git automatically uses the current branch name. This is useful when you have long or complex branch names.
How Do I Create a Remote Branch?
Push a local branch with -u. The push creates the branch on the remote and sets it as the upstream of your local branch:
git switch -c feature/payments
git push -u origin feature/payments
To create a remote branch without a local one, push a commit to a new name:
git push origin HEAD:feature/payments # from the current commit
git push origin 3a7b9f2:refs/heads/hotfix # from a commit hash: write the full ref name
git push origin 'v1.0.0^{commit}:refs/heads/release-1.0' # from the commit of a tag
From a hash, Git cannot guess whether you mean a branch or a tag, so 3a7b9f2:hotfix fails with The destination you provided is not a full refname. From an annotated tag, add ^{commit}. Without it, Git tries to put the tag object itself on a branch, and the server rejects it with trying to write non-commit object.
If you can create branches in the web interface of GitHub, GitLab or Bitbucket, a branch made there appears locally after git fetch. Check out a remote branch shows how to start working on it.
Push without -u every time
Git 2.37 and later can create the upstream on the first git push of a new branch:
git config --global push.autoSetupRemote true
git switch -c feature/x
git push
# * [new branch] feature/x -> feature/x
# branch 'feature/x' set up to track 'origin/feature/x'.
Without the setting, the first plain git push stops and prints the git push --set-upstream origin feature/x command to run.
How Do I Fix "src refspec master does not match any"?
Git has no local branch or commit with the name you pushed. Push a branch that exists:
git branch --show-current # the name of your branch, for example main
git push -u origin main # push that name
git push -u origin HEAD # or: push the current branch, whatever its name
The error has three common causes:
No commits yet. After
git init, the branch exists only after the first commit.git logconfirms it:fatal: your current branch 'main' does not have any commits yetMake the first commit:
git add .andgit commit -m "Initial commit". Then push.The branch is
main, and you pushedmaster(or the other way round). New repositories on GitHub and GitLab usemain, and so does Git wheninit.defaultBranchismain. Git 3.0 plans to makemainthe default for new repositories (what changes in Git 3.0). Push the name thatgit branch --show-currentprints.A typo in the branch name, for example
git push origin maste.
If the remote expects master and you want your branch to have that name, rename it: git branch -m main master, then git push -u origin master.
A missing remote gives a different error, fatal: 'origin' does not appear to be a git repository. Add it with git remote add origin <url>. If the push is rejected because the remote already has a commit, for example a README, see refusing to merge unrelated histories.
How Do I Rename a Git Branch?
Rename the current branch with git branch -m <new-name>, or any branch with git branch -m <old> <new>:
git branch -m featur-login feature-login
The commits, the reflog and the branch settings move to the new name. The upstream does not change: in a test, the renamed branch still tracked origin/featur-login. So if you pushed the branch before, push the new name, set it as the upstream, and delete the old remote branch:
git push -u origin feature-login # the new name, now the upstream
git push origin --delete featur-login # the old name
On GitHub, deleting the old branch closes the open pull requests that use it as their head branch, and you must open them again from the new branch.
Rename a shared or default branch
For a branch that other people use, such as master to main, rename it in the web interface of the hosting service. GitHub then moves branch protection rules, changes the base branch of open pull requests, and redirects web URLs that contain the old name. It does not update GitHub Actions workflows that name the old branch. Each collaborator then runs the commands that GitHub's documentation lists:
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a
On macOS and Windows, a rename that changes only the case (Feature to feature) can fail, because the file system does not see a difference. git branch -M forces it.
How Do I Delete a Git Branch Locally and Remotely?
Delete the local branch with git branch -d, and the remote branch with git push origin --delete:
git switch main # you cannot delete the branch you are on
git branch -d feature/login # local
git push origin --delete feature/login # remote
-d refuses to delete a branch whose commits are not merged:
error: The branch 'feature/login' is not fully merged.
If you are sure you want to delete it, run 'git branch -D feature/login'.
-d checks the branch against its upstream, or against the current branch if it has no upstream. So a branch whose upstream has all its commits counts as merged, even if it never reached main. A branch that you pushed without -u and never merged counts as "not fully merged". Use -D only when you are sure. Git prints the last commit of the deleted branch, so you can undo the delete:
git branch -D feature/login
# Deleted branch feature/login (was 0f1ce33).
git branch feature/login 0f1ce33 # undo, if you need it again
Clean up after branches are merged
When a pull request is merged and the remote branch is deleted, your clone still has the remote-tracking branch until you prune:
git fetch --prune # or set it once: git config --global fetch.prune true
git branch -vv # local branches whose upstream is gone show ": gone]"
To delete every local branch whose upstream is gone:
git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads |
awk '$2 == "[gone]" {print $1}' | xargs -r git branch -d
Read the list first: drop the xargs part to see it. A gone upstream does not prove that the work was merged, so the command uses -d, which refuses branches with commits that are not merged. If your team squash-merges pull requests, -d refuses most of them, because the squash commit is a new commit. Check each refused branch, for example with git log --oneline origin/main..<branch> and the state of its pull request, before you delete it with -D. git branch --merged main lists the branches that are merged into main.
When the delete fails
error: Cannot delete branch 'x' checked out at '/path': the branch is open in another worktree. Switch that worktree to another branch, or remove it withgit worktree remove /path.- The remote refuses: GitHub does not let you delete the default branch, and branch protection rules can block a delete. Change the default branch or the rule first.
error: unable to delete 'x': remote ref does not exist: someone already deleted it. Rungit fetch --prune.
A deleted remote branch is gone from the server, but every clone that fetched it still has the commits. Push it again from such a clone with git push origin <hash>:refs/heads/<name>.
Working with Different Remote Names
If your remote repository isn't named "origin", adjust the commands accordingly:
git push -u upstream feature/new-feature
git push -u github main
List All Remotes
To see all configured remotes:
git remote -v
Handling Common Scenarios
Scenario 1: Creating and Pushing Feature Branch
# Create and switch to new branch
git checkout -b feature/shopping-cart
# Make your changes and commit
git add .
git commit -m "Implement shopping cart functionality"
# Push and set tracking
git push -u origin feature/shopping-cart
Scenario 2: Push Branch with Different Remote Name
git checkout -b hotfix/critical-bug
git commit -m "Fix critical security vulnerability"
git push -u production hotfix/critical-bug
Scenario 3: Push to Multiple Remotes
# Push to origin and set tracking
git push -u origin feature/api-integration
# Also push to backup remote
git push backup feature/api-integration
Verifying Branch Relationships
Check Branch Tracking Status
git status
With tracking set up, you'll see messages like:
On branch feature/user-authentication
Your branch is up to date with 'origin/feature/user-authentication'.
View All Branch Information
git branch -vv
This shows:
- Branch names
- Latest commit hashes
- Commit messages
- Tracking relationships
Check Remote Branches
git branch -r
This lists all remote branches that your local Git knows about.
Managing Branch Relationships
Change Upstream Branch
To change which remote branch your local branch tracks:
git branch -u origin/different-branch
Remove Tracking Relationship
git branch --unset-upstream
Push to Different Branch Name
To push your local branch to a remote branch with a different name:
git push -u origin local-branch:remote-branch
Example:
git push -u origin feature/login:feature/user-authentication
Advanced Push Options
Replace a Branch You Pushed Before
A new branch never needs a force push. If you rewrote a branch that you pushed before, for example after a rebase, replace it with a lease:
git push --force-with-lease origin feature/branch
Push All Branches
To push every local branch, also the ones that are not on the remote yet:
git push --all origin
Use it with care: it also publishes old experiments and backup branches. To push only the current branch by default, keep push.default at its default value, simple.
Push Tags Along with Branch
git push -u origin feature/new-feature --tags
Troubleshooting Common Issues
Error: "The current branch has no upstream branch"
This means tracking isn't set up. Use:
git push -u origin <branch-name>
Error: "failed to push some refs"
The remote repository might have changes you don't have locally:
git fetch origin
git pull origin <branch-name>
git push -u origin <branch-name>
Error: "Permission denied"
Check your authentication and permissions:
git remote get-url origin
git config user.name
git config user.email
Branch Already Exists on Remote
If the branch exists on the remote, someone else may have created it, or pushed to it. Fetch and look before you decide:
git fetch origin
git log --oneline <branch-name>..origin/<branch-name> # commits on the remote that you do not have
If those commits belong to someone else, pick another branch name, or put your commits on top of theirs with git rebase origin/<branch-name> and push again. Only if you are sure the remote branch is yours and can go, replace it with git push --force-with-lease -u origin <branch-name>. A plain --force overwrites commits that you have not even seen.
Best Practices
Naming Conventions
Use clear, descriptive branch names:
git checkout -b feature/user-profile-editing
git checkout -b bugfix/login-validation-error
git checkout -b hotfix/security-patch-2024-12
Regular Synchronization
After setting up tracking, regularly sync with remote:
git fetch origin
git pull
Clean Up Local Tracking
Remove tracking for deleted remote branches:
git remote prune origin
Verify Before Force Operations
Always check what you're about to push:
git log origin/<branch-name>..<branch-name>
git diff origin/<branch-name>
Working in Teams
Communicate Branch Creation
When working in teams, inform colleagues about new branches:
git push -u origin feature/team-collaboration
# Send notification to team about new branch
Pull Request Workflow
After pushing your branch:
- Create a pull request on your Git hosting platform
- Share the branch name with reviewers
- Keep the branch updated with main branch changes
Branch Protection
For important branches, consider setting up protection rules on your Git hosting platform to prevent accidental force pushes.
Summary Commands
Here's a quick reference for the most common operations:
# Create branch, make changes, and push with tracking
git checkout -b feature/new-feature
git add .
git commit -m "Add new feature"
git push -u origin feature/new-feature
# Set tracking for existing branch
git branch -u origin/feature/existing-branch
# Check tracking status
git branch -vv
# Push current branch with tracking
git push -u origin HEAD
By following these methods, you can efficiently push new local branches to remote repositories and establish proper tracking relationships, making your Git workflow smoother and more collaborative.
Related Resources
- Introduction to Git: Push, Fetch, Pull and Tracking Branches
- Introduction to Git: List, Rename and Delete Branches
- Fetch a remote branch and check it out
- Make an existing branch track a remote branch
- Git concepts simulator
- Git branching strategies interview question
- Test yourself: Git Command Quiz and the Git workflow exercise
Try it hands-on
Run the commands from this article in the browser. Nothing to install.
Git Concepts Simulator
Practice Git in an interactive browser terminal with a visual repository model. Learn the working directory, staging area, local commits, branch pointers, remotes, fast-forward merges, fetch, and rebase.
Git Merge Conflict Simulator
Resolve Git merge conflicts in a browser lab. Read the conflict markers and the three index stages, edit the file to what it should be, take a side with --ours or --theirs, see why they swap during a rebase, back out with git merge --abort, and catch a clean merge that breaks the build.
We earn commissions when you shop through the links below.
Bitrise
Managed runners for GitHub Actions
Bitrise Build Hub runs your GitHub Actions jobs on M4 Macs and AMD Linux machines. Change runs-on and keep your workflows, secrets and logs on GitHub.
Atomsized
AWS platform engineering and GitOps
Design and automation for reliable AWS and Kubernetes platforms, safer delivery workflows, and preview and UAT environments your engineers can understand and own.
DigitalOcean
Cloud infrastructure for developers
Simple, reliable cloud computing designed for developers
DevDojo
Developer community & tools
Join a community of developers sharing knowledge and tools
SMTPfast
Developer-first email API
Send transactional and marketing email through a clean REST API. Detailed logs, webhooks, and embeddable signup forms in one dashboard.
QuizAPI
Developer-first quiz platform
Build, generate, and embed quizzes with a powerful REST API. AI-powered question generation and live multiplayer.
Want to support DevOps Daily and reach thousands of developers?
Become a SponsorTags
Found an issue?
Related Posts
Also worth your time on this topic
How to Get the Current Branch Name in Git
Need to programmatically get the current Git branch name? Learn multiple methods to retrieve the branch name for scripts, CI/CD pipelines, and shell prompts.
Git Workflow and Collaboration Fundamentals
Master essential Git workflows, branching strategies, and collaboration techniques used in modern development teams.
50 minutes
Git Staging and Committing
Explain the Git staging area. What is the difference between git add, git commit, and git push?
junior