/compare/git/git-switch-vs-git-checkout
git switch vs git checkout: which one to use
verified onenvironmentlocal · windows 10.0.26200 arm64 · GNU bash 5.3.15 (Git Bash) · git version 2.55.0.windows.5updated
- tool
- Git
- compares
- git switch / git restore vs git checkout
Use git switch to change branches and git restore to undo changes in files; both arrived in Git 2.23 to split the two jobs of git checkout. git checkout still works and is not deprecated, but because it accepts both branch names and file paths, a typo can discard file changes instead of switching branches. The new commands only do one thing each.
Equivalents
| Task | git switch / restore | git checkout |
|---|---|---|
| Switch to a branch | git switch main | git checkout main |
| Create and switch | git switch -c feature | git checkout -b feature |
| Previous branch | git switch - | git checkout - |
| Track a remote branch | git switch feature (from origin/feature) | git checkout feature |
| Inspect an old commit | git switch --detach abc1234 | git checkout abc1234 |
| Discard edits in a file | git restore app.js | git checkout -- app.js |
| Unstage a file | git restore --staged app.js | git reset app.js |
| File from another branch | git restore --source=main app.js | git checkout main -- app.js |
Safer by design
git init -q -b main repo && cd repo
echo v1 > app.js && git add app.js && git commit -qm v1
first=$(git rev-parse --short HEAD)
echo v2 > app.js && git commit -qam v2
git switch "$first" 2>&1 | head -n 2
git switch -q --detach "$first" && git branch --show-current || true
git switch -q main
echo "local edit" > app.js
git switch app.js 2>&1 | head -n 1Output
fatal: a branch is expected, got commit 'fa057d8' hint: If you want to detach HEAD at the commit, try again with the --detach option. fatal: invalid reference: app.js
git switch refuses to detach HEAD unless you say --detach, and refuses file paths entirely. git checkout app.js in the same situation would have silently thrown away the local edit.
Criterion by criterion
| Criterion | git switch / restore | git checkout |
|---|---|---|
| Switch branches | git switch | yes |
| Create a branch | git switch -c | git checkout -b |
| Restore files | git restore | yes, with -- PATH |
| Detached HEAD | only with --detach | implicitly, for any commit |
| Ambiguous name (branch and file) | impossible | needs -- to disambiguate |
| Availability | Git 2.23+ (2019) | every Git version |
Sources
Related pages
errors · giterror: pathspec 'x' did not match any file(s) known to gitgit checkout prints this when the name is neither a branch nor a tracked file, often a remote branch not fetched yet. Fetch, check the name, or create it.errors · giterror: Your local changes to the following files would be overwritten by checkoutGit refuses to switch branches when uncommitted edits would be lost in files that differ between branches. Commit, stash and pop, or use git switch -m.glossary · gitWhat is a detached HEAD in Git?Detached HEAD means HEAD points at a commit instead of a branch, after checking out a tag or a hash. New commits there belong to no branch until you create one.