Terminal GuideTerminal Guide

git checkout Command Guide

Switch branches or restore working tree files

7 min readLast updated: January 19, 2026
Dai Aoki

Dai Aoki

CEO at init, Inc. / CTO at US & JP startups / Creator of WebTerm

Quick Reference

Branches

git checkout <branch>Switch to branch
git checkout -b <name>Create and switch
git checkout -Switch to previous

Files

git checkout -- <file>Discard changes
git checkout HEAD <file>Restore from HEAD
git checkout <commit> -- <file>Get file version

Detached

git checkout <commit>Detached HEAD
git checkout <tag>Checkout tag
git checkout HEAD~33 commits back

Downloadable Image Preview

Failed to generate preview

Basic Usage

The git checkout command switches branches and restores working tree files. It's a versatile command with multiple use cases.

bash
# Switch to an existing branch
git checkout main

# Create and switch to new branch
git checkout -b feature-x

# Discard changes in a file
git checkout -- src/app.js
Tip
In Git 2.23+, consider using git switch for branches and git restore for files. They're clearer alternatives.

Switching Branches

bash
# Switch to existing branch
git checkout develop

# Create and switch to new branch
git checkout -b feature/login

# Create branch from specific commit
git checkout -b hotfix abc1234

# Switch to previous branch
git checkout -

# Track and checkout remote branch
git checkout --track origin/feature-x

Restoring Files

bash
# Discard changes in working directory
git checkout -- file.js

# Restore file from specific commit
git checkout abc1234 -- file.js

# Restore file from another branch
git checkout main -- src/config.js

# Restore all files in directory
git checkout -- src/

# Restore to HEAD (same as --)
git checkout HEAD -- file.js
Warning
git checkout -- <file> permanently discards uncommitted changes. This cannot be undone if the changes weren't staged.

Detached HEAD State

Checking out a commit (not a branch) puts you in "detached HEAD" state:

bash
# Checkout a specific commit (detached HEAD)
git checkout abc1234

# Checkout a tag
git checkout v1.0.0

# Go back N commits
git checkout HEAD~3

# View the detached state warning
# "You are in 'detached HEAD' state..."

# Create a branch to save work in detached HEAD
git checkout -b new-branch-name

Detached HEAD Tips

  • • Safe for viewing old code
  • • Commits made here can be lost
  • • Create a branch to preserve work
  • • Return to a branch with git checkout main

Checkout vs Switch/Restore

Git 2.23 introduced clearer alternatives:

bash
# Old way (checkout does everything)
git checkout main              # Switch branch
git checkout -b feature        # Create and switch
git checkout -- file.js        # Restore file

# New way (separate commands)
git switch main                # Switch branch
git switch -c feature          # Create and switch
git restore file.js            # Restore file

Practical Examples

bash
# Start new feature
git checkout -b feature/payment

# Quick switch between main and feature
git checkout main
git checkout -   # Back to feature

# Discard all local changes
git checkout -- .

# Get file from main branch
git checkout main -- package.json

# Explore old version without committing
git checkout v1.0.0
# ... look around ...
git checkout main  # Return

Frequently Asked Questions

What is a detached HEAD state?

Detached HEAD means you're not on a branch - you're looking at a specific commit. Any new commits won't belong to any branch and could be lost. Create a branch to save your work.

What is the difference between git checkout and git switch?

They both switch branches, but switch (Git 2.23+) is clearer and safer. checkout can also restore files, while switch only handles branches. For files, use "git restore" instead.

How do I discard uncommitted changes to a file?

Use "git checkout -- <file>" or the newer "git restore <file>". This discards working directory changes - the file reverts to its last committed state.

What does "git checkout -" do?

It switches back to the previously checked out branch. It's like "cd -" in bash - a quick way to toggle between two branches.

Can I checkout a file from another branch?

Yes! Use "git checkout <branch> -- <file>" to get a specific file from another branch without switching branches.

Summary

git checkout is versatile but can be confusing. Consider using git switch and git restore for clarity.

Quick Reference

  • git checkout <branch> - Switch branch
  • git checkout -b <name> - Create and switch
  • git checkout -- <file> - Discard changes
  • git checkout - - Previous branch

Official Documentation

For authoritative information, refer to the official documentation:

Related Articles