diff options
| author | Julia Evans <julia@jvns.ca> | 2025-09-10 19:14:25 +0000 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2025-09-10 14:32:04 -0700 |
| commit | ab215e4a8d14624c274319883c4b74956b24b0f0 (patch) | |
| tree | 23667c7edb99df49716e08feddeeea3f2c11c712 | |
| parent | ea03d5ae5cf7b256eca80634b424d3555da2cb8f (diff) | |
| download | git-ab215e4a8d14624c274319883c4b74956b24b0f0.tar.gz | |
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>
| -rw-r--r-- | Documentation/git-checkout.adoc | 16 |
1 files changed, 7 insertions, 9 deletions
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 [<branch>]`:: - To prepare for working on _<branch>_, 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 - _<branch>_. + Switch to _<branch>_. This sets the current branch to _<branch>_ and + updates the files in your working directory. The checkout will fail + if there are uncommitted changes to any files where _<branch>_ and + your current commit have different content. Uncommitted changes will + otherwise be kept. + If _<branch>_ is not found but there does exist a tracking branch in 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> ------------ + -You could omit _<branch>_, 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) <new-branch> [<start-point>]`:: |