admin/git
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: git-checkout: clarify git checkout <branch>

Browse Source 
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 <branch>." didn't seem accurate to them, since
`git checkout <branch>` 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 <branch>` 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 <branch>..." section is
extremely confusing. Explain this in a much more direct way.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Julia Evans
2025-09-10 19:14:25 +00:00
committed by Junio C Hamano
parent ea03d5ae5c
commit ab215e4a8d
1 changed files with 7 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
Documentation/git-checkout.adoc
View File

@@ -30,11 +30,11 @@ DESCRIPTION
See ARGUMENT DISAMBIGUATION below for how Git decides which one to do. See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
`git checkout [<branch>]`:: `git checkout [<branch>]`::
To prepare for working on _<branch>_, switch to it by updating Switch to _<branch>_. This sets the current branch to _<branch>_ and
the index and the files in the working tree, and by pointing updates the files in your working directory. The checkout will fail
`HEAD` at the branch. Local modifications to the files in the if there are uncommitted changes to any files where _<branch>_ and
working tree are kept, so that they can be committed to the your current commit have different content. Uncommitted changes will
_<branch>_. otherwise be kept.
+ +
If _<branch>_ is not found but there does exist a tracking branch in If _<branch>_ is not found but there does exist a tracking branch in
exactly one remote (call it _<remote>_) with a matching name and exactly one remote (call it _<remote>_) with a matching name and
@@ -44,10 +44,8 @@ exactly one remote (call it _<remote>_) with a matching name and
$ git checkout -b <branch> --track <remote>/<branch> $ git checkout -b <branch> --track <remote>/<branch>
------------ ------------
+ +
You could omit _<branch>_, in which case the command degenerates to Running `git checkout` without specifying a branch has no effect except
"check out the current branch", which is a glorified no-op with to print out the tracking information for the current branch.
rather expensive side-effects to show only the tracking information,
if it exists, for the current branch.
`git checkout (-b|-B) <new-branch> [<start-point>]`:: `git checkout (-b|-B) <new-branch> [<start-point>]`::