How to PROPERLY list remote branches in git

Quick cheat sheet to list remote branches in git

Comfortably listing your remote branches is one of the routes to manage your workstation. The three standard commands to use during git list remote branches are:

Use

git branch -r

to list only remote branches,

git branch -a

to list all local and remote branches connected to your repo, or

git show-branch

to list both local and remote repos with their updated commits.

Although the above commands reveal remotes, using them often come with some challenges that this tutorial solves.

You are about to understand when and how to use the three git list branches commands and related commands to solve associated challenges. Before that, it would be best to understand git branching and set up a lab to practice git list remote branches.

Let us get started.

 

Understand git branching

You need to learn branching concepts to smoothen your understanding of git list remote branches. For instance, what is git branching? Simply put, git branching is the creation of independent development lines (branches).

Why should you do git branching? The main reason for creating branches is to enable multiple developers to work on the same project simultaneously. Each developer focuses on completing an independent program while collaborating with the team through merging, pushing, and pulling.

As a result, you, as the developer in a team collaborating on the project, need to be aware of your repos on the local machine and remote ones on websites like GitHub, Bitbucket, or GitLab.

Synchronizing the local repo with a remote one occurs through an upstream branch. The configured upstream relieves you of the burden of constantly typing a lengthy remote URL. For example, handling an easy-to-remember name, such as origin, is quicker than recalling and typing a long repo URL cloned on GitHub.

Even if you work on personal projects, mastering git list remote branches helps you have a fantastic time identifying your remote branches, as shown below.

 

Lab setup to explain git list remote branches

Clone a remote repo

I am creating a remote repo called list_remotes on GitHub to help us explore git list remote branches.

The repo has one branch named main. main, which used to be called master before 2020, is GitHub's default branch name for a new repo.

You can view branches on GitHub by navigating to the repo's landing page. You see a menu bar with the main branch button, number of branches, and tags on the top-left corner of the body section.

Alternatively, you can click the dropdown on the right side of the main button, followed by view all branches.

You can then edit the main branch's details from the resulting table.

Let us copy the repo URL,

head over to the terminal, and clone the repo.

 

Build the second branch locally

There are many ways to create a remote branch. For instance, you can head over to GitHub and manually create a branch. Alternatively, you can make it locally, do commits, and push the changes through it.

You then move to GitHub, Compare,and pull request the changes. As you will see in this tutorial, you then return to the local repo and squash merge the changes.

Before building a branch, let us see the local branches. cd into the directory containing the cloned repo.

cd list_remotes

List local branches.

git branch

Create, stage, commit and push a file through the main branch before heading to the git list remote branches section.

Create a file

touch file.txt

and stage it.

git add file.txt

Commit the change

git commit -m "add text file in main the branch"

then push it.

git push

Refresh the GitHub repo page to view the pushed change.

We still have one remote, main.

Return to the terminal and create a local branch.

git switch -c first_remote

Create, stage, commit and push a file through the first_remote branch before git list remote branches.

touch f1.py

git add f1.py

git commit -m "track py file in the first_remote branch"

git push --set-upstream origin first_remote

Refresh the remote on GitHub. We see unmerged changes on a new branch.

Let us merge the branch remotely by responding to the green guidelines after Compare & pull request on GitHub.

Return to the command line and merge the branch locally as well.

git checkout main

git merge --squash first_remote

git commit -m "merge first_remote"

git push -f

Now that we have a remote repo with two branches to practice git list remote branches, let us use the setup in the examples section.

 

Example-1: Git list remote branches using the -r flag

The most typical way to git list remote branches is to use the

git branch -r

command, enabling you to see a list of remote branches connected to your repo.

origin is the name of our list_remotes branch's upstream. HEAD implies where the last commit points.

 

Challenges of using git branch -r command and their solutions

Several factors may cause git branch -r to ignore some of your remote branches. For example, you cannot see unfetched branches because the command only shows remote branches tracked locally.

If you cannot see your remotes after running git branch -r, try any of the following options.

Run the command

git ls-remote --heads <remote-name>

that is,

git ls-remote --heads origin

on your command line or type

git ls-remote

Alternatively, we can fetch the remotes before running the git branch -r command, as follows.

 

Create an unfetched branch on GitHub

Move to the list_remotes repo on GitHub and click the dropdown on the right-hand side of the main branch. Type branch name in the input box and click, "create a branch: third from 'main' " as shown in this screenshot:

Recheck the remotes on your terminal. Although we can see the third branch on GitHub, git branch -r cannot list it on the terminal.

Return to your terminal and run these commands

git fetch

git branch -r

We can now see the branch named third listed locally.

 

Example-2: Git list remote branches using the -a flag

The git branch -a command works similarly to the git branch -r. The only difference is that the -a flag lists local branches besides remotes.

 

Challenges if using git branch -a command and their solutions

If you still can't list remote branches using the -a flag, try either of these commands:

git branch -ar

or

git fetch

followed by

git branch -a

 

Example-3: How to git list remote branches using the git show-branch command

The last command we will use in this tutorial to git list remote branches is

git show-branch

It enables us to list both local and remote branches with each branch's latest commit.

Solve challenges

Sometimes you want to know more than branches with their commits. For instance, what are the statuses of the remotes relative to the local repo? That is where the

git remote show origin

command comes in. It reveals the tracked and unfetched files on your terminal or command line.

 

Summary

You can use any of these commands to git list remote branches:

git branch -r

git branch -a

git show-branch

However, when the primary commands fail to show your target remote branch, use their alternatives as tabulated below.