Reflect on your 2024 year in code

How to checkout a branch in Git

Kenny DuMez
Kenny DuMez
Graphite software engineer
Try Graphite


Note

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


Checking out a branch in Git allows developers to switch between different versions of their codebase. This guide will cover the necessary steps and commands to checkout a branch from Git in various scenarios.

The git checkout command is used to switch branches and restore working tree files. It's a way to point your local environment to a different snapshot of your project, represented by branches or commits.

Before checking out a branch, especially one that might have been added recently by another team member, it's important to update your list of remote branches:

Terminal
git fetch origin

This command retrieves the latest list of branches from the remote named origin.

To switch to the new branch run:

Terminal
git checkout <branch-name>

Replace <branch-name> with the name of the branch you want to switch to.

If you want to work with a branch that exists on the remote repository but not on your local machine, you can do so directly by:

Terminal
git checkout --track origin/<branch-name>

This command will automatically set up your local branch to track the remote branch, allowing you to push and pull changes without specifying the remote each time.

Sometimes, you might need to create a new branch based on another branch. This is common when starting a new feature that depends on the changes made in a different feature branch.

To create a new branch based on another branch, run:

Terminal
git checkout -b new-feature-branch existing-feature-branch

This creates and checks out new-feature-branch based on existing-feature-branch.

There are scenarios where you might need just one file or a few files from another branch without switching the entire branch. This can be done with:

Terminal
git checkout <branch-name> -- <path-to-file>

Replace <branch-name> with the branch from which you want to fetch the file, and <path-to-file> with the path to the file you need.

  • Be cautious with changes in the working directory: Changes in your working directory that have not been committed will be carried over when you switch branches. This can lead to conflicts or unexpected behavior. Commit or stash your changes before switching branches.
  • Use git fetch regularly: Keeping your local copy of the remote up-to-date helps avoid conflicts and errors when checking out branches.

For further reading see the official Git documentation.

The Graphite CLI offers a streamlined approach to managing Git workflows, particularly emphasizing ease in handling complex scenarios like stacked pull requests. This tool simplifies Git commands and enhances pull request (PR) operations, making it an indispensable tool for modern developers.

The gt command simplifies numerous Git operations, making daily tasks more efficient and less error-prone. Here’s how you can leverage it for common Git tasks:

Instead of the standard Git commands, you can use gt for a more intuitive experience. Here’s how you can switch to the main branch using Graphite CLI:

Terminal
gt checkout main

This command replaces the traditional git checkout command, streamlining the checkout process with Graphite’s enhanced functionality.

Creating a new branch and a corresponding pull request is more straightforward with the Graphite CLI:

Terminal
# Create a branch with a single commit
gt create --all --message "feat(api): Add new API method for fetching users"
# Push changes and create a pull request
gt submit

This set of commands helps you create a branch, add all changes, commit them with a message, and then push these changes as a new pull request, all in one go.

Graphite CLI excels in managing stacked pull requests, which is a method of grouping related PRs in a way that each PR builds on the parent one. This is particularly useful for breaking down large features into manageable reviews.

You can start a new PR stack with the following commands:

Terminal
# Assuming changes are made in your editor
gt create --all --message "Initial commit for feature"
gt submit --stack

Graphite CLI makes it easy to address feedback on any part of the stack. You can amend changes and restack with ease:

Terminal
gt modify --all
gt restack

This modifies the current stack’s branch and restacks all subsequent branches to incorporate the latest changes, maintaining the integrity of the stack.

To keep your stack updated with the latest changes from the main branch, Graphite CLI offers a simple syncing mechanism:

Terminal
gt sync

This command will fetch the latest updates, rebase your stacks, and clean up any branches that have been merged or closed.

Graphite’s CLI integrates deeply with your Git workflow, offering both simplicity and powerful features to manage branches and pull requests efficiently. For a more comprehensive understanding and further features, refer to the official Graphite documentation.

Built for the world's fastest engineering teams, now available for everyone