How to set Git Upstream For a Respository and a Branch

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.

1. You would fork the actual project repository.
2. Then you clone from the forked repository.
3. Meanwhile, to keep up with the main open-source repository, you pull the changes from it through your git upstream config.
4. You push your changes to a branch in the forked repository.
5. 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.

vagrant@dcubelab:~/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 --set-upstream-to command.

Important Note: In git version update, 1.8.0 the --set-upstream the command is changed to --set-upstream-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 -u is the shorthand for --set-upstream-to

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 foo.

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

If you want to clone or checkout a specific commit id, checkout my blog on git checkout specific commit id.