What Is Git Upstream and How to Set an Upstream Branch

Introduction

Upstream branches specify the remote branch where your local changes are pushed and from which updates are pulled. Understanding how upstream branches work and how to set them up is essential when collaborating on projects and managing remote repositories.

Learn how to set, change, and track Git upstream branches.

Prerequisites

• Git installed (see how to install Git on Windows, macOS, or Ubuntu).
• A cloned Git repository or a local Git project.

What Is a Git Upstream Branch? 

In Git, when you push changes upstream from a local branch, you send updates to the central repository or a branch maintained by the project's original authors.

The --set-upstream or -u option in the git push command links your local branch to a specific branch on the remote repository and sets it as the default remote branch for push and pull operations.

The specific remote branch your local branch tracks is the upstream branch.

How to Set Upstream Branch in Git

You can set an upstream branch in Git using one of the two methods: the git push command or by configuring a Git alias.

Method 1: Set Upstream Branch Using Git Push

Using git push is the fastest way to set a single upstream branch:

1. Create a new branch and switch to it using the checkout command with the -b option:

git checkout -b [branch_name]

In this example, the branch name is test.

From this point on, test is the current active branch.

2. Set the upstream branch using the git push command with the -u extension:

git push -u origin [branch_name]

Replace branch_name with your local branch name.

In this example, the test branch is configured to track the origin upstream branch.

Users who prefer more explicit, self-descriptive commands can use the longer --set-upstream command version:

git push --set-upstream origin [branch_name]

The result of this command is identical to using git push -u.

Method 2: Set Upstream Branch Using Alias

To simplify the process of setting upstream branches, you can create a custom alias:

1. Use the git config command to create a global alias:

git config --global alias.[alias_name] "push -u origin HEAD"

Replace alias_name with your desired alias.

2. Run the global alias by typing:

git [alias_name]

How to View the Upstream of a Branch

Enter the following command to view the upstream branch associated with the local branch:

git rev-parse --abbrev-ref --symbolic-full-name @{u}

The output displays the name of the remote branch your local branch is tracking.

The @{u} option refers to the upstream branch of the current branch, while --abbrev-ref converts the full path, for example, refs/remotes/origin/global, into the short name origin/global.

How to Change Upstream Branch in Git

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

git branch [branch_name] -u [remote_name]

For example:

git branch test -u origin/global

The output confirms the local test branch is tracking the origin/global upstream branch.

How to Fetch from Git Upstream

Use the git fetch command to retrieve updates from an upstream branch:

git fetch [remote_name]

This retrieves changes from the specified remote repository without merging them into the local branch. For example, to fetch changes from the origin remote, enter:

git fetch origin

The terminal displays a summary of the fetched updates, such as new branches or commits.

How to Push to Git Upstream

To push local branch changes to the upstream branch, use the following command:

git push

The command pushes changes to the branch your local branch is tracking (upstream branch). To specify the remote and branch explicitly, use the following syntax:

git push origin [branch_name]

For example, to push the test branch to the origin remote, enter:

git push origin test

How to Check Which Git Branches Are Tracking Which Upstream Branch

Enter the following command to check all upstream branch associations for your repository:

git branch -vv

This displays a list of local branches, their upstream branches, and their synchronization status.

In this example, 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 no upstream branch.

Conclusion

This guide showed you what upstream branches are, how they work, and how to set them in Git.

Next, learn how to delete a git branch remotely and locally and remove a git remote from a repository, so feel free to experiment and get comfortable with upstream branches.