Listing Branches

Now that you understand how to create branches with git branch <branch-name> and switch between them using git switch <branch-name> (or the older git checkout <branch-name>), you need a way to see all the different lines of development you have available in your local repository. Keeping track of your branches is important for managing your work and understanding the project's structure.

The git branch Command

The simplest way to see your local branches is to run the git branch command with no arguments:

git branch

This command lists all the branches that exist in your local repository. Git will also indicate which branch you are currently working on by placing an asterisk (*) next to its name and often highlighting it in a different color (depending on your terminal configuration).

For example, if you have a main branch and a feature-login branch, and you are currently working on feature-login, the output might look like this:

  main
* feature-login

This tells you that two local branches exist (main and feature-login) and that your working directory currently reflects the state of the feature-login branch. Any commits you make right now will be added to the feature-login branch history.

Viewing Remote-Tracking Branches

Often, you'll be working with repositories that are connected to a remote server (like GitHub or GitLab), as discussed in the upcoming chapter on remote repositories. Git keeps track of the state of branches on that remote server using special references called remote-tracking branches. These are like local bookmarks showing you where the branches on the remote were the last time you communicated with it (e.g., using git fetch or git pull).

To see only these remote-tracking branches, you can use the -r (for "remote") flag:

git branch -r

The output typically prefixes the branch names with the name of the remote repository (commonly origin).

  origin/HEAD -> origin/main
  origin/main
  origin/develop
  origin/feature-login

Here, origin/main and origin/develop represent the main and develop branches as they exist on the origin remote. origin/HEAD is a special pointer usually indicating the default branch on the remote. Notice that these are not your local branches; they reflect the remote state.

Viewing All Branches (Local and Remote)

To get a complete picture of all branches, both local and remote-tracking, use the -a (for "all") flag:

git branch -a

This command combines the output of git branch and git branch -r, giving you a comprehensive list.

  main
* feature-login
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/develop
  remotes/origin/feature-login

You can see your local branches (main, feature-login) and the remote-tracking branches (prefixed with remotes/origin/). This is particularly useful for comparing your local work against the state of the remote repository.

Getting More Information

Sometimes, just seeing the branch names isn't enough. You might want to know what the latest commit on each branch is. The -v (for "verbose") flag provides this information, showing the short SHA-1 hash and the subject line of the latest commit on each branch:

git branch -v

  main           a1b2c3d Initial project setup
* feature-login  e4f5g6h Add login form fields

Adding another v (-vv) provides even more detail, including the upstream branch that your local branch is tracking (if any), which is helpful when working with remotes.

git branch -vv

  main           a1b2c3d [origin/main] Initial project setup
* feature-login  e4f5g6h [origin/feature-login: ahead 1] Add login form fields

This output tells you that main is tracking origin/main and is up-to-date, while feature-login is tracking origin/feature-login and has one commit (ahead 1) that hasn't been pushed to the remote yet.

In summary, the git branch command, along with its -r, -a, and -v/-vv options, provides essential tools for inspecting the different lines of development within your repository, helping you navigate and manage your work effectively.