How to Set Up and Use an Upstream Branch in Git

In this post, I will show you how to set up and use an upstream branch in Git. When it comes to Version Control System, Git is considered to be the leading and most used distributed version control system globally when compared to other version control systems such GitLab, BitBucket, Azure DevOps Repos,  Apache Subversion, PerForce, Beanstalk, AWS CodeCommit and Microsoft Team Foundation Server. A version control system enables users to keep track of changes in software projects and collaborate on them. It allows developers to collaborate on code while also separating their tasks via branches. There can be several branches in a version control system, according to the number of collaborators. Because the code changes remain in a specific branch, the branches retain their copies. When necessary, developers can combine the code changes.  They can also view the history of changes, go back to previous version(s), and use/manage code as  desired. GitHub allows software teams to collaborate while also keeping track of all code changes. You can track code changes, go back in time to undo mistakes, and collaborate with other team members. It serves as a repository for Git projects.

You might like to ask, what is Git? It is an open source version control system that features local branching, multiple workflows, and convenient staging areas. Git version control allows for faster operation. To learn more about Git and GitHub, please review the following related posts: Git command not found: How to fix Git is not recognized as an internal or external command, Git Vulnerability: Git for Windows uninstaller is vulnerable to DLL hijacking when run under the SYSTEM user account, Install Git on Windows: The term “git” was not used as the name of a cmdlet, function, script file, or executable Program recognized, How to Setup HTTPS users using Git credentials and Pushing Code to AWS CodeCommit and Git config –global init.defaultBranch: Error cannot lock ref ‘refs/remotes/origin/windows’, not a directory

GIT Vs GitHub

Many people sometimes misinterpreted Git and GitHub to means the same thing. In actual sense, they mean different things. To put it simply, Git is a version control system that allows you to manage and track the history of your source code. On the other hand, GitHub is a cloud-based hosting service that lets you manage Git repositories. If you have open-source projects that use Git, GitHub is the right hosting platform to manage them with you them.

Understanding an Upstream Branch

Whenever you want to clone a new repository or work with different feature branches, you must first understand how to work with upstream branches and how to set them up. Upstream branches are closely associated with remote branches. Upstream branches define the branch that your local remote branch is tracking on the remote repository – also known as the remote tracking branch.

Setting Up An Upstream Branch

When creating a new branch or working with existing branches, knowing how to set upstream branches on Git can be very helpful.

There are various methods of setting up Upstream branches in Git. They methods are:

Method 1- Using the git push command

The simplest method is to use the "git push" command with the “-u” option for upstream branch. We are going to do this by creating a local folder and initialize it for git using the Git Bash Terminal. To install Git Bash terminal click here.

First, create a folder on your Desktop or any other location within your system preferable to you. Here, I have created one called git-upstream-branch and it’s currently empty.

To be able to use the folder to set up an upstream branch in Git, we need to run the git init command to initialize the empty folder and make it git ready. Open your git bash terminal and navigate to the empty folder created you before and run:

git init

As you can see from the screenshot above, we’re directly on the master branch.

Now add a file. It can be any txt file e.g. file1.txt to the folder. To create a file type:

touch file1.txt

Now, add, commit and push the file to your remote GitHub repository. Review this post to learn how to create your first remote repository on GitHub. I have created my remote repo already as shown in the screenshot below:

Now to set upstream branches, run any of the command below:

$git push -u <remote> <branch> OR $git push --set-upstream <remote> <branch>

Let’s create a branch called upstreamb with the command git branch <branchname> or git checkout -b <branchname>. After creating the branch, run the below command to switch to it:

$git switch <branchname>

Running the git branch command with the -vv flag allows you to inspect tracking branches.

As you can clearly see, the branch upstreamb has no tracking branches compared to master and no upstream branches as well.

Now we can setup the upstream branch using the “git push” command for the new branch "upstreamb".

To so, I created a file called file3.txt added and committed it and then run either of the commands below:

$git push -u <remote> <branch> OR $git push --set-upstream <remote> <branch>

Let’s have a look at the tracking branches again with the branch command, "git branch -vv".

Now you have successfully set the upstream branch for your newly created branch and git is tracking it.

Method 2 – Set upstream branch using an alias

Another option for configuring the upstream branch is to create an alias for your “git push” command. Note, pushing to HEAD is actually the same as pushing to a remote branch with the same name as your current branch. To setup upstream branch using alias, run:

$git config --global alias.pushd "push -u origin HEAD"

When you’re finished adding and committing files to your repository, use your newly defined alias to set the upstream branch using the command below:

git pushd

As you can the upstream branch has been set to "HEAD -> upstreamb"

Method 3 – Set up Upstream Branch using a bash alias

If you don’t want to change your existing git commands, you can use a bash alias. To do this, create a new bash alias with the "alias" command and give it a name, run:

$alias gp='git push -u origin HEAD'

Create a new branch and use our alias to easily push our code and create the upstream branch with the command below:

$git checkout -b <branchname>

Method 4 – Set upstream branch for an existing remote branch

In some cases, you may want to connect your local branches to remote branches that you have just pulled or cloned from the main repository. Assuming you pulled a branch named the "prod" branch from the "origin" remote. As a result, the tracking branch is known as "origin/prod".

Set new local branches as tracking branches

Use the "-track" option to switch to the local "prod” branch and set the "origin/prod" as the tracking branch or upstream branch by typing the command below:

$ git checkout --track origin/prod

Branch 'prod' set up to track remote branch 'prod' from 'origin'.
Switched to a new branch 'prod'

Use the "git branch" command to confirm that you linked 'prod' to the tracking branch "origin/prod" which upstream branch is the remote prod.

$git branch -vv

Set existing local branches as tracking branches

You may, on the other hand, have chosen to work on a local branch while creating the upstream branch (or the remote tracking branch later on). Consider a scenario where you have created a "feature" branch to work with.

Let’s assume you made some commits in your branch and want to make the tracking branch master by running the command below:

$ git branch -u origin/master

You can see from the screenshot the 'feature' branch have set up to track 'origin/master'

Why are upstream branches important in Git?

Setting Upstream branches are important for the following reasons:

1. It allows you to set the default remote branch for your current local branch.
2. Upstream branches are extremely useful for collaboration. They simplify pushing and pulling from remote branches by allowing us to use the Git Push and Git Pull commands without specifying the remote or branch name.
3. Another significant benefit of establishing Upstream Branches is that we can easily compare our local branch to the remote branch. Git displays information such as the number of commits ahead or behind the remote branch and makes it easy for us to merge them together as shown in the images below:

Congratulations! You’ve learnt how to set up and use upstream branches in Git.