How to Check If a Git Branch Is Behind the Remote Branch

Introduction

In this lab, you will learn how to determine if your local Git branch is behind its corresponding remote branch. We will cover the essential steps to achieve this, starting with fetching the latest changes from the remote repository using git fetch.

Following the fetch, you will utilize git status to quickly check if your branch is behind the remote. Finally, you will learn how to use git log HEAD..@{u} to view the specific commits that exist on the remote branch but not on your local branch, providing a detailed understanding of the differences.

Skills Graph

Fetch Remote with git fetch

In this step, we will learn how to fetch changes from a remote Git repository. Imagine you are collaborating with others, and they have made changes to the project. git fetch is the command you use to download those changes to your local machine without merging them into your current work.

First, let's simulate having a remote repository. We'll create a simple one locally for demonstration purposes.

cd ~/project
mkdir remote-repo
cd remote-repo
git init --bare

This creates a "bare" repository, which is typically used as a central remote repository. Now, let's go back to our my-time-machine repository and add this as a remote.

cd ~/project/my-time-machine
git remote add origin ../remote-repo

We've added a remote named origin pointing to our simulated remote repository. Now, let's make a change in the remote repository and then fetch it.

cd ~/project/remote-repo
echo "This is a remote change." > remote_file.txt
git add remote_file.txt
git commit -m "Add remote file"

Now, back in our my-time-machine repository, let's fetch the changes from the remote.

cd ~/project/my-time-machine
git fetch origin

You should see output indicating that Git has downloaded the changes from the remote repository. Something like this:

remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 2 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (2/2), 258 bytes | 258.00 KiB | elapsed 0.00s.
From ../remote-repo
 * [new branch]      master     -> origin/master

The git fetch command downloads the commits, files, and references from the remote repository into your local repository. However, it does not automatically merge these changes into your current working branch. This allows you to inspect the changes before integrating them.

Think of git fetch as getting the latest updates from a news feed. You see the headlines and summaries, but you haven't read the full articles yet. You can decide which articles (changes) you want to read (merge) later.

Use git status to Check Behind Status

In the previous step, we fetched changes from the remote repository. Now, let's use git status to see how our local repository compares to the remote.

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

cd ~/project/my-time-machine

Now, run the git status command:

git status

You should see output similar to 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 output tells us a few important things:

• "On branch master": We are currently on the master branch.
• "Your branch is behind 'origin/master' by 1 commit": This is the key message! It indicates that our local master branch is one commit behind the master branch on the origin remote. This means there is a commit on the remote that we don't have locally yet.
• "(use "git pull" to update your local branch)": Git even gives us a hint on how to bring our local branch up to date.

The git status command is your window into the state of your repository. It tells you which branch you are on, whether you have any uncommitted changes, and how your current branch compares to its upstream branch (in this case, origin/master).

Understanding the output of git status is crucial for working with Git effectively. It helps you know if you need to pull changes from the remote, if you have changes to commit, or if your working directory is clean.

Run git log HEAD..@{u} for Behind Commits

In the previous step, git status told us that our local branch is behind the remote branch. But how can we see which commits we are behind by?

We can use the git log command with a special syntax to show only the commits that are on the remote branch but not on our local branch. The syntax HEAD..@{u} compares our current branch (HEAD) with its upstream branch (@{u}, which is origin/master in our case).

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

cd ~/project/my-time-machine

Now, run the following command:

git log HEAD..@{u}

You should see the log entry for the commit we made in the remote repository in Step 1:

commit <commit-hash> (origin/master)
Author: Your Name <[email protected]>
Date:   <Date and Time>

    Add remote file

This command is very useful for seeing exactly what changes you will get when you pull from the remote. It shows you the commit history that is present on the remote tracking branch (origin/master) but not yet on your local branch (master).

Understanding how to view the commits you are behind by is important for staying up-to-date with your collaborators' work and for planning your merges.

Press q to exit the log view.

Summary

In this lab, we learned how to check if a local Git branch is behind its remote counterpart. We began by simulating a remote repository and adding it to our local project using git remote add. We then practiced using git fetch to download changes from the remote without merging them, demonstrating how this command updates our local repository with the latest remote information.

Following the fetch, we would typically use git status to see if our current branch is behind the remote tracking branch and git log HEAD..@{u} to view the specific commits that are present on the remote but not yet in our local branch. These steps collectively provide a clear picture of the divergence between our local work and the remote repository.