What Is Git Upstream And How To Set Upstream Branch

January 18, 2021

Introduction

When you clone a Git repository or create new features through branches, you need know how upstream branches work and how to set them up.

This article gives an overview of how to set up a Git upstream branch, how to change it and how to have an overview of which Git branch is tracking which upstream branch.

What Is Git Upstream and How to Use It

Prerequisites

  • Git installed and configured
  • A cloned Git repository or your own Git project set up locally

What is a Git Upstream Branch? 

Using a river analogy to illustrate the flow of data, upstream is sending your data back to where the river stream is coming from. When you send something upstream, you are sending it back to the original authors of the repository.

With git set upstream, you can choose where your current local branch will flow. It allows you to change the default remote branch.

How to Set Upstream Branch in Git

There are two ways to set an upstream branch in Git:

  • Using git push, which is the fastest method if you need to set a single upstream branch.
  • Using a short alias command. This method makes sense if you often change the flow of your current branch.

Method 1: Set Upstream Branch Using Git Push

Using git push to set an upstream branch is the most straightforward way to set upstream branches in Git.

Note: Forgot how to clone a repository? Freshen up your memory with our Git Commands Cheat Sheet.

1. Create a new branch and give it a name. We named ours test. Switch to it using the checkout command with the -b option:

git checkout -b <branch name>

switch branch confirmation appears:

Switched branch confirmation message using git checkout

Note: From this point on, the active branch is listed as (<branch name>) instead of (main). In our case, it’s (test).

2. Set upstream branch using the git push command with the -u extension or use the longer version --set-upstream. Replace <branch name> with your branch name.

git push -u origin <branch name>

Alternatively:

git push --set-upstream origin <branch name>

You get confirmation that your branch has been set up to track a remote branch:

git push -u command and confirmation message that a branch is tracking a remote branch

The test branch now has a set upstream branch.

Method 2: Set Upstream Branch Using Alias

Instead of going through these commands every time you create a new branch, set up a short alias command. You can modify your existing Git commands or create a bash command.

1. Configure the global alias command through git config with the --global command:

git config --global alias.<alias name> "push -u origin HEAD"

Or create a bash alias command using alias:

alias <alias name> ='git push -u origin HEAD'

Note: Pushing to HEAD will push to a remote branch with the same name as your current branch.

2. Run your global alias by typing:

git <alias name>

Or your bash alias by typing its name:

<alias name>

How to Change Upstream Branch in Git

Track a different upstream branch than the one you just set up by running:

git branch  -u <remote/branch name>

For example:

git branch  -u <origin/global>

The terminal prints out a confirmation message:

git branch -u command and confirmation of tracking change

How to Check Which Git Branches Are Tracking Which Upstream Branch

List all your branches and branch tracking by running git branch with the -vv option:

git branch -vv
Listing all branches using the git branch -vv command

The main branch has a tracking branch of [origin/main]. The test branch has a tracking branch of [origin/global]. The global branch has no tracking branches, and therefore no upstream branch.

Note: The current active branch is denoted by the asterisk (*) sign.

Conclusion

You should now know what upstream branches are, how they work, and most importantly, how to set an upstream branch in Git.

Feel free to experiment and get comfortable with upstream. You can easily delete a git branch remotely and locally and remove a git remote from a repository.

Was this article helpful?
YesNo
Milica Dancuk
Milica Dancuk is a technical writer at phoenixNAP with a passion for programming. With a background in Electrical Engineering and Computing, coupled with her teaching experience, she excels at simplifying complex technical concepts in her writing.
Next you should read
How to Remove a Git Remote From Repository
November 17, 2020

When a remote repository moves to another host or a team member stops working on a project, the related git...
Read more
How to Delete a Git Branch Remotely and Locally
October 13, 2020

This article provides a quick overview of basic commands and processes necessary for deleting both local and...
Read more
Git Commands Cheat Sheet
March 10, 2020

Git, the popular version control system, has a plethora of commands for managing your project history. This...
Read more
How To Switch Branch on Git
September 20, 2023

Developers need to switch between branches frequently. Git branches allow you to work on your code, fix bugs...
Read more