How to Check If a Git Branch Has Diverged from Remote

Introduction

In this lab, you will learn how to check if your local Git branch has diverged from its remote counterpart. This is a fundamental skill for collaborative development and staying up-to-date with project changes.

We will begin by fetching updates from a simulated remote repository and using git status to identify if your local branch is behind. Subsequently, you will explore how to use git log to compare commits between your local and remote branches and finally, verify the divergence using git diff @{u} HEAD.

Skills Graph

Fetch and Check git status for Divergence

In this step, we'll learn how to check if there are any changes in the remote repository that we don't have locally. This is crucial when collaborating with others or when working on a project that is updated elsewhere.

First, let's simulate having a remote repository with some changes. In a real-world scenario, this would be a repository hosted on a platform like GitHub or GitLab. For this lab, we'll use a local directory to act as our "remote".

Navigate back to your project directory if you are not already there:

cd ~/project/my-time-machine

Now, let's fetch the latest changes from the simulated remote. We'll use the git fetch command. This command downloads commits, files, and refs from a remote repository into your local repository. It does not merge them into your current branch.

git fetch origin

You might not see much output if there are no new changes. However, git fetch updates the information about the remote branches in your local repository.

Next, we'll use git status to see if our local branch is behind the remote branch. The git status command is your window into the current state of your repository. It tells you about staged, unstaged, and untracked files, and also provides information about the relationship between your current branch and its upstream branch.

Run the git status command:

git status

If there were changes on the remote that you just fetched, the output of git status would indicate that your local branch is behind the remote branch. It might look something like this:

On branch master
Your branch is behind 'origin/master' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

This message tells you that your local master branch is one commit behind the origin/master branch (the remote version of the master branch). It also suggests using git pull to update your local branch, which we will cover in a later lab.

Understanding the output of git status after fetching is important because it lets you know if there are new changes available from the remote repository before you decide to integrate them into your local work. This helps prevent potential conflicts and keeps you informed about the project's progress.

Use git log to Compare Commits

In the previous step, we used git status to see if our local branch was behind the remote. Now, let's use git log to see the actual commits that are on the remote branch but not on our local branch.

The git log command is incredibly versatile. It allows you to view the commit history in many different ways. To compare our local branch (HEAD) with the remote tracking branch (origin/master), we can use the following syntax:

git log HEAD..origin/master

Make sure you are in the ~/project/my-time-machine directory:

cd ~/project/my-time-machine

Now, run the git log command to compare the branches:

git log HEAD..origin/master

If there are commits on origin/master that are not on your local HEAD (which is currently pointing to your local master branch), this command will list those commits. The output will show the commit details, including the commit hash, author, date, and commit message, for each commit that exists in origin/master but not in your current branch.

For example, if the remote had one new commit, the output might look like this:

commit abcdef1234567890abcdef1234567890abcdef (origin/master)
Author: Another User <[email protected]>
Date:   Tue Aug 8 10:00:00 2023 +0000

    Add a new feature

This output clearly shows the commit that is present on the remote but not locally. The HEAD..origin/master syntax tells Git to show commits that are reachable from origin/master but not from HEAD.

Using git log in this way is a powerful tool for understanding the differences between branches and seeing exactly what changes you would get if you were to update your local branch. It provides more detail than git status about the specific commits that are causing the divergence.

Remember to press q to exit the log view if it opens in a pager.

Verify with git diff @{u} HEAD

In the previous steps, we used git status to see if our local branch was behind the remote and git log to see the commits that were different. Now, let's use git diff to see the actual code changes introduced by those commits on the remote branch compared to our local branch.

The git diff command shows the differences between two points in your Git history. We can use it to compare our current local branch (HEAD) with its upstream branch. The upstream branch is the branch on the remote repository that your local branch is tracking. In our case, the upstream branch for master is origin/master. Git provides a convenient shorthand for the upstream branch: @{u} or @{upstream}.

Make sure you are in the ~/project/my-time-machine directory:

cd ~/project/my-time-machine

Now, run the git diff command to see the differences between your local branch and its upstream branch:

git diff @{u} HEAD

This command will show you the line-by-line differences between the files in your current commit (HEAD) and the files in the latest commit on the upstream branch (@{u}).

If there are changes on the remote that you haven't pulled yet, the output will show those differences. For example, if a line was added to message.txt on the remote, the output might look like this:

diff --git a/message.txt b/message.txt
index a1b2c3d..e4f5g6h 100644
--- a/message.txt
+++ b/message.txt
@@ -1 +1,2 @@
 Hello, Future Me
+This is a new line from the remote.

The + sign indicates lines that are present in the upstream branch (@{u}) but not in your local branch (HEAD).

Using git diff @{u} HEAD is a powerful way to preview the changes that exist on the remote before you merge them into your local branch. It allows you to understand the exact modifications that have been made, which is very helpful for code reviews or simply staying informed about the project's evolution.

Press q to exit the diff view if it opens in a pager.

Summary

In this lab, we learned how to check if a local Git branch has diverged from its remote counterpart. We began by simulating a remote repository and using git fetch to retrieve the latest changes without merging them. Subsequently, we utilized git status to quickly identify if our local branch was behind the remote, which is indicated by messages like "Your branch is behind 'origin/master' by X commit".

Following the initial check with git status, we explored more detailed methods for comparing branches. We learned how to use git log with various options to visualize the commit history and identify differences between the local and remote branches. Finally, we discovered the utility of git diff @{u} HEAD for a precise comparison of the changes between the upstream branch and the current HEAD, providing a clear view of the divergence.