Understanding the Differences Between `git checkout` and `git switch`

Greg Foster
Greg Foster
Graphite software engineer

With the introduction of git switch in Git version 2.23, there has been some confusion about when to use each command. Historically, git checkout has been used for two main purposes: switching between branches and restoring working tree files. However, this dual functionality can lead to confusion and mistakes, especially for newcomers. To address this, Git introduced the git switch and git restore commands to separate these responsibilities.

This guide aims to clarify these differences and provide practical examples to help you understand when and how to use each command effectively.

The git checkout command is one of the most frequently used Git commands, involved in various operations like switching branches, checking out tags, and undoing modifications in the repository.

Syntax:

Terminal
git checkout <branch-name>
git checkout <commit-hash>
git checkout -- <file-name>

We'll cover each of these examples later.

Introduced in Git 2.23, git switch is designed specifically to switch branches, making it clearer and safer than git checkout because it avoids the ambiguity of the latter's multi-purpose nature.

Syntax:

Terminal
git switch <branch-name>
git switch -c <new-branch-name> # Create and switch to a new branch

Like the git checkout syntax, we'll cover each of these example below.

  • Purpose: git checkout is used for both switching branches and restoring file states, whereas git switch is specifically tailored for switching branches.
  • Safety: git switch does not allow you to accidentally overwrite changes, as it is designed to handle branch operations exclusively.
  • Clarity: git switch makes scripts and commands clearer, as it's obvious from the command itself that you are performing a branch change.

git checkout is versatile but should be used with caution due to its potential to overwrite changes. It is still widely used for the following tasks:

Although git switch is preferred for this task, git checkout is still commonly used:

This command is used to switch from the current branch in a Git repository to another branch specified by <branch-name>. When you run this command, Git updates the files in the working directory to match the version stored in the target branch, thus allowing you to work within the context of that branch.

Example:

If you're currently on the main branch and you want to switch to a branch called feature, you would run:

Terminal
git checkout feature

This command is used to switch the current working directory to the state of a specific commit identified by <commit-hash>. This is useful for inspecting old versions of your project without altering the current state of a branch. When you checkout to a commit, you are put in a 'detached HEAD' state, which means you are no longer working on top of a branch.

Example:

Suppose you have a commit with the hash a1b2c3d. To check out this commit, you would run:

Terminal
git checkout a1b2c3d

The terminal would display:

Terminal
Note: switching to 'a1b2c3d'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
...

For a more detailed guide on the 'detached HEAD state', including how to get out of it, see this guide on resolving a detached head state.

This command is used to discard changes in the working directory for specific files. Essentially, it restores the files to their last committed state. This is particularly useful if you want to undo modifications and/or deletions of files that have not yet been staged for commit.

Example:

If you've made changes to a file called example.txt and decide you want to discard these changes, you would run:

Terminal
git checkout -- example.txt

In the terminal, there typically isn't a confirmation message, but the file example.txt will be restored to its last committed state, and all local changes will be lost.

git switch should be used for all branch switching operations as it is designed explicitly for this purpose:

This command is used to switch your current working directory to a different branch specified by <branch-name>. When you run this command, git updates the files in your working directory to match the version stored in the branch you are switching to. This allows you to work on different versions of your project separately.

Example usage: If you have a branch named feature, you can switch to it using:

Terminal
git switch feature

This command combines two actions: it creates a new branch named <new-branch-name> and then switches to it immediately. It's a shorthand for doing git branch <new-branch-name> followed by git switch <new-branch-name>. This is useful for starting new features or bug fixes without affecting the main codebase.

Example usage: To create and switch to a new branch called new-feature, you would use:

Terminal
git switch -c new-feature

These commands help developers manage multiple lines of development within the same project, making it easier to isolate changes without impacting the entire project.

While git checkout remains a powerful tool for various Git operations, git switch offers a more specialized, intuitive, and safer option for branch management.

For further information on switch and checkout` see the official git documentation on "switch" and "checkout".

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2