Skip to content

favor git switch and git restore over git checkout - #2095

Draft
das-g wants to merge 5 commits into
progit:mainfrom
das-g:replace-checkout
Draft

das-g wants to merge 5 commits into
progit:mainfrom
das-g:replace-checkout

Conversation

@das-g

@das-g das-g commented Oct 11, 2026

Copy link
Copy Markdown

Changes

Context

Fixes #1524

das-g added 2 commits October 11, 2026 03:17
from tree-ish into working copy and/or staging area
rather than `git checkout --` for discarding changes in working directory.

Change made using:
	git sed '(use "git checkout -- <file>\.\.\." to discard changes in working directory)' '(use "git restore <file>..." to discard changes in working directory)'
but manually checked that all matches are about `git status` outputs
or about outputs of commands that also have this change, namely:
 * `git stash apply`
 * `git stash branch <new branch name>`
@das-g

das-g commented Oct 11, 2026

Copy link
Copy Markdown
Author

Remaining occurrences of git checkout as found by git grep 'git checkout':

C-git-commands.asc:==== git checkout
C-git-commands.asc:The `git checkout` command is used to switch branches and check content out into your working directory.
book/02-git-basics/sections/tagging.asc:If you want to view the versions of files a tag is pointing to, you can do a `git checkout` of that tag, although this puts your repository in "`detached HEAD`" state, which has some ill side effects:
book/02-git-basics/sections/tagging.asc:$ git checkout v2.0.0
book/02-git-basics/sections/tagging.asc:$ git checkout v2.0-beta-0.1
book/03-git-branching/sections/nutshell.asc:`git checkout` can be used instead:
book/03-git-branching/sections/nutshell.asc:- Switch to an existing branch: `git checkout testing-branch --`.
book/03-git-branching/sections/nutshell.asc:- Create a new branch and switch to it: `git checkout -b new-branch`.
book/07-git-tools/sections/reset.asc:Running `git checkout [branch]` is pretty similar to running `git reset --hard [branch]` in that it updates all three trees for you to look like `[branch]`, but there are two important differences.
book/07-git-tools/sections/reset.asc:If we instead run `git checkout master`, `develop` does not move, HEAD itself does.
book/07-git-tools/sections/reset.asc:.`git checkout` and `git reset`
book/07-git-tools/sections/reset.asc:image::images/reset-checkout.png[`git checkout` and `git reset`]
book/07-git-tools/sections/submodules.asc:In Git >= 2.13, it's also available for the older `git checkout` command.
book/08-customizing-git/sections/attributes.asc:$ git checkout -- test.txt
book/08-customizing-git/sections/attributes.asc:$ git checkout date_test.txt
book/08-customizing-git/sections/hooks.asc:After you run a successful `git checkout`, the `post-checkout` hook runs; you can use it to set up your working directory properly for your project environment.
book/10-git-internals/sections/refs.asc:If you run `git switch test` or `git checkout test`, Git updates the file to look like this:
book/10-git-internals/sections/refs.asc:You can `git checkout` (or `git switch --detach`) to one, but Git won't symbolically reference HEAD to one, so you'll never update it with a `commit` command.
book/A-git-in-other-environments/sections/bash.asc:…and Bash will auto-complete to `git checkout`.
  • 2 × in C-git-commands.asc: These have to stay, as they are about that very command.
  • 3 × in book/02-git-basics/sections/tagging.asc: Could probably be changed to git switch --detach, but that'd require changing the prose there, too.
  • 3 × in book/03-git-branching/sections/nutshell.asc: Intentionally introduced here, hopefully in the spirit of Rewrite recommend git switch instead of git checkout #1524's "Add [NOTE] explaining that git checkout is the "old way" of doing things."
  • 4 × in book/07-git-tools/sections/reset.asc: Unsure what to do about those. They're mostly about switching branches, but the prose around some occurrences there also seems to use the term for getting files into the working directory. Probably would need major rephrasing
  • 1 × in book/07-git-tools/sections/submodules.asc: Intentionally introduced / retained here. Not sure whether that's worth it, as the mentioned Git version is rather old now.
  • 2 × in book/08-customizing-git/sections/attributes.asc: I'm unsure whether we should change to git restore there (if the examples work with that, too, which I have yet to try). Any advice?
  • 1 × in book/08-customizing-git/sections/hooks.asc: I have yet to try, whether that works with switch and/or restore. (And then decide how to present it. Help welcome.)
  • 2 × in book/10-git-internals/sections/refs.asc: Similar situation (and semantics) to the occurrences in book/02-git-basics/sections/tagging.asc
  • 1 × in book/A-git-in-other-environments/sections/bash.asc: Should we change to a different example? What (except for checkout) would be an often-used yet long-ish Git subcommand?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rewrite recommend git switch instead of git checkout

1 participant