git checkout

The original swiss-army command. Use switch/restore instead today.

🎯 What & why

The original swiss-army command for switching branches and restoring files. Still works; still ships. New code should use git switch (branches) and git restore (files) instead — the split makes intent unambiguous.

🧠 Mental model

Two unrelated jobs in one verb: 'change which branch HEAD points to' and 'overwrite paths in the working tree from a tree-ish.' Whether checkout does one or the other depends on its arguments. That overload is exactly why switch/restore were created.

🛠️ Synopsis

git checkout [<options>] <branch>
git checkout [<options>] [<branch>] -- <pathspec>...
git checkout [-b | -B] <new-branch> [<start-point>]

🎚️ Switches & options

Flag	What it does
`-b <name>`	Create a new branch and check it out.
`-B <name>`	Like `-b` but reset if it already exists.
`--detach`	Check out a commit without making/moving a branch — detached HEAD.
`-- <path>`	Restore `<path>` from the index (or from `<branch>:<path>` if a tree-ish is given).
`--orphan <name>`	New branch with no history — empty parent.

💡 Use cases

Legacy scripts that use checkout for branch switching.
Inspecting an old commit (detached HEAD).
Pulling a file from another branch (git checkout other-branch -- path/to/file).

🧪 Examples

Switch to an existing branch.

$ git checkout feature/login

Create and switch to a new branch.

$ git checkout -b feature/login

Restore a single file from HEAD (legacy form of git restore).

$ git checkout -- src/main.c

Detached HEAD at a specific commit (good for inspection, bad for committing).

$ git checkout --detach v1.2

🎓 Recommendations

Use git switch for branches and git restore for files in new code. Reserve checkout for the rare case (--detach, --orphan) where the new commands don't have a one-liner.
Detached HEAD is fine for reading; for writing, switch to a branch first.

🪤 Common pitfalls

git checkout <name> ambiguity: is <name> a branch, a file, or both? Git tries branch first, then file. If both exist, you get a confusing error.
Committing on detached HEAD then switching away orphans those commits — they're only reachable via reflog.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.