From 4b52ffd4970d8a33065cc8dcd915623acf716b5a Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Fri, 22 Aug 2025 10:36:09 -0400 Subject: [PATCH 1/7] doc: git-checkout: clarify intro sentence From user feedback: in the first paragraph, 5 users reported not understanding the terms "pathspec" and 1 user reported not understanding the term "HEAD". Of the users who said they didn't know what "pathspec" means, 3 said they couldn't understand what the paragraph was trying to communicate as a result. One user also commented that "If no pathspec was given..." makes `git checkout ` sounds like a special edge case, instead of being one of the most common ways to use this core Git command. It looks like the goal of this paragraph is to communicate that `git checkout` has two different modes: one where you switch branches and one where you just update your working directory files/index. So say that directly, and use more familiar language (including examples) to say it. Signed-off-by: Julia Evans --- Documentation/git-checkout.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 40e02cfd6562ae..9733c7345067a9 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -20,10 +20,12 @@ git checkout (-p|--patch) [] [--] [...] DESCRIPTION ----------- -Updates files in the working tree to match the version in the index -or the specified tree. If no pathspec was given, `git checkout` will -also update `HEAD` to set the specified branch as the current -branch. + +`git checkout` has two main modes: + +1. **Switch branches**, with `git checkout ` +2. **Restore a different version of a file**, for example with + `git checkout ` or `git checkout ` `git checkout []`:: To prepare for working on __, switch to it by updating From 08f0a5efab9d5dd57e1a49d00664e9453b6413f5 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 8 Sep 2025 17:14:30 -0400 Subject: [PATCH 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION There's no need to use the terms "pathspec" or "tree-ish" in the ARGUMENT DISAMBIGUATION section, which are terms that (from user feedback on this page) many users do not understand. "tree-ish" is actually not accurate here: `git checkout` in this case takes a commit-ish, not a tree-ish. So we can say "branch or commit" instead of "tree-ish" which is both more accurate and uses more familiar terms. And now that the intro to the man pages mentions that `git checkout` has "two main modes", it makes sense to refer to this disambiguation section to understand how Git decides which one to use when there's an overlap in syntax. Signed-off-by: Julia Evans --- Documentation/git-checkout.adoc | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 9733c7345067a9..d6f4044a09cd93 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -27,6 +27,8 @@ DESCRIPTION 2. **Restore a different version of a file**, for example with `git checkout ` or `git checkout ` +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 @@ -513,14 +515,18 @@ $ git log -g -2 HEAD ARGUMENT DISAMBIGUATION ----------------------- -When there is only one argument given and it is not `--` (e.g. `git -checkout abc`), and when the argument is both a valid __ -(e.g. a branch `abc` exists) and a valid __ (e.g. a file -or a directory whose name is "abc" exists), Git would usually ask -you to disambiguate. Because checking out a branch is so common an -operation, however, `git checkout abc` takes "abc" as a __ -in such a situation. Use `git checkout -- ` if you want -to checkout these paths out of the index. +When you run `git checkout `, Git tries to guess whether +`` is intended to be a branch, a commit, or a set of file(s), +and then either switches to that branch or commit, or restores the +specified files. + +If there's any ambiguity, Git will treat `` as a branch or +commit, but you can use the double dash `--` to force Git to treat the +parameter as a list of files and/or directories, like this: + +---------- +git checkout -- file.txt +---------- EXAMPLES -------- From 551e56dea6c5a6381f5f2e9fd81882f8104ef233 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Fri, 22 Aug 2025 10:45:08 -0400 Subject: [PATCH 3/7] 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 --- Documentation/git-checkout.adoc | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index d6f4044a09cd93..0db32b098e671d 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) []`:: From e636475cba2246ea98e461579a25b41b0ef4e99d Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Fri, 22 Aug 2025 10:56:35 -0400 Subject: [PATCH 4/7] doc: git-checkout: clarify `-b` and `-B` From user feedback: several users reported having trouble understanding the difference between `-b` and `-B` ("I think it's because my brain expects it to contrast with `-b`, but instead it starts off explaining how they're the same"). Also, in `-B`, 2 users can't tell what the branch is reset *to*. Simplify the sentence structure in the explanations of `-b` and `-B` and add a little extra information (what `` is, what the branch is reset to). Splitting up `-b` and `-B` into separate items helps simplify the sentence structure since there's less "In this case...". Replace the long "the branch is not reset/created unless "git checkout" is successful..." with just "will fail", since we should generally assume that Git will fail operations in a clean way and not leave operations half-finished, and that cases where it does not fail cleanly are the exceptions that the documentation should flag. Signed-off-by: Julia Evans --- Documentation/git-checkout.adoc | 44 ++++++++++++++------------------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 0db32b098e671d..7ae2ae9483031f 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -47,27 +47,21 @@ $ git checkout -b --track / 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) []`:: - - Specifying `-b` causes a new branch to be created as if - linkgit:git-branch[1] were called and then checked out. In - this case you can use the `--track` or `--no-track` options, - which will be passed to `git branch`. As a convenience, - `--track` without `-b` implies branch creation; see the - description of `--track` below. -+ -If `-B` is given, __ is created if it doesn't exist; otherwise, it -is reset. This is the transactional equivalent of -+ ------------- -$ git branch -f [] -$ git checkout ------------- +`git checkout -b []`:: + + Create a new branch named __, start it at __ + (defaults to the current commit), and check out the new branch. + You can use the `--track` or `--no-track` options to set the branch's + upstream tracking information. + -that is to say, the branch is not reset/created unless "git checkout" is -successful (e.g., when the branch is in use in another worktree, not -just the current branch stays the same, but the branch is not reset to -the start-point, either). +This will fail if there's an error checking out __, for +example if checking out the `` commit would overwrite your +uncommitted changes. + +`git checkout -B []`:: + + The same as `-b`, except that if the branch already exists it + resets `__` to the start point instead of failing. `git checkout --detach []`:: `git checkout [--detach] `:: @@ -157,16 +151,14 @@ of it"). see linkgit:git-branch[1] for details. `-B `:: - Creates the branch __, start it at __; - if it already exists, then reset it to __. And then - check the resulting branch out. This is equivalent to running - `git branch` with `-f` followed by `git checkout` of that branch; - see linkgit:git-branch[1] for details. + The same as `-b`, except that if the branch already exists it + resets `__` to the start point instead of failing. `-t`:: `--track[=(direct|inherit)]`:: When creating a new branch, set up "upstream" configuration. See - `--track` in linkgit:git-branch[1] for details. + `--track` in linkgit:git-branch[1] for details. As a convenience, + --track without -b implies branch creation. + If no `-b` option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of From e7d9641125c78924aa7eb8d0534d361d760ea534 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Fri, 22 Aug 2025 15:28:46 -0400 Subject: [PATCH 5/7] doc: git-checkout: deduplicate --detach explanation From user feedback: several users say they don't understand the use case for `--detach`. It's probably not realistic to explain the use case for detached HEAD state here, but we can improve the situation. Explain how `git checkout --detach` is different from `git checkout ` instead of copying over the description from `git checkout `, since `git checkout ` will be a familiar command to many readers. Signed-off-by: Julia Evans --- Documentation/git-checkout.adoc | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 7ae2ae9483031f..dd3cbb210ddb31 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -66,16 +66,9 @@ uncommitted changes. `git checkout --detach []`:: `git checkout [--detach] `:: - Prepare to work on top of __, by detaching `HEAD` at it - (see "DETACHED HEAD" section), and updating the index and the - files in the working tree. Local modifications to the files - in the working tree are kept, so that the resulting working - tree will be the state recorded in the commit plus the local - modifications. -+ -When the __ argument is a branch name, the `--detach` option can -be used to detach `HEAD` at the tip of the branch (`git checkout -` would check out that branch without detaching `HEAD`). + The same as `git checkout `, except that instead of pointing + `HEAD` at the branch, it points `HEAD` at the commit ID. + See the "DETACHED HEAD" section below for more. + Omitting __ detaches `HEAD` at the tip of the current branch. From 7b1e2f265baaa70483c8319793f167f7c91f3930 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 2 Sep 2025 17:22:01 -0400 Subject: [PATCH 6/7] doc: git-checkout: split up restoring files section From user feedback: one user mentioned that "When the (most often a commit) is not given" is confusing since it starts with a negative. Restructuring so that `git checkout main file.txt` and `git checkout file.txt` are separate items will help us simplify the sentence structure a lot. As a bonus, it appears that `-f` actually only applies to one of those forms, so we can include fewer options, and now the structure of the DESCRIPTION matches the SYNOPSIS. Signed-off-by: Julia Evans --- Documentation/git-checkout.adoc | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index dd3cbb210ddb31..1e19e13a0e1a4b 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [] git checkout [-q] [-f] [-m] --detach [] git checkout [-q] [-f] [-m] [--detach] git checkout [-q] [-f] [-m] [[-b|-B|--orphan] ] [] -git checkout [-f] [--] ... -git checkout [-f] --pathspec-from-file= [--pathspec-file-nul] +git checkout [--] ... +git checkout --pathspec-from-file= [--pathspec-file-nul] git checkout [-f|--ours|--theirs|-m|--conflict=