Git Upstream and Downstream

A lot of times, we will be working on a project and collaborating with other developers. In these situations, we have a central remote repository from where we cloned our local copy and, we also have our own local repository where we work on features and push them to the remote repository. In this case, the remote repository is called the Upstream and our local repository is known as the Downstream. Let's learn more about the concept of Upstream and Downstream in Git.

Upstream and Downstream

• In Git, any repository that we clone from, or pull from, or push to, is called the Upstream. Our local repository is known as the Downstream.
• Both of these are relative, which means that there is no central upstream or downstream. It all depends on what the other repository is trying to do.
• We can also think of upstream and downstream as the flow of data. Existing data will flow downstream from one repository to another and new changes will flow upstream to the repository from where the data was initially fetched.
• In most cases, the upstream is a central remote repository, and all the local repositories of developers collaborating on that project are downstream.

Upstream Branches

An upstream branch is a remote branch that is tracked by a local tracking branch. The remote branch is called the upstream of the local branch. All the changes of this remote branch can be pulled by the local branch and, the local branch can push changes to the upstream. Let's first try to understand what remote-tracking branches and tracking branches are.

• A Remote-Tracking branch is a branch that tracks changes to a remote branch. These remote-tracking branches are created by Git when we clone a repository and they play an important role when fetching or pulling 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.

Consider the following scenario where we have a remote repository with a master branch having three commits. If we clone this remote repository to our local system, then it will create a remote-tracking branch called origin/master that tracks the remote master branch. A local branch called master is also created that has the remote master branch as its upstream.

Advantages of Setting Upstreams

There are two major advantages of setting upstream branches for our local branches.

1. Upstream branches make it very easy to push and pull changes. We can directly use the Git Push and Git Pull commands without specifying the remote or the remote branch name. This may not seem like a great advantage but proves to be very helpful when working on a lot of different branches.
2. Upstream branches also help us to easily compare our local branch with the remote branch. We can use the Git Status command to see whether our local branch is leading ahead or lagging behind the remote branch.

Consider the above example where we had a remote repository with three commits and a cloned local repository. Our local master branch had the remote master branch as its upstream. Let's say that we add a new empty commit to the local branch. We can directly push this change to the remote branch by using the Git Push command.

Now, let's suppose that some other developer added two new commits to the remote branch. We can check this difference in commits by first using the Git Fetch command and then using the Git Status. We can see in the output below that our local branch is lagging behind the remote branch by two commits.

Check out our How to set Upstream Branch on Git? if you wish to understand how to make upstream for local branches.

Summary

Upstream and downstream are relative terms that can be used to describe the flow of data between two repositories. A repository that pulls or clones from another repository is called downstream to the other repository. The repository to which we push changes is called the upstream. Upstream repositories are usually central remote repositories to which all the collaborators contribute. We must be careful while making any changes to the upstream repository as an incorrect change can affect all the downstream repositories that pull from this upstream.