Git Set Upstream Branch: A Comprehensive Guide


When working with Git, it is crucial to understand how upstream branches function and how to set them up. This article provides a detailed overview of setting up a Git upstream branch, changing it, and acquiring an overview of the branch tracking in Git.


To follow along with this guide, you will need:

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

What is a Git Upstream Branch?

Imagine a river analogy to visualize the flow of data. When you send something upstream, you are sending it back to the original authors of the repository. In Git, the concept of an upstream branch refers to sending your data back to where the river stream originates.

With Git’s “set upstream” functionality, you can determine 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 methods to set an upstream branch in Git:

  1. Using git push: This is the fastest method if you only need to set a single upstream branch.
  2. Using a short alias command: This method is suitable if you frequently change the flow of your current branch.

Method 1: Set Upstream Branch Using git push

Setting up an upstream branch using git push is the most straightforward approach in Git.

  1. Create a new branch and provide it with a name. For example, let’s name ours “test.” Switch to it using the checkout command with the -b option:
    git checkout -b <branch name>

    A confirmation message will appear, confirming the successful branch switch.

  2. Set the upstream branch using the git push command with the -u extension or its longer version, -set-upstream. Replace <branch name> with the name of your branch:
    git push -u origin <branch name>

    Alternatively, you can use:

    git push -set-upstream origin <branch name>

    You will receive confirmation that your branch has been set up to track a remote branch.

Method 2: Set Upstream Branch Using Alias

If you find yourself repeatedly executing the same commands when creating a new branch, it is advisable to set up a short alias command. This can be achieved by modifying your existing Git commands or creating a bash command.

  1. Configure a global alias command using git config and the -global flag:
    git config -global alias.<alias name> "push -u origin HEAD"

    Alternatively, create a bash alias command using alias:

    alias <alias name> ='git push -u origin HEAD'
  2. Execute your global alias by typing:
    git <alias name>

    Or, run your bash alias by entering its name:

    <alias name>

How to Change Upstream Branch in Git

To track a different upstream branch than the one you previously set up, use the following command:

git branch -u <remote/branch name>

For instance, if you want to change the upstream branch to the main branch of the remote repository, you would run:

git branch -u origin/main

A confirmation message will be displayed in the terminal, acknowledging the successful change.

How to Check Which Git Branches Are Tracking Which Upstream Branch

To obtain a comprehensive list of all your branches and their tracked branches, execute git branch with the -vv option:

git branch -vv

This command will display the tracking branches for each branch. For example, the main branch will have a tracking branch of [origin/main], while the test branch will have a tracking branch of [origin/global]. If a branch has no tracking branches, it means there is no upstream branch associated with it.


Congratulations! You now possess a firm understanding of upstream branches in Git. You have learned how they function, how to set them up, and how to change them. Feel free to experiment and familiarize yourself with upstream branches. Additionally, remember that you can effortlessly delete both remote and local Git branches and remove a Git remote from a repository.