How to Check If a Git Branch Exists on Remote

Introduction

In this lab, you will learn how to check if a specific Git branch exists on a remote repository. We will explore two primary methods for achieving this.

First, you will use the git ls-remote command to inspect references, including branches, on a remote repository by providing its URL. This allows you to see what's available on the remote without needing to clone it. Following this, you will learn how to use the git branch -r command to list remote branches that are tracked by your local repository. Finally, you will apply these techniques to verify the existence of a specific branch on a remote.

Skills Graph

Run git ls-remote to Check Remote

In this step, we will learn how to check the remote repositories associated with your local Git repository. A remote repository is essentially a version of your project that is hosted on the internet or a network, like on platforms such as GitHub, GitLab, or Bitbucket. It allows you to collaborate with others and back up your work.

To see the remote repositories configured for your current project, you can use the git remote command. However, to get more detailed information about the remote, including the references (like branches and tags) available on the remote, we use the git ls-remote command.

First, let's make sure we are in our project directory. Open your terminal and navigate to the my-time-machine directory:

cd ~/project/my-time-machine

Now, let's use git ls-remote to check a remote repository. For this example, we will use a public Git repository. Type the following command:

git ls-remote https://github.com/labex-io/example-repo.git

You should see output similar to this:

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9 HEAD
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9 refs/heads/main
... (other references)

This command contacts the remote repository at the given URL and lists all the references (like branches and tags) available there, along with their corresponding commit hashes. The HEAD reference usually points to the default branch (often main or master).

Understanding git ls-remote is useful when you want to inspect a remote repository without cloning it entirely. It gives you a quick overview of what branches and tags are available on the remote.

Use git branch -r to List Remote Branches

In the previous step, we used git ls-remote to see references on a remote repository by providing its URL. Another common way to view remote branches, especially for remotes you have already added to your local repository, is using the git branch command with the -r flag.

The git branch command is primarily used to list, create, or delete local branches. Adding the -r flag tells Git to list the remote-tracking branches. Remote-tracking branches are references in your local repository that keep track of the state of branches on a remote repository. They are automatically updated when you perform Git operations like fetch or pull.

Since our current my-time-machine repository doesn't have any remotes added yet, let's first add a remote so we can use git branch -r. We'll add the same example repository we used in the previous step as a remote named origin.

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

cd ~/project/my-time-machine

Now, add the remote:

git remote add origin https://github.com/labex-io/example-repo.git

This command adds a new remote named origin pointing to the specified URL. origin is a conventional name for the primary remote repository.

Now that we have a remote configured, we can use git branch -r to list the remote branches. However, before git branch -r can show you the remote branches, your local repository needs to know about them. This information is updated when you fetch from the remote. Let's fetch the latest information from the origin remote:

git fetch origin

You should see output indicating that Git is fetching objects from the remote.

Now, let's list the remote branches using git branch -r:

git branch -r

You should see output similar to this:

  origin/HEAD -> origin/main
  origin/main

This output shows the remote-tracking branches. origin/main represents the main branch on the origin remote. The origin/HEAD entry indicates which branch HEAD is pointing to on the remote, which is typically the default branch.

Using git branch -r is a quick way to see which branches exist on your configured remotes without needing to connect to the remote every time, as the information is stored locally after a fetch or pull.

Verify Specific Remote Branch

In the previous step, we listed all remote-tracking branches using git branch -r. Sometimes, you might want to specifically check if a particular branch exists on a remote repository. You can do this by combining git ls-remote with grep or by examining the output of git branch -r.

Let's use git ls-remote again, but this time we'll filter the output to see if the main branch exists on the origin remote.

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

cd ~/project/my-time-machine

Now, run the following command:

git ls-remote origin main

You should see output similar to this:

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9 refs/heads/main

This command specifically asks the origin remote for information about the main reference (which corresponds to the main branch). If the branch exists, it will show the commit hash it points to and the full reference name (refs/heads/main). If the branch did not exist, there would be no output.

Alternatively, you could achieve a similar result by checking the output of git branch -r. Since we already ran git fetch origin in the previous step, our local repository has information about the remote branches.

You can use git branch -r and pipe its output to grep to search for a specific branch. For example, to check for origin/main:

git branch -r | grep origin/main

If the origin/main remote-tracking branch exists, this command will output:

  origin/main

If it didn't exist, grep would find nothing, and there would be no output.

Both git ls-remote <remote> <branch> and git branch -r | grep <remote>/<branch> are useful ways to verify the existence of a specific branch on a remote repository. git ls-remote directly queries the remote, while git branch -r uses the locally cached information from the last fetch.

Summary

In this lab, we learned how to check if a Git branch exists on a remote repository. We explored two primary methods for this.

First, we used the git ls-remote command, which allows us to inspect references (including branches) on a remote repository by providing its URL, without needing to clone it. This provides a detailed list of available references and their commit hashes. Second, we learned how to use the git branch -r command to list remote branches for remotes that are already configured in our local repository. Finally, we practiced verifying the existence of a specific remote branch using these methods.