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

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.

git checkout

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:

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

We'll cover each of these examples later.

git switch

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:

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.

Key differences

• 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.

When to use each command

Using git checkout

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:

1. Switching between branches (with caution)

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:

git checkout feature

2. git checkout <commit-hash>

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:

git checkout a1b2c3d

The terminal would display:

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.

3. git checkout -- <file-name>

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:

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.

Using git switch

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

1. git switch <branch-name>

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:

git switch feature

2. git switch -c <new-branch-name>

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:

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".