From: Julia Evans Date: Wed, 10 Sep 2025 19:14:25 +0000 (+0000) Subject: doc: git-checkout: clarify `git checkout ` X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ab215e4a8d14624c274319883c4b74956b24b0f0;p=thirdparty%2Fgit.git doc: git-checkout: clarify `git checkout ` From user feedback: several users commented that "Local modifications to the files in the working tree are kept, so that they can be committed to the ." didn't seem accurate to them, since `git checkout ` will often fail. One user also thought that "... and by pointing HEAD at the branch" was something that _they_ had to do somehow ("How do I point HEAD at a branch?") rather than a description of what the `git checkout` operation is doing for them. Explain when `git checkout ` will fail and clarify that "pointing HEAD at the branch" is part of what the command does. 6 users commented that the "You could omit ..." section is extremely confusing. Explain this in a much more direct way. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index c4fa555f94..7d7505ad40 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -30,11 +30,11 @@ DESCRIPTION See ARGUMENT DISAMBIGUATION below for how Git decides which one to do. `git checkout []`:: - To prepare for working on __, switch to it by updating - the index and the files in the working tree, and by pointing - `HEAD` at the branch. Local modifications to the files in the - working tree are kept, so that they can be committed to the - __. + Switch to __. This sets the current branch to __ and + updates the files in your working directory. The checkout will fail + if there are uncommitted changes to any files where __ and + your current commit have different content. Uncommitted changes will + otherwise be kept. + If __ is not found but there does exist a tracking branch in exactly one remote (call it __) with a matching name and @@ -44,10 +44,8 @@ exactly one remote (call it __) with a matching name and $ git checkout -b --track / ------------ + -You could omit __, in which case the command degenerates to -"check out the current branch", which is a glorified no-op with -rather expensive side-effects to show only the tracking information, -if it exists, for the current branch. +Running `git checkout` without specifying a branch has no effect except +to print out the tracking information for the current branch. `git checkout (-b|-B) []`::