How to set Upstream Branch on Git?

Branching is an important feature of Version Control Systems like Git. When using Git we will often have a remote repository to which people push commits and we also have our own local copy on which we are working. Pushing, and pulling between these two repositories is very common. Setting Upstream Branches makes it very easy for us to connect with the remote repositories. Let's try to understand how these work.

Upstream and Downstream

• In Git terminology, any repository that you clone from, pull from, or push to is Upstream to your repository and your local repository is Downstream to that repository.
• Both of these terms are relative, which means there is no central upstream or downstream repository. It's all relative to what the other repository is doing.
• In most cases, the upstream is a remote repository and all local repositories of the developers who are collaborating on that project are downstream.

Upstream Branches

• To understand the upstream branch we first need to learn about Remote-Tracking Branches and Tracking Branches.
• A Remote-Tracking Branch is a branch that tracks changes to a remote repository branch. Whenever we clone a repository a remote-tracking branch is created which helps us to fetch changes from the remote repository.
• A Tracking Branch is a branch that tracks another branch. In most cases, the Tracking Branch tracks the Remote-Tracking Branch.
• Now consider that we have a Remote-Tracking branch that tracks a remote branch. We also have a Tracking Branch that tracks this Remote-Tracking Branch. Then the remote branch is called the Upstream Branch for the Tracking Branch on our local repository.

Consider a scenario where we have a remote repository with three commits. Now if we clone this repository then a remote-tracking branch is created that tracks the remote master branch and another local master branch are created that has the remote master branch as its upstream.

Why are Upstream Branches Needed?

• Upstream branches are very useful for collaborative purposes. They make pushing and pulling from the remote branches very easy as we can directly use the Git Push and Git Pull commands without specifying the remote name or the branch name. This may not seem like a great advantage but proves to be very helpful when working on a lot of different branches.
• Another major advantage of setting Upstream Branches is that we can easily compare our local branch with the remote branch. Git shows information like the number of commits that we are ahead or behind from the remote branch.

Setting Upstream Branch

There are many cases in which we may need to set Upstream Branches. Let's take a look at these scenarios.

When Pushing an existing Local Branch

There may be cases when we have a local branch that we want to push to a remote repository. Setting an Upstream branch for this local branch will also prove to be helpful. We can do this by using the --set-upstream or the -u flag along with the Git Push command. It will not only push and create a new branch in the remote repository but also set it as an Upstream Branch. Before executing the following command make sure that you are on the branch that you want to push and set an Upstream for.

$ git push --set-upstream <remote-name> <branch-name>

When creating a new Local Branch

We can also set Upstream Branch for a new branch that we want to create. In this case, the remote repository already has a branch and we want to create a new local tracking branch that has this remote branch as an Upstream Branch. To do this we have to create a new branch that is based on the remote-tracking branch. We use the Git Checkout command with the --track option for doing this.

$ git checkout --track <remote-tracking-branch>

Setting Upstream for an existing Local Branch

We can set an Upstream Branch for an already existing local branch. In this case, both the remote branch and the local branch exist and we want to set the remote branch as the Upstream for our local branch. This can be done by using the Git Branch command. Make sure you are currently on the local branch that you want to set an Upstream for.

$ git branch -u <remote-name>/<remote-branch-name>

We can check the remote-tracking branches for a tracking branch by using the following Git Branch Command.

$ git branch -vv

In the following output we can see that our local master branch tracks the remote-tracking branch origin/master. This implies that the remote master branch is the upstream branch for our local master branch.

Summary

Upstream Branches are extremely helpful for collaborative purposes. We directly push and pull from the remote branches without worrying about the names of the remotes or the branches. Setting Upstream Branches also helps us in comparing how far ahead or behind our local branch is when compared to the remote branch.

We discussed three different cases in which we may need to set Upstream Branches:

1. When creating a new remote branch by pushing our local branch.
2. When creating a new local branch that should track the remote branch.
3. To set Upstream Branch for an already existing local branch.