Why was git checkout replaced?

checkout did two different things: switch branches AND restore files. Git 2.23 introduced git switch (branches) and git restore (files) for clarity. checkout still works but the newer commands are recommended.

What is detached HEAD?

When you checkout a commit (not a branch), HEAD is no longer attached to a branch. Commits you make in this state will be lost if you don't create a branch. Use git checkout -b my-branch to fix the situation.

What is the difference between checkout and switch?

switch only switches branches, which is clearer and safer. checkout can also restore files, which leads to confusion. For beginners, switch is recommended.

How do I undo a checkout?

If you switched branches, just checkout the previous branch again. If you restored a file, the overwritten changes are lost (unless they were committed or stashed).

What happens if I have uncommitted changes?

Git will refuse to switch branches if it would overwrite your changes. Commit or git stash before checking out. Or use git checkout -f to force (warning: changes will be lost).

Git checkout: switch branches or restore files

git checkout is the legacy command for switching branches, creating branches and restoring files. Now replaced by switch and restore, it remains widely used.

Practice git checkout Git Glossary

gitquest — enquête

Legacy

What is git checkout?

git checkout is Git's Swiss Army knife: it switches branches, creates branches, and restores files. It's the most versatile but also the most confusing command.

Since Git 2.23, it has been replaced by two clearer commands: git switch for branches and git restore for files.

Git checkout syntax

git checkout branch

Switch to an existing branch

git checkout -b new-branch

Create and switch to a new branch

git checkout -- file

Restore a file from the last commit

Git checkout in practice

Switch branches or restore files.

Branches

gitquest — checkout branch

# Switch branches

$git branch

* main

feature-login

fix-header

$git checkout feature-login

Switched to branch 'feature-login'

# Create and switch to a new branch

$git checkout -b feature-signup

Switched to a new branch 'feature-signup'

Files and commits

gitquest — checkout file

# Restore a file from the last commit

$git checkout -- index.html

index.html restored

# Restore a file from a specific commit

$git checkout a1b2c3d -- style.css

style.css restored from a1b2c3d

# Explore an old commit (detached HEAD)

$git checkout a1b2c3d

HEAD is now at a1b2c3d...

checkout vs switch vs restore

`checkout`

Does everything: branches, files, commits. Versatile but confusing.

Legacy but still functional

`switch`

Only for switching branches. Clearer and safer.

Recommended since Git 2.23

`restore`

Only for restoring files. Replaces checkout -- file.

Recommended since Git 2.23

Common mistakes with git checkout

Ending up in detached HEAD

If you checkout a commit instead of a branch, you're in detached HEAD. Create a branch with git checkout -b my-branch to avoid losing your work.

Overwriting local changes

git checkout -- file overwrites uncommitted changes to the file. This is irreversible if the changes were not stashed or committed.

Confusing branch and file

If a branch and a file have the same name, use -- to disambiguate: git checkout -- file.

Part of the Git Branching Workflow guide

Related commands

git switch

Switch branches (modern)

git restore

Restore files (modern)

git branch

Manage branches

GitQuest is created by Anaïs (nouvelle fenêtre), web developer and head of education, specializing in tech training and digital accessibility.

Questions about git checkout

Navigate between branches with GitQuest

Learn to juggle between branches and commits through interactive challenges.

Start the investigations