A Local Git Branch exists in our local repository, whereas a Remote Branch is present in the remote repository. We can make a Local Branch track a Remote Branch.
There are two main benefits of this tracking connection. The tracking connection helps developers push and pull changes between the Local and Remote branches. We no longer need to explicitly mention the remote branch name while using the Git Push and Git Pull commands. Also, this tracking relationship helps us to compare the differences between the local branch and its remote counterpart. Git informs us how far ahead or behind our Local Branch is from the Remote Branch.
For example, if one developer adds a commit to the Remote Branch, we can view this change and compare it to our local branch state. Git will inform us that our local branch is one commit behind the remote branch.
This tracking relationship is also known as an upstream connection. The remote branch is called the upstream branch for the corresponding local branch, and the remote repository is known as the upstream.
There are a few different ways to make a local branch track a remote branch. Let's learn how to set up a tracking connection between Local and Remote Branches.
The Git Branch command helps us to manage branches. We can use this command to make an existing branch track a remote branch. The --set-upstream option or the -u flag is used for this purpose.
git branch --set-upstream <remote-name>/<branch-name>
git branch -u <remote-name>/<branch-name>
If we are not currently on the local branch, then we need to mention the local branch name as well.
git branch --set-upstream <remote-name>/<branch-name> <local-branch-name>
git branch -u <remote-name>/<branch-name> <local-branch-name>
Note that the --set-upstream option is deprecated and replaced with the more intuitive --set-upstream-to. The -u flag remains the same.
git branch --set-upstream-to=<remote-name>/<branch-name>
git branch --set-upstream-to=<remote-name>/<branch-name> <local-branch-name> #if on a different branch
To verify the upstream or tracking connection, run the Git Branch command with the -vv option.
git branch -vv
The above commands assume that a remote branch is already present. Use the Git Push command to push(or create) a new Remote Branch and track it too. We have to use the same --set-upstream option or -u flag.
git push --set-upstream <remote-name> <branch-name>
git push -u <remote-name> <branch-name>
Let's learn how this tracking relationship is created. We need to make the Local Branch track the Remote-Tracking Branch. The Remote-Tracking Branch, in turn, tracks the corresponding Remote Branch. So, the Local Branch indirectly ends up tracking the Remote Branch. The Remote-Tracking branch acts as a middleman between the Local and Remote Branches.
A -- B -- C
↑
feature (remote branch)
↑ Remote Repo
-----------------------------------------------------------------
↑ Local Repo
origin/feature (remote tracking branch)
↓
A -- B -- C
↑
feature (local branch)
Consider a remote repository with two branches - master and feature.
Remote Repository:
A -- B -- C <- master <- HEAD
\
\
D <- feature
Also, consider a local cloned repository with the same two branches. However, the feature branch has an extra commit(commit E). We also have two remote-tracking branches - origin/master and origin/feature.
Local Repository:
origin/feature
↓
A -- B -- C <- master <- HEAD, origin/master
\
\
D <- feature
We want the local feature branch to track the remote feature branch. Let's run the Git Branch command with --set-upstream-to.
git branch --set-upstream-to=origin/feature # currently checked out on feature branch
git branch --set-upstream-to=origin/feature feature # not checked out on feature branch
Or, we can use -u .option
git branch -u origin/feature # currently checked out on feature branch
git branch -u origin/feature feature # not checked out on feature branch
We can verify whether the upstream connection has been created by running the Git Branch -vv command. The output shows that the feature branch tracks the origin/feature branch(written in square brackets). And the master branch tracks the origin/master. For a branch that doesn't track any other branch, there will be no square brackets part in the output.
git branch -vv
Output:
* feature 2825557 [origin/feature: ahead 1] E
master b22281a [origin/master] C
Now, we can compare the local and remote feature branches. Run the Git Status command from the feature branch to do this. As we can see in the output, the local branch is ahead of 'origin/feature' by 1 commit. We get this output because the commit E is not present in the remote feature branch.
git status
Output:
On branch feature
Your branch is ahead of 'origin/feature' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
We can also easily push the new commit(commit E) to the remote branch by just running the Git Push command.
git push
Branching is an essential feature of Git. Local and Remote Branches work in unison. Developers can test new features on local branches and then publish them on the remote repository. Other developers can view these changes and compare them to their local state.
A tracking relation between local and remote branches makes it easy to view and compare the changes. It also helps developers push and pull changes without worrying about the Remote or the Branch.
We can use the Git Branch command to set up a tracking relation. The --set-upstream-to option or the -u flag are used with the command.
The tracking relation is established with the help of remote-tracking branches. These branches track the changes in the remote branches.