In this blog, you will learn everything about setting up an upstream for a git repository, a branch and the
--set-upstream-to command usage
You will also learn about different scenarios where git upstream is used and how to apply it in your git development workflow.
Have you wondered how to keep the forked repo in sync with the main repo? It’s done by adding the main repo as the upstream. It is explained in the below sections.
What is Upstream in Git?
Note: We are following the name “main” instead of “master” considering the removal of terms like “master” and “slave” in the IT community.
Like the literal meaning, upstream refers to something which points to where it originated from.
In the git world, upstream refers to the original repo or a branch. For example, when you clone from Github, the remote Github repo is upstream for the cloned local copy.
Let’s take a look at different types of git upstreams.
Git Repository Upstream
Whenever you clone a git repository, you get a local copy in your system. So, for your local copy, the actual repository is upstream.
Git Forked repository Upstream
When you clone a Forked repository to your local, the forked repository is considered as the remote origin, and the repository you forked from is upstream.
This workflow is common in open-source development and even in normal project developments.
For example, If you wanted to contribute to an open-source project, this is what you do.
- You would fork the actual project repository.
- Then you clone from the forked repository.
- Meanwhile, to keep up with the main open-source repository, you pull the changes from it through your git upstream config.
- You push your changes to a branch in the forked repository.
- Then you would raise a PR to the actual project repository from your forked repository.
Tip: With Jenkins multibranch pipelines, you can easily set up the hooks for pull requests from a Forked branch.
Setup Git Upstream For a Repository
Let’s say you are working on a forked project and you want to sync changes from the main project repo.
You can add the actual repo as an upstream to your local copy. This way you can pull all the changes happening in the main project repo.
Add an Upstream Repo
Before adding upstream, you can take a look at your
.git/config file and you will see something like below with a remote origin. Which is a clone of the forked repo.
Now lets the add the upstream to our repo with the main project repo URL using the
add upstream command.
git remote add upstream https://github.com/devopscube/vagrant-examples.git
Now if you check the .
git/config, you will see an upstream entry as shown below.
You can also check out the remote origin and upstream branches using the following command.
git branch --remotes
Here is a sample output.
[email protected]:~/vagrant-examples$ git branch --remotes origin/HEAD -> origin/main origin/dev origin/main upstream/dev upstream/main
Sync Changes From The Upstream repo
To sync an upstream repo, first, you need to fetch the upstream changes.
git fetch upstream
Then, merge the changes from the upstream branch to the local branch. In this example, it’s the main upstream branch.
git merge upstream/main
Setup Git Upstream For a Branch
But when we talk about an upstream branch, it refers to the specific upstream of a branch in the remote respository.
For example, let’s say you clone a git repository with two branches, main and dev.
When you clone the repository both the branches, main, and dev will have the respective upstream branches (remote branches) because these branches are present in both the local copy as well the remote or upstream repository. Also, the tracking is enabled by default.
Now let’s look at scenarios where you want to set up git upstream using
Important Note: In git version update, 1.8.0 the
--set-upstreamthe command is changed to
Add Git Upstream Using –set-upstream-to
When you create a branch (named foo) in your local repository and want to add an upstream branch for tracking, you can use the following command.
git push -u origin foo
Important Note: Here
-uis the shorthand for
When you push a local branch with the upstream command, it automatically creates the remote branch and adds tracking to your local branch.
Add Git Upstream To Existing Remote Branch
Sometimes, when you create a local branch, you might push the remote repository changes without adding the upstream tag. For example,
git push origin foo
It will create the remote branch without tracking. Meaning, when someone pushes any change to the branch foo in the remote branch, and when you try to pull the changes, it will throw the following error.
There is no tracking information for the current branch. Please specify which branch you want to merge with. See git-pull(1) for details git pull <remote> <branch> If you wish to set tracking information for this branch you can do so with: git branch --set-upstream-to=origin/<branch> testing
To avoid this, you can set git upstream using the following command. It will enable tracking, and you will be able to pull the changes.
git branch --set-upstream-to origin/foo
Add Git Upstream Using Git HEAD
In git, HEAD refers to the currently active branch.
For example, if you have checked out
foo branch, your HEAD now is
So when you create a new local branch named foo, you can create the upstream using the HEAD as shown below.
git push -u origin HEAD
Git set-upstream FAQ’s
What is the need to set upstream in git?
By setting upstream in git, the local branches can track the remote branches. This makes pulling changes from the remote repository very easy.
How to keep the original and forked repo in sync?
By setting the original repo as upstream on your local copy, you can fetch the original repo changes and push them to the forked repo to keep it in sync.
What is an upstream branch in Git?
When you clone a git repository, the parent or remote repository branches are called the upstream branches for the local branches.
How to check the git upstream branches?
You can check all the upstream branches using the git branch -vv command. It will show all the upstream tracking mapped to the local branches.
If you want to clone or checkout a specific commit id, checkout my blog on git checkout specific commit id.
Thank you for the detailed explanation. I’m able to understand perfectly.