Git Checkout

The git checkout command is one of the most versatile commands in Git, which is both its strength and its source of confusion for newcomers. Historically, git checkout served multiple purposes — switching branches, restoring files, and even creating new branches. Understanding what this command actually does under the hood will help you use it confidently in any situation.

What Git Checkout Actually Does

At its core, git checkout updates the files in your working directory to match a specific version stored in Git. When you checkout a branch, Git updates all files to reflect the latest commit on that branch and tells HEAD to point to that branch. When you checkout a specific file, Git replaces just that file with its version from the specified commit.

Think of it like a time machine combined with a dimension hopper — you can travel to any point in your project's history or jump to any parallel branch of development.

Switching Between Branches

The most common use of git checkout is switching between branches:

When you run this command, Git does three things:

1. Moves the HEAD pointer to the develop branch
2. Updates the files in your working directory to match the latest commit on develop
3. Updates the staging area to match that commit as well

If you have uncommitted changes that would conflict with the branch you are switching to, Git will refuse the checkout and warn you:

Creating and Switching in One Step

A very common workflow is creating a new branch and immediately switching to it:

This is equivalent to running:

You can also create a branch from a specific commit or tag:

This creates a new branch starting from the tagged release v2.3.1 rather than from your current position.

Checking Out Files

You can use git checkout to restore individual files to a previous state:

This replaces src/utils.js in your working directory with the version from the last commit, effectively discarding your uncommitted changes to that file. The -- separator is important — it tells Git that what follows is a file path, not a branch name.

To restore a file from a specific commit:

This grabs the database.yml file as it existed in commit abc1234 and puts it in both your working directory and staging area.

Detached HEAD State

One of the most confusing situations for Git beginners is the detached HEAD state. This happens when you checkout a specific commit rather than a branch:

Git will display a warning:

In detached HEAD state, you are not on any branch. Any commits you make will be orphaned once you switch to a branch — they will exist in the Git database but no branch points to them. This is useful for exploring historical code or running tests against old versions.

If you want to keep work done in detached HEAD state, create a branch before switching away:

The Modern Alternative: Git Switch and Git Restore

Starting with Git 2.23, the Git team introduced two new commands to replace the dual nature of git checkout:

• git switch — for switching branches
• git restore — for restoring files

The newer commands are less ambiguous and harder to misuse. However, git checkout remains fully functional and is still widely used in documentation, tutorials, and scripts.

Practical Scenarios

Scenario: Quickly testing another branch's code

Your colleague asks you to test their branch:

Scenario: Reverting a specific file to its last committed state

You have been experimenting with changes to a CSS file and want to start over:

Scenario: Looking at how code looked two weeks ago

Common Mistakes

A frequent error is accidentally checking out a file when you meant to switch branches, or vice versa. If you have a branch named main.css and a file named main.css, the command git checkout main.css becomes ambiguous. Always use -- to be explicit:

Another pitfall is losing commits in detached HEAD state. Always check git status after checkout to confirm you are where you expect to be.

Key Takeaways

The git checkout command is powerful but overloaded with multiple responsibilities. For new projects, consider adopting git switch and git restore for clarity. Regardless of which command you use, always be aware of whether you are switching contexts (branches) or restoring content (files) — this mental distinction prevents most checkout-related mistakes.