Git Upstream and Downstream

Git Upstream and Downstream

Upstream and downstream in Git are usually defined with the context of a repository. In general terms, upstream refers to the location through which we clone the repository. The term downstream is defined as the process of integrating our work with other works. These two methods are not just restricted to Git repositories, but they also play a crucial role in the project.

Let’s discuss this in detail.

As the name suggests, upstream and downstream define the flowing nature of the activities we carry while working on a project. It means that these are remote activities having time and history constraints. Concerning the subject cited above, if a remote repository is upstream or downstream, the downstream repository is pulled from the upstream repository. This gives us an idea that the data flow is downstream by default.

There is an ambiguity that upstream is defined in time while downstream is defined in history and vice-versa. One better way to understand this is by using parent/child terms to get time and history. Let us understand these terms by implementing them.

The above diagram defines the workflow of both this stream and how they work. The picture is just for reference. It will be clear once we get our hands dirty by executing commands necessary for upstream and downstream.

Note: Upstream is always local while downstream is remote.

Upstream

As we know that upstream and downstream constitute local and remote nature. The upstream is channeled through a remote server. For this, we need to set upstream and check if the remote server is present to carry out or not. The commands below can be helpful.

If we type -set upstream, it throws an error like

error: failed to push some refs to 'https :< remote repository Address>

Since we have not defined the remote server, we need to check it the through the following commands.

$ git remove -v

This command will show the origin of the remote repository on GitHub. This shows the remote server name.

$ git branch -a

This command gives the branch list with the repository. Now you need to push the changes you have made in the repository to the remote server and make it default and to do this, type the following command.

$ git push --set-upstream origin master

This command will set the master branch to default remote branch. The console now shows that everything is up to date. Now, we can also set the default remote branch and view them by using the below commands.

$ git branch --set-upstream-to origin master
$ git branch -vv

Downstream

Downstream works in association with upstream. We again need to establish a remote server since the upstream is a locally stored repository while downstream is the default flow of the data.

Type the following commands for establishing server if the errors show something like this.

error: failed to push some refs to 'https :< remote repository Address>

We then need to navigate or map branches and to do that we type the following commands.

 $ git map-branches
 origin/master
   cool_feature
     subfeature
   fixit
     frozen_branch 

After typing this commands, we need to navigate downstream in order to fetch the branches, and to do this we type the following command.

$ git nav-downstream

Previous HEAD position was beec6f4 Make ReflectorImpl use mailboxes

 Switched to branch 'cool_feature'
 Your branch is ahead of 'origin/master' by 4 commits.
   (use "git push" to publish your local commits)
 Please select a downstream branch
   0. cool_feature
   1. fixit
 Selection (0-1)[0]: 0 

We need to map the branches through the following command.

 $ git map-branches
 origin/master
   cool_feature *
     subfeature
   fixit
     frozen_branch 

The final step is to downstream the branch and re-map and check. We do this by typing the following command.

 $ git nav-downstream
 Switched to branch 'subfeature'
 Your branch and 'cool_feature' have diverged,
 and have 2 and 1 different commits each, respectively.
   (use "git pull" to merge the remote branch into yours)
 $ git map-branches
 origin/master
 cool_feature
     subfeature *
   fixit
     frozen_branch 

Let us now discuss what the workflow of downstream states.

Whenever a user makes changes, he/she may want to send the changes back to the upstream so that everyone associated in a team who is working on the repository can pull from the same source and mark reflected changes. This comes with an issue that mostly the same changes can reflect all the members in a single workspace rather than the technical requirement of the source control. Therefore, to submerge these changes into the main project, we downstream them to track the divergent changes in the phase of development.

Also, the package or release managers rectify the changes made by navigating across the submitted changes to the upstream branches thus they send all the changes so that the developers need not adjust the source or keep track of changes. This resolves the issue of sending the changes back to upstream again in the next release.