@matheusbsbs / matheus-bagliano / commits / ab215e4a8d

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

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>

Julia Evans committed Sep 10, 2025 at 19:14 UTC ab215e4a8d14624c274319883c4b74956b24b0f0

1 file changed +7 -9

Documentation/git-checkout.adoc

+7 -9

@@ -30,11 +30,11 @@ DESCRIPTION

30 See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.

32 `git checkout [<branch>]`::

33 - To prepare for working on _<branch>_, switch to it by updating

34 - the index and the files in the working tree, and by pointing

35 - `HEAD` at the branch. Local modifications to the files in the

36 - working tree are kept, so that they can be committed to the

37 - _<branch>_.

33 + Switch to _<branch>_. This sets the current branch to _<branch>_ and

34 + updates the files in your working directory. The checkout will fail

35 + if there are uncommitted changes to any files where _<branch>_ and

36 + your current commit have different content. Uncommitted changes will

37 + otherwise be kept.

38 +

39 If _<branch>_ is not found but there does exist a tracking branch in

40 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

44 $ git checkout -b <branch> --track <remote>/<branch>

45 ------------

46 +

47 -You could omit _<branch>_, in which case the command degenerates to

48 -"check out the current branch", which is a glorified no-op with

49 -rather expensive side-effects to show only the tracking information,

50 -if it exists, for the current branch.

47 +Running `git checkout` without specifying a branch has no effect except

48 +to print out the tracking information for the current branch.

50 `git checkout (-b|-B) <new-branch> [<start-point>]`::