Understanding git remote branches

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


This guide will explain what a Git remote branch is, how it differs from local and remote tracking branches, and how to effectively manage these branches in your Git workflow.

A Git remote branch refers to a branch in a remote repository. For instance, when you clone a repository, you are essentially copying all of its files and branches from a remote server to your local environment. The branches that exist on the server are considered "remote branches."

A common convention in Git is to name the primary remote repository "origin". This is the default name given to the server from which the repository was initially cloned. Remote branches are usually referenced by specifying the remote name followed by a slash and then the branch name, for example, origin/main.

Local branches are branches that exist in your local repository. You can switch between these branches, make changes, commit them, and manage them without requiring an internet connection or interacting with a remote repository until you choose to push or fetch changes.

In contrast, remote branches reflect the state of branches on your remote repository at the last time you communicated with it (fetched, pushed, or pulled changes). You cannot directly check out a remote branch; instead, you interact with them through remote tracking branches.

Remote tracking branches are local references to the state of remote branches. They act as bookmarks to remember where the remote branches were the last time you interacted with the remote repository. For instance, origin/main is a remote tracking branch that tracks the main branch on the origin remote.

Remote tracking branches automatically move forward when you do network operations like git fetch, git pull, or git push. They are crucial for Git to determine how your local and remote repositories differ. You don't make direct changes to these branches; instead, you work in a local branch that tracks a remote branch, make your changes there, and then push those changes back to the remote.

To see if a specific remote branch exists, you can use the git branch -r command, which lists all remote branches known to your local repository. This will show you all branches that Git is aware of for each remote:

Terminal
git branch -r

You can also use git ls-remote to query the remote repository directly, showing all references it has, including branches:

Terminal
git ls-remote origin

This command will show all branches and tags on the remote named origin, letting you verify the existence of a branch directly on the remote.

To update your remote tracking branches (i.e., to get the latest state of the remote branches), you can run:

Terminal
git fetch origin

This command fetches all updates from the origin remote but does not merge any changes into your local branches.

To start working on a remote branch locally, you create a new local branch that tracks the remote branch:

Terminal
git checkout -b new-branch origin/remote-branch

This command creates a new branch called new-branch that tracks the remote-branch from origin.

After committing your changes locally, you can share them by pushing them to the remote branch:

Terminal
git push origin local-branch:remote-branch

This command pushes changes from your local local-branch to the remote-branch on origin.

For further reading see the official Git documentation on branching.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2