Tracking branches (aka Upstream Branches) in Git is usually something that slips under our radar when we are using Git in our projects. But it’s really useful and it’s there in plain sight even if we don’t notice it. If you understand how tracking branches work in Git and the benefits it brings to the table, it will help you speed up your activities when using Git. Let’s get in to it.
Tracking branch is a branch that knows which remote branch, a local branch is related to. It basically links a local branch to a remote branch and this provides some benefits. Some branches in git will usually track the remote branch that its it related to in the remote repository. But even if a local branch doesn’t track the remote branch it’s ok, we can make it track the remote branch and do some interesting stuff with it.
What is the benefit of using tracking branches you may ask? Well, the following comes to mind regarding the benefits of tracking branches.
Tracking Branches Allows You to Push or Pull Changes Without Specifying the Remote or The Branch.
Normally when you have a branch locally and you want to push or pull changes to/from the remote repository you would issue a command like the following. Here the branch we are working on is called feature
git pull origin feature
git push origin feature
But when your branch is tracking the remote branch you don’t have to do this. I said that tracking branch knows which remote branch its related to. So, when we are on the feature branch and it has a tracking branch, it knows that when we push or pull it needs to push or pull from the remote branch named feature in the remote repository. So now the command can be just,
Inform You That How Far Behind the Tracking Branch Is Relative to The Local Branch.
If you have a tracking branch for your local branch when you issue a git status command, it will show you how far your tracking branch is behind comparted to your local branch. This can be a reminder for you to push your changes to the remote repository. Look at the screenshot bellow, a git status command is issued and git lets the user know how far ahead your local branch is from the remote branch.
Looking at the benefits, it’s clear that the tracking branches are a great time saver if you use it correctly. Let’s look at how to configure tracking branches for your local branches.
Find Out Which Local Branches Have Tracking Branches.
Before we start adding tracking branches to our local branches, we need to know what branches already have tracking branches and which branches does not. It’s really easy to do this, it’s done by a simple git command.
git branch -vv
Enter this command on a command line in your git project and you will see a list of all branches and the last commit on that branch and if the branch has a tracking branch or not. Have a look at the following screenshot.
In the output of the command line, it shows that I have 2 branches named master and develop and the last commits done in the branches. But my master branch has a tracking branch and it also shows that origin/master (my remote branch) is behind by 1 commit compared to my local branch.
This may sound misleading, when it says ahead 1 it actually means that my local branch is ahead by 1 commit, not that the origin/master (remote branch) is ahead. Look at the following screenshot.
Here I have done a git log –oneline for both local branch and origin/master branch. See that my local master branch has 1 extra commit than the remote master branch.
Configure A Tracking Branch for A Local Branch
There are many ways you can do this. You can do this at the time you create a branch. If you are creating a branch directly from a remote branch a tracking branch will automatically be created for you.
Here in this scenario we have a branch called feature in our remote branch (origin/feature) and we need to create a local branch from the remote feature branch. You can just create the branch and the tracking branch will be automatically created.
git checkout -b feature origin/feature
This will create the feature branch and switch to the branch while creating the tracking branch as well. Its mentioned in the following line “Branch feature set up to track remote branch feature from origin”. Now if we list all the branches you will see that feature branch also has the tracking branch.
If you want to create a branch based off of a local branch and you want to setup a tracking branch you can use the following command.
git checkout --track -b second-feature develop
As you can see in the screenshot, the second-feature branch is created off of local develop branch. But notice the message. “Branch second-feature set up to track local branch develop.” Since we created the branch based off of local develop branch, the tracking branch created was also to the local develop branch. It doesn’t matter if the local branch you base off, has a remote branch associated with it or not. If you create a branch based off of a local branch with tracking enabled, it will create a tracking branch to that local branch.
In a scenario where you already created a branch, you have 2 ways of creating a tracking branch for it. You can either create the tracking branch at the time you are pushing the changes to remote branch. Here we have a branch called third-feature and we will create a tracking branch at the same time we push the code the remote repo.
git push --set-upstream origin third-feature
Look at the screenshot below,
Here you can see that the third-feature branch did not have a tracking branch till the branch was pushed to the remote repository.
The second option to create a tracking branch for an already created branch is done with the following command. The command is –set-upstream-to
git branch --set-upstream-to master fourth-feature
Take a look at the screenshot below,
Here a tracking branch Is created for the fourth-feature branch to track local master branch. You can see the branch information before and after creating the tracking branch.
Removing a Tracking Branch
You can also remove the tracking branch associated with a branch. This is done using a simple command.
git branch --unset-upstream
We are removing the tracking branch to master from the fourth-feature branch using this command. Look at the screenshot to see the change.
Note: Notice that we are in the fourth-feature branch when we remove the tracking branch from it. If you want to remove a tracking branch and the branch you want to have the tracking branch removed is not the active branch, you need to include the branch name to remove the tracking branch. If not, it will remove the tracking branch from the current active branch.
Finally, you can configure git to always create a tracking branch when you create a new branch. You change global git configuration to do this. Use the following command to set the functionality.
git config --global branch.autosetupmerge always
Enabling this will always create a tracking branch to the branch you are basing your new branch. This might come in handy for you. But I tend not to enable this functionality.
Tracking branches or Upstream branches can be an incredibly helpful feature of git if you know the concepts behind it and know how to use it properly. It will speed up your workflow when using git, especially if you are a geek who prefers the command line over a graphical tool for managing git.
Hope you got an understanding of what tracking branches are and how the work and you would use it in your projects as needed. Happy coding and I’ll see you in the next one.