doc: git-checkout: clarify DESCRIPTION section

I got feedback from 21 Git users on the current version of the git checkout man page to figure out what's confusing about the current text. The goal here is to clarify the parts of the man page they found the most confusing, while accurately communicating the same information as before.

About 50% of the users who gave the feedback said they've been using Git for 5-10 years and 50% have been using Git for 10+ years.

Julia Evans (5):
doc: git-checkout: clarify intro
doc: git-checkout: clarify git checkout <branch>
doc: git-checkout: don't use "reset"
doc: git-checkout: deduplicate --detach explanation
doc: git-checkout: clarify restoring files section

 Documentation/git-checkout.adoc | 94 ++++++++++++++++-----------------
 1 file changed, 47 insertions(+), 47 deletions(-)

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1962

gitgitgadget

From: Julia Evans <[email protected]>

- Many users do not understand the terms "index" or "pathspec". Clarify in the intro by using an example, so that users can understand the basic idea without learning the full definition of "pathspec".
- Use the terminology "Switch" and "Restore" to mirror git switch and git restore
- Reference (and clarify) the ARGUMENT DISAMBIGUATION section

---
 Documentation/git-checkout.adoc | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

index 40e02cfd6562..ddda891c0ff7 100644
@@ -20,10 +20,14 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 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 <branch>`
+2. **Restore a different version of a file**, for example with `git
+   checkout <commit> <filename>` or `git checkout <filename>`
+
+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
+Here's a description of all of the modes:
 
 `git checkout [<branch>]`::
 	To prepare for working on _<branch>_, switch to it by updating

@@ -511,14 +515,17 @@ $ 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 _<tree-ish>_
-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (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 _<tree-ish>_
-in such a situation.  Use `git checkout -- <pathspec>` if you want
-to checkout these paths out of the index.
+When you run `git checkout <something>`, Git tries to guess whether
+`<something>` is intended to be a branch, a commit, or a set of file(s),
+and then switches branches, switches commits, or restores the files.
+
+If there's a conflict, you can use the double dash `--` to distinguish
+between branches and files:
+
+* `git checkout <branch> --` will force Git to treat the parameter as a
+  branch name or commit
+* `git checkout -- <pathspec>` will force Git to treat the parameter as
+  a set of file(s)
 
 EXAMPLES
 --------

gitgitgadget

Avoid bullet points here. End your sentence with a full stop.

I am not sure if we want/need this line, though.

Another thing I noticed but forgot to mention.

Does everybody really understand what it means to "switch branches" without further explanation?

Also "<branch>" -> "(<branch> | <commit>)", perhaps, as working on the unnamed branch (aka detached HEAD) behaves very much the same way as working on a named branch.

Thanks for the comments!

Ok, will change.

I like that, will change.

Will remove.

Will change.

I like that, will change.

My thought was that we explain what "switch branches" in immediately afterwards in more depth. ("git checkout [<branch>]:
Switch to <branch>. This will update the files in the working tree...)

I feel mixed about this one.

One way to look at it is that git checkout has two modes: one where you update HEAD and one where you don't. I think from a "git internals" point of view this makes a lot of sense, but my impression is that most "regular" Git users think of "switching to detached HEAD state" as being a very different operation from "switching branches", not as basically equivalent except for one small detail.

Another way to look at it is that the "git checkout <branch> | <commit>"'s main role is to switch branches, and that "git checkout <commit>" is sort of an edge case and that we can leave its explanation to a few lines later on. That's the stance I've taken here, but I'm open to hearing other points of view.

Thanks, will fix. Though I don't think it's accurate that Git will treat <something> as a <tree-ish> in this context, since git checkout <tree> is not valid. Will find a different wording. (I get "fatal: Cannot switch branch to a non-commit")

True. "git checkout foo" is disambiguated by seeing if 'foo' can be interpreted as a commit-ish, and if not, if there is a path 'foo' in the working tree. Otherwise we'd get an ambiguity error. A commit-ish that is nameed by giving a branch name and other commit-ish then trigger a bit different codepaths (the former results in checking out a branch, the latter detached HEAD).

Interesting. A docs bug! :) AFAICT it comes from 19e5656345 (checkout.txt: document a common case that ignores ambiguation rules, 2016-09-07). I was a novice then and don't know the behavior from that period, nor did I bother to find out whether "tree-ish" matched the behavior at the time and has changed or was simply wrong from the start. Good catch.

Yep, makes sense.

D. Ben Knoble

Yup. And on the other side, unifying "prepare to extend the history of a branch" and "prepare to create a new history starting at a commit" (aka detached HEAD) into one is equally good.

But I am wondering what is the most common perception of the second mode. I've always thought that the action was to "grab things out of the index or out of a tree-ish and overwrite the working tree files", and it takes me an extra effort to read, think, understand and finally realize that "update working tree files to match either the index or a tree-ish" is equivalent to it.

Anyway, thanks for a review.

I'd say your first version matches my concept of that mode, but it's heavy on the operation (do this, do that) vs the declaration (desired end state). Of course the second version still has the verb "update," but we emphasize less "how" to update and more the results of said update?

:)

D. Ben Knoble

From: Julia Evans <[email protected]>

- "To prepare for working on _<branch>_..." is confusing to some users:
it makes it sound like these are steps that the user has to do, not steps that Git itself will do. Reword it.
- Use "changes" instead of "modifications" (which Git normally does)
- Mention that git checkout will fail if there's a merge conflict
- The current explanation of You could omit <branch>... is confusing to users (what are the "expensive side effects"? what's a better way of getting the same info?). Be more direct and mention that git status is likely a better option.

---
 Documentation/git-checkout.adoc | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

index ddda891c0ff7..a3edb95973a2 100644
@@ -30,11 +30,12 @@ See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
 Here's a description of all of the modes:
 
 `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 will update the files in the working tree,
+	point `HEAD` at the branch, and update the index. Local changes to
+	the files in the working tree are kept, so that they can be committed
+	to the _<branch>_. If the local changes conflict with the changes on
+	_<branch>_, no changes will be made and the checkout operation will
+	fail.
 +
 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 +45,9 @@ 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 will output the
+tracking information, if it exists, for the current branch, but it's
+slower than getting the same information from `git status`.
 
 `git checkout (-b|-B) <new-branch> [<start-point>]`::
 

gitgitgadget

I'm not sure what you mean here: "switch to <branch>" is as far as I can tell the most widely used term to refer to this operation, in other Git resources, in Git's own man pages, and in the error output of the git checkout command itself:
("Please commit your changes or stash them before you switch branches.") Which readers do you think would be confused by it?

That makes sense. I'll work on a better way to phrase this.

Ah, I thought git status was faster because I benchmarked it it on one of my repositories and got these results [1].

Now that I see that that's not what "expensive side-effects" was intended to mean, will change to something much simpler, like "Running git checkout without specifying a branch outputs the tracking information for the current branch. It has no other effect. "

- Julia

[1]

$ hyperfine 'git status'
Benchmark 1: git status
  Time (mean ± σ):       6.6 ms ±   1.2 ms    [User: 3.2 ms, System: 5.1 ms]
$ hyperfine 'git checkout'
  Time (mean ± σ):      29.5 ms ±   1.9 ms    [User: 12.6 ms, System: 14.8 ms]

My assumption was that you are making this a manual to teach what "switch to branch" means to folks who do not know, hence my question.

Exactly those who are given that message and want to understand what it means.

Thanks for bringing this up, I think the question of audience is very important.

My main goal right now is actually to make the Git documentation understandable for existing Git users who have already been using Git for at least a year or two. From the feedback I'm getting so far, the man pages are very hard to understand for those users, and even for many users who have been using Git for 10+ years.

The reason that I've been thinking of "existing Git users" and not "newcomers to Git" as the primary audience are:

a) existing users are likely to be the main users of the man pages (after all, beginners don't _stay_ beginners for very long!)
b) my impression is that the Git documentation always aims to explain everything in a way that's "completely technically accurate" (which I think makes sense!), and I I think it's often impossible to give a completely technically accurate explanation in a way that a newcomer to Git can completely understand.

That said, of course I'm not against making things accessible to newcomers :) My usual approach in technical writing is to think of "a user who's been using this software for a couple of years already" as the _primary_ audience, but also to try to keep it as accessible to a newcomer as possible.

I think I can figure out how to say something about what it means to "Switch branches" that a newcomer to Git might understand, though of course it'll need to be quite different than the current explanation (existing users generally don't understand what "HEAD" or the "index" are, so a newcomer likely won't understand those terms either).

From: Julia Evans <[email protected]>

Many Git users don't know what the term "reset" means. Resolve this by:

- Expanding it into its definition, in one case
- Giving a simpler but still accurate explanation ("the branch will not be created or modified"), in the other case

---
 Documentation/git-checkout.adoc | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

index a3edb95973a2..dc9607d9ea39 100644
@@ -58,18 +58,17 @@ slower than getting the same information from `git status`.
 	`--track` without `-b` implies branch creation; see the
 	description of `--track` below.
 +
-If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it
-is reset. This is the transactional equivalent of
+If `-B` is given, _<new-branch>_ is created if it doesn't exist;
+otherwise `<new-branch>` is forced to point at the commit. This is the
+transactional equivalent of
 +
 ------------
 $ git branch -f <branch> [<start-point>]
 $ git checkout <branch>
 ------------
 +
-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).
+that is, the branch will not be created or modified unless
+`git checkout` is successful.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

gitgitgadget

From: Julia Evans <[email protected]>

Right now the explanation of --detach repeats a lot of the content in the description of git checkout <branch>: we can communicate the same thing by saying "This is the same as git checkout <branch>, except..."

---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

index dc9607d9ea39..b343d292b30b 100644
@@ -73,16 +73,9 @@ that is, the branch will not be created or modified unless
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::
 
-	Prepare to work on top of _<commit>_, 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 _<commit>_ argument is a branch name, the `--detach` option can
-be used to detach `HEAD` at the tip of the branch (`git checkout
-<branch>` would check out that branch without detaching `HEAD`).
+	The same as `git checkout <branch>`, 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 _<branch>_ detaches `HEAD` at the tip of the current branch.
 

gitgitgadget

From: Julia Evans <[email protected]>

- Use the term "Restore" to mirror git restore
- Many Git users do not know what a "tree-ish" is. Clarify by using an example of each case, and by saying "commit or tree" in the text instead of "<tree-ish>"
- Many Git users do not know what the "index" is. Instead say "stage the file's contents" where appropriate, since Git often uses "stage" as a verb to mean the same thing as "add to the index" and it's a more familiar term.

---
 Documentation/git-checkout.adoc | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

index b343d292b30b..9f2b86ac5368 100644
@@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite the contents of the files that match the pathspec.
-	When the _<tree-ish>_ (most often a commit) is not given,
-	overwrite working tree with the contents in the index.
-	When the _<tree-ish>_ is given, overwrite both the index and
-	the working tree with the contents at the _<tree-ish>_.
+	Restore another version of the file(s) that match the pathspec.
 +
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries.  The contents from a
+If you specify a commit or tree to restore from (for example `git
+checkout main file.txt`), this will restore the version of the file(s)
+from that commit or tree. This overwrites the file in the working
+directory and stages the file's contents.
++
+If you do not specify where to restore from (for example `git checkout
+file.txt`), this will replace the file(s) with the version from the index.
+If you check out a file with an unresolved merge
+conflict, the checkout operation will fail and no changes will be made.
+Using `-f` will ignore the merge conflict.  The contents from a
 specific side of the merge can be checked out of the index by
 using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
 file can be discarded to re-create the original conflicted merge result.
-
 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
 	This is similar to the previous mode, but lets you use the
 	interactive interface to show the "diff" output and choose which

gitgitgadget

Thanks, this section of the man page is not easy and this is very useful feedback. Will work on improving all of these points.

Wishful thinking (see glossary comments): I wish we could teach them about "tree-ish"s here rather than stop using useful shorthands altogether. Of course, then we have to wonder where we can use the shorthand and where we must do the "spell it out (give an abbreviation)" dance. Hm.

D. Ben Knoble

What I find hard about documenting cases like this is identifying the use case for providing so much flexibility
("you can pass any tree, not just a commit!), since personally I've never passed anything to git checkout other than a commit.

I've been trying to think of examples of cases where it's useful to pass a tree instead of a commit. I can see that it's possible to run something like this

$ git checkout HEAD:Documentation/ git-commit.adoc

to restore file.txt into a different directory than it was originally. This seems cool in theory but it's hard for me to see why it's useful, which makes it hard for me to document. What I would tell a friend is "<tree-ish> 99% of the time just means "commit or something which resolves to a commit, but Git has made it more general for a reason I don't understand", but of course that's not the right thing to say in the Git documentation :)

It probably is handy when you want to cross a rename boundary to backport a new thing into an old history (or vice versa). Something like

    $ git checkout v1.0.0
    $ git checkout v1.7.1:builtin cat-file.c

perhaps.

You are describing commit-ish (which allows an annotated or signed tag that points at a commit).

This makes sense, and: I think some of how I learned more Git was to read the manuals, look up things I wasn't familiar with, and then play with them :) So in a sense my wishful thinking is about sign-posting "here's this other nook to explore if you're curious" (knowing that ~70% or or more simply won't be).

I would say that it's more general in part because it can be: the data model allows it without any extra effort (not a jab at the programming, which was probably not easy!). But I'm in a tangent now and the latest version is probably fine by me. I just don't want to lose the signposts for explorers.

D. Ben Knoble

* Remove the numbered list from the beginning
* Split up the git checkout [<tree-ish>] <pathspec> section into two sections, one for git checkout <tree-ish> <pathspec> and one for git checkout <pathspec>, to match the SYNOPSIS and because it seems like a clearer approach. Also completely rewrite them to be more accurate and more clear. Use "Replace" instead of "Restore".
* Describe what it means to "switch branches" in a way that's more accessible to newcomers, and make "If the local changes conflict with the changes on ..." more accurate
* Improve the ARGUMENT DISAMBIGUATION section

Julia Evans (5):
doc: git-checkout: clarify intro
doc: git-checkout: clarify git checkout <branch>
doc: git-checkout: don't use "reset"
doc: git-checkout: deduplicate --detach explanation
doc: git-checkout: clarify restoring files section

 Documentation/git-checkout.adoc | 114 +++++++++++++++++---------------
 1 file changed, 60 insertions(+), 54 deletions(-)

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1962

Range-diff vs v1:

1: a6125a0128 ! 1: 48e7f23029 doc: git-checkout: clarify intro
@@ Documentation/git-checkout.adoc: git checkout (-p|--patch) [<tree-ish>] [--] [<p
-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 <branch>
-+2. **Restore a different version of a file**, for example with `git
-+ checkout <commit> <filename> or git checkout <filename>`
++git checkout has two main modes: it can
++**switch branches**, for example with git checkout <branch>, and ++**restore files from a different version**, for example with
++git checkout <commit> <filename> or git checkout <filename>
+
+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
-+Here's a description of all of the modes:

git checkout [<branch>]::
To prepare for working on _<branch>_, switch to it by updating
@@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
+<something> is intended to be a branch, a commit, or a set of file(s), +and then switches branches, switches commits, or restores the files. +
-+If there's a conflict, you can use the double dash -- to distinguish -+between branches and files:
++If there's any ambiguity, Git will treat <something> 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 <branch> -- will force Git to treat the parameter as a -+ branch name or commit
-+* git checkout -- <pathspec> will force Git to treat the parameter as -+ a set of file(s)
++----------
++git checkout -- file.txt
++----------

EXAMPLES
--------
2: b8873c4529 ! 2: 23a738981a doc: git-checkout: clarify git checkout <branch>
@@ Commit message

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
- Here's a description of all of the modes:
+@@ Documentation/git-checkout.adoc: 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
@@ Documentation/git-checkout.adoc: See ARGUMENT DISAMBIGUATION below for how Git d
- 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 will update the files in the working tree,
-+ point HEAD at the branch, and update the index. Local changes to
++ Switch to _<branch>_. This sets the current branch to <branch> and
++ updates the files in your working directory. Local changes to
+ the files in the working tree are kept, so that they can be committed
-+ to the _<branch>_. If the local changes conflict with the changes on
-+ _<branch>_, no changes will be made and the checkout operation will
-+ fail.
++ to the _<branch>_. If the local changes can't be cleanly merged into
++ the _<branch>_, no changes will be made and the checkout operation will fail.
+
If _<branch>_ is not found but there does exist a tracking branch in exactly one remote (call it _<remote>_) with a matching name and
@@ Documentation/git-checkout.adoc: exactly one remote (call it _<remote>_) with a
-"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 will output the -+tracking information, if it exists, for the current branch, but it's -+slower than getting the same information from git status. ++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>]::

3: 0a3915264b ! 3: 360051d2a6 doc: git-checkout: don't use "reset"
@@ Commit message

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: slower than getting the same information from git status. +@@ Documentation/git-checkout.adoc: to print out the tracking information for the current branch.
--track without -b implies branch creation; see the
description of --track below.
+

 4:  2221a6bfb5 = 4:  6f3e485c33 doc: git-checkout: deduplicate --detach explanation
 5:  b641874627 ! 5:  9c0119e70d doc: git-checkout: clarify restoring files section

@@ Metadata
## Commit message ##
doc: git-checkout: clarify restoring files section

- - Use the term "Restore" to mirror git restore
+ - Split up the forms git checkout file.txt and
+ git checkout main file.txt to match what's given in the SYNOPSIS
+ - Remove -f from the SYNOPSIS for the second form, since according to
+ this man page it is not relevant in that context
- Many Git users do not know what a "tree-ish" is. Clarify by using an example of each case, and by saying "commit or tree" in the text instead of "<tree-ish>"
@@ Commit message
file's contents" where appropriate, since Git often uses "stage" as a verb to mean the same thing as "add to the index" and it's a more familiar term.
+ - Use "Discard unstaged changes" instead of "checking out paths from
+ the index" where relevant

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches HEAD at the tip of the current branch.
- git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...::
- git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]::
+@@ Documentation/git-checkout.adoc: git checkout [-q] [-f] [-m] [<branch>]
+ git checkout [-q] [-f] [-m] --detach [<branch>]
+ git checkout [-q] [-f] [-m] [--detach] <commit>
+ git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
+-git checkout [-f] <tree-ish> [--] <pathspec>...
+-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
++git checkout <tree-ish> [--] <pathspec>...
++git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+ git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
+ git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
+ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
+@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modified unless
+ +
+ Omitting _<branch>_ detaches HEAD at the tip of the current branch.
+
+-git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...::
+-git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]::
++git checkout <tree-ish> [--] <pathspec>...::
++git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]::

- Overwrite the contents of the files that match the pathspec.
- When the _<tree-ish>_ (most often a commit) is not given,
- overwrite working tree with the contents in the index.
- When the _<tree-ish>_ is given, overwrite both the index and
- the working tree with the contents at the _<tree-ish>_.
-+ Restore another version of the file(s) that match the pathspec.
++ Replace the specified files and/or directories with the version from
++ the given commit or tree.
+
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using -f will ignore these unmerged entries. The contents from a
-+If you specify a commit or tree to restore from (for example `git
-+checkout main file.txt`), this will restore the version of the file(s)
-+from that commit or tree. This overwrites the file in the working
+-specific side of the merge can be checked out of the index by
+-using --ours or --theirs. With -m, changes made to the working tree
+-file can be discarded to re-create the original conflicted merge result.
++For example, git checkout main file.txt will restore the version
++of file.txt from main. This overwrites the file in the working
+directory and stages the file's contents.
+
++git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...::
++git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]::
++
++ Replace the specified files and/or directories with the latest
++ committed or staged version.
+++
++This overwrites the file(s) you specify with either the staged version
++or the version from the current commit if there is no staged version.
++For example, if you've been editing file.txt and you want to discard
++your changes to it, you can run git checkout file.txt to replace it
++with the latest committed version.
++
-+If you do not specify where to restore from (for example `git checkout
-+file.txt`), this will replace the file(s) with the version from the index.
-+If you check out a file with an unresolved merge
-+conflict, the checkout operation will fail and no changes will be made.
-+Using -f will ignore the merge conflict. The contents from a
- specific side of the merge can be checked out of the index by
- using --ours or --theirs. With -m, changes made to the working tree
- file can be discarded to re-create the original conflicted merge result.
--
++This will fail if the file has a merge conflict and you haven't yet run
++git add file.txt (or something equivalent) to mark it as resolved.
++You can use -f to ignore the unmerged files instead of failing, use
++--ours or --theirs to replace them with the version from a specific
++side of the merge, or use -m to replace them with the original
++conflicted merge result.
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
- This is similar to the previous mode, but lets you use the
+- This is similar to the previous mode, but lets you use the
++ This is similar to the previous two modes, but lets you use the
interactive interface to show the "diff" output and choose which
+ hunks to use in the result. See below for the description of
+ --patch option.

gitgitgadget

From: Julia Evans <[email protected]>

- Many users do not understand the terms "index" or "pathspec". Clarify in the intro by using an example, so that users can understand the basic idea without learning the full definition of "pathspec".
- Use the terminology "Switch" and "Restore" to mirror git switch and git restore
- Reference (and clarify) the ARGUMENT DISAMBIGUATION section

---
 Documentation/git-checkout.adoc | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

index 40e02cfd65..c86941ad53 100644
@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 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: it can
+**switch branches**, for example with `git checkout <branch>`, and
+**restore files from a different version**, for example with
+`git checkout <commit> <filename>` or `git checkout <filename>`
+
+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

@@ -511,14 +513,17 @@ $ 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 _<tree-ish>_
-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (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 _<tree-ish>_
-in such a situation.  Use `git checkout -- <pathspec>` if you want
-to checkout these paths out of the index.
+When you run `git checkout <something>`, Git tries to guess whether
+`<something>` is intended to be a branch, a commit, or a set of file(s),
+and then switches branches, switches commits, or restores the files.
+
+If there's any ambiguity, Git will treat `<something>` 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
 --------

gitgitgadget

You seem to have forgotten to update the proposed log message ...

https://lore.kernel.org/git/[email protected]/

... to avoid making it just an enumeration of "these random things were done in this patch" (and instead tell a coherent story).

The same comment applies to many of your patches in this and other topics (I won't repeat for brevity, though, on my review on them).

Thanks for the reminder, will work on that. I just realized today that I can use lazygit to make it much faster to edit my log messages :)

Agreed that "switches commits" is weird, will use "switches to".

From: Julia Evans <[email protected]>

- "To prepare for working on _<branch>_..." is confusing to some users:
it makes it sound like these are steps that the user has to do, not steps that Git itself will do. Reword it.
- Use "changes" instead of "modifications" (which Git normally does)
- Mention that git checkout will fail if there's a merge conflict
- The current explanation of You could omit <branch>... is confusing to users (what are the "expensive side effects"? what's a better way of getting the same info?). Be more direct and mention that git status is likely a better option.

---
 Documentation/git-checkout.adoc | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

index c86941ad53..4de3ac6680 100644
@@ -28,11 +28,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. Local changes to
+	the files in the working tree are kept, so that they can be committed
+	to the _<branch>_. If the local changes can't be cleanly merged into
+	the _<branch>_, no changes will be made and the checkout operation will fail.
 +
 If _<branch>_ is not found but there does exist a tracking branch in
 exactly one remote (call it _<remote>_) with a matching name and

@@ -42,10 +42,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>]`::
 

gitgitgadget

Thanks, I wasn't sure based on the existing text what "modifications are kept" meant exactly, and I've always been slightly hazy about this behaviour. Will fix.

From: Julia Evans <[email protected]>

Many Git users don't know what the term "reset" means. Resolve this by:

- Expanding it into its definition, in one case
- Giving a simpler but still accurate explanation ("the branch will not be created or modified"), in the other case

---
 Documentation/git-checkout.adoc | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

index 4de3ac6680..e4614674f0 100644
@@ -54,18 +54,17 @@ to print out the tracking information for the current branch.
 	`--track` without `-b` implies branch creation; see the
 	description of `--track` below.
 +
-If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it
-is reset. This is the transactional equivalent of
+If `-B` is given, _<new-branch>_ is created if it doesn't exist;
+otherwise `<new-branch>` is forced to point at the commit. This is the
+transactional equivalent of
 +
 ------------
 $ git branch -f <branch> [<start-point>]
 $ git checkout <branch>
 ------------
 +
-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).
+that is, the branch will not be created or modified unless
+`git checkout` is successful.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

gitgitgadget

Even though it is the name of one of the most often used commands? And yet a separate step in this series made the claim that everybody knows what "switch" means because it is the name of another command?

I think the source of the problem is not that they "don't know what the term means" at all. Isn't the real problem that the use of the verb in the original sentence you are correcting in this patch is vague and does not say what the branch is reset *to*?

The description says "-B <branch>" resets the branch if it exists, but does not say what it resets to. Rephrase to clarify that it is made to point at the specified commit.

or something?

By the way this kind of use of bulleted list in a proposed log message I do not mind all that much. What I reacted to was a list without the introducing text (in the case of this patch, "resolve this by doing these things:").

I agree this is a reasonable approach here, will try that.

I'm surprised to hear you say that "reset" is one of the most often used Git commands -- what I frequently hear from Git users is that they use git reset only in "emergencies" where something has gone wrong and that they're afraid of using it.

I'm curious about whether there are any datasets about which Git commands are the most frequently used, or if it would be worth me trying to build one.

"Transactional equivalent" was bothering me too and I like the idea of rewriting it, will give it a shot.

For the list of commands that have been historically considered "common":

    $ git -h

is meant to serve a good guide. We may want to cull/update some entries (like, "backfill" which should not be more prominent than "maintenance", for example), but I think it is not far off or way too stale (for one thing, it no longer lists checkout but gives two separate commands, restore and switch, which are no longer marked as experimental).

Thanks.

From: Julia Evans <[email protected]>

Right now the explanation of --detach repeats a lot of the content in the description of git checkout <branch>: we can communicate the same thing by saying "This is the same as git checkout <branch>, except..."

---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

index e4614674f0..4d522a5f75 100644
@@ -69,16 +69,9 @@ that is, the branch will not be created or modified unless
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::
 
-	Prepare to work on top of _<commit>_, 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 _<commit>_ argument is a branch name, the `--detach` option can
-be used to detach `HEAD` at the tip of the branch (`git checkout
-<branch>` would check out that branch without detaching `HEAD`).
+	The same as `git checkout <branch>`, 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 _<branch>_ detaches `HEAD` at the tip of the current branch.
 

gitgitgadget

From: Julia Evans <[email protected]>

- Split up the forms git checkout file.txt and
git checkout main file.txt to match what's given in the SYNOPSIS
- Remove -f from the SYNOPSIS for the second form, since according to this man page it is not relevant in that context
- Many Git users do not know what a "tree-ish" is. Clarify by using an example of each case, and by saying "commit or tree" in the text instead of "<tree-ish>"
- Many Git users do not know what the "index" is. Instead say "stage the file's contents" where appropriate, since Git often uses "stage" as a verb to mean the same thing as "add to the index" and it's a more familiar term.
- Use "Discard unstaged changes" instead of "checking out paths from the index" where relevant

---
 Documentation/git-checkout.adoc | 45 ++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 17 deletions(-)

index 4d522a5f75..dababe452a 100644
@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]
 git checkout [-q] [-f] [-m] --detach [<branch>]
 git checkout [-q] [-f] [-m] [--detach] <commit>
 git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-git checkout [-f] <tree-ish> [--] <pathspec>...
-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout <tree-ish> [--] <pathspec>...
+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]

@@ -75,25 +75,36 @@ that is, the branch will not be created or modified unless
 +
 Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+`git checkout <tree-ish> [--] <pathspec>...`::
+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite the contents of the files that match the pathspec.
-	When the _<tree-ish>_ (most often a commit) is not given,
-	overwrite working tree with the contents in the index.
-	When the _<tree-ish>_ is given, overwrite both the index and
-	the working tree with the contents at the _<tree-ish>_.
+	Replace the specified files and/or directories with the version from
+	the given commit or tree.
 +
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries.  The contents from a
-specific side of the merge can be checked out of the index by
-using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
-file can be discarded to re-create the original conflicted merge result.
+For example, `git checkout main file.txt` will restore the version
+of `file.txt` from `main`. This overwrites the file in the working
+directory and stages the file's contents.
 
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...`::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+
+	Replace the specified files and/or directories with the latest
+	committed or staged version.
++
+This overwrites the file(s) you specify with either the staged version
+or the version from the current commit if there is no staged version.
+For example, if you've been editing `file.txt` and you want to discard
+your changes to it, you can run `git checkout file.txt` to replace it
+with the latest committed version.
++
+This will fail if the file has a merge conflict and you haven't yet run
+`git add file.txt` (or something equivalent) to mark it as resolved.
+You can use `-f` to ignore the unmerged files instead of failing, use
+`--ours` or `--theirs` to replace them with the version from a specific
+side of the merge, or use `-m` to replace them with the original
+conflicted merge result.
 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
-	This is similar to the previous mode, but lets you use the
+	This is similar to the previous two modes, but lets you use the
 	interactive interface to show the "diff" output and choose which
 	hunks to use in the result.  See below for the description of
 	`--patch` option.

gitgitgadget

* Improve the storytelling in the commit messages
* Take a different approach to the git checkout -b description (keep reset in -B, but simplify the description of -B a lot)
* Make the description of git checkout [<branch>] more accurate.
* Try a different approach to git checkout file.txt ("Discard any unstaged changes...")

Julia Evans (6):
doc: git-checkout: clarify intro
doc: git-checkout: clarify git checkout <branch>
doc: git-checkout: clarify -b and -B
doc: git-checkout: deduplicate --detach explanation
doc: git-checkout: split up restoring files section
doc: git-checkout: clarify restoring files section

 Documentation/git-checkout.adoc | 147 ++++++++++++++++----------------
 1 file changed, 72 insertions(+), 75 deletions(-)

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1962

Range-diff vs v2:

1: 48e7f23029 ! 1: 1975384dd0 doc: git-checkout: clarify intro
@@ Metadata
## Commit message ##
doc: git-checkout: clarify intro

- - Many users do not understand the terms "index" or "pathspec". Clarify
- in the intro by using an example, so that users can understand the
- basic idea without learning the full definition of "pathspec".
- - Use the terminology "Switch" and "Restore" to mirror git switch
- and git restore
- - Reference (and clarify) the ARGUMENT DISAMBIGUATION section
+ - Reduce use of jargon ("index", "pathspec", "tree") by using an
+ example, and by mirroring the "switch" and "restore" language from the
+ first line of the man page.
+ - Reference and clarify the ARGUMENT DISAMBIGUATION section, as well
+ as fixing a small error (in "git checkout abc, abc is a commit,
+ not a _<tree-ish>_)

@@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
-to checkout these paths out of the index.
+When you run git checkout <something>, Git tries to guess whether +<something> is intended to be a branch, a commit, or a set of file(s),
-+and then switches branches, switches commits, or restores the files. ++and then either switches to that branch or commit or restores the ++specified files.
+
+If there's any ambiguity, Git will treat <something> as a branch or +commit, but you can use the double dash -- to force Git to treat the
2: 23a738981a ! 2: 940cd17e7e doc: git-checkout: clarify git checkout <branch>
@@ Metadata
## Commit message ##
doc: git-checkout: clarify git checkout <branch>

- - "To prepare for working on _<branch>_..." is confusing to some users:
- it makes it sound like these are steps that the user has to do, not
- steps that Git itself will do. Reword it.
- - Use "changes" instead of "modifications" (which Git normally does)
- - Mention that git checkout will fail if there's a merge conflict
- - The current explanation of You could omit <branch>... is confusing
- to users (what are the "expensive side effects"? what's a better way
- of getting the same info?). Be more direct and mention that `git
- status` is likely a better option.
+ - Reduce use of jargon ("index", "HEAD")
+ - Clarify that only identical files will be left unchanged, and that
+ git checkout will fail rather than overwrite an unchanged file
+ - Explain what git checkout with no arguments does in a more direct
+ way

@@ Documentation/git-checkout.adoc: DESCRIPTION
- 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. Local changes to
-+ the files in the working tree are kept, so that they can be committed
-+ to the _<branch>_. If the local changes can't be cleanly merged into
-+ the _<branch>_, no changes will be made and the checkout operation will fail.
++ Switch to _<branch>_. This sets the current branch to _<branch>_ and
++ updates the files in your working directory. Files which are
++ identical in _<branch>_ and your current commit are left unchanged
++ so that you can keep your uncommitted changes to those files.
++ This will not overwrite uncommitted changes to a file: instead it
++ will fail without making any changes.
+
If _<branch>_ is not found but there does exist a tracking branch in exactly one remote (call it _<remote>_) with a matching name and
3: 360051d2a6 ! 3: 043fec7e66 doc: git-checkout: don't use "reset"
@@ Metadata
Author: Julia Evans <[email protected]>

## Commit message ##
- doc: git-checkout: don't use "reset"
+ doc: git-checkout: clarify -b and -B

- Many Git users don't know what the term "reset" means. Resolve this by:
-
- - Expanding it into its definition, in one case
- - Giving a simpler but still accurate explanation ("the branch will not
- be created or modified"), in the other case
+ - Remove some unnecessary detail about --track (users can refer
+ to the OPTIONS section instead)
+ - Explain what the start point defaults to
+ - Describe -B much more tersely as "the same as -b, except ..",
+ since potential users of -B are almost certainly already very
+ familiar with -b. Move all of the other contents of -B to -b,
+ updating the example so that it's appropriate for -b

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: to print out the tracking information for the current branch.
- --track without -b implies branch creation; see the
- description of --track below.
- +
+@@ Documentation/git-checkout.adoc: $ git checkout -b <branch> --track <remote>/<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>]::
+-
+- 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, _<new-branch>_ is created if it doesn't exist; otherwise, it -is reset. This is the transactional equivalent of
-+If -B is given, _<new-branch>_ is created if it doesn't exist;
-+otherwise <new-branch> is forced to point at the commit. This is the -+transactional equivalent of
- +
- ------------
- $ git branch -f <branch> [<start-point>]
- $ git checkout <branch>
- ------------
+-+
+-------------
+-$ git branch -f <branch> [<start-point>]
+-$ git checkout <branch>
+-------------
++git checkout -b <new-branch> [<start-point>]::
++
++ Create a new branch named _<new-branch>_, start it at _<start-point>_
++ (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).
-+that is, the branch will not be created or modified unless
-+git checkout is successful.
++This fails without making any changes if there's an error checking out ++_<new-branch>_, for example if checking out the <start-point>
++commit would overwrite your uncommitted changes.
++
++git checkout -B <branch> [<start-point>]::
++
++ The same as -b, except that if the branch already exists it
++ resets _<branch>_ to the start point instead of creating it.

git checkout --detach [<branch>]::
git checkout [--detach] <commit>::
+@@ Documentation/git-checkout.adoc: of it").
+ see linkgit:git-branch[1] for details.
+
+ -B <new-branch>::
+- Creates the branch _<new-branch>_, start it at _<start-point>_;
+- if it already exists, then reset it to _<start-point>_. 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 _<branch>_ to the start point instead of creating it.
+
+ -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
4: 6f3e485c33 ! 4: 6ce31b6278 doc: git-checkout: deduplicate --detach explanation
@@ Metadata
## Commit message ##
doc: git-checkout: deduplicate --detach explanation

- Right now the explanation of --detach repeats a lot of the content in
- the description of git checkout <branch>: we can communicate the same
- thing by saying "This is the same as git checkout <branch>, except..."
+ Say that git checkout --detach is almost the same as git checkout
+ instead of duplicating the content of the git checkout section, since
+ many users will already be familiar with what git checkout does.

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modified unless +@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.
git checkout --detach [<branch>]::
git checkout [--detach] <commit>::

5: 9c0119e70d ! 5: 24793f9a45 doc: git-checkout: clarify restoring files section
@@ Metadata
Author: Julia Evans <[email protected]>

## Commit message ##
- doc: git-checkout: clarify restoring files section
+ doc: git-checkout: split up restoring files section

- - Split up the forms git checkout file.txt and
- git checkout main file.txt to match what's given in the SYNOPSIS
- - Remove -f from the SYNOPSIS for the second form, since according to
- this man page it is not relevant in that context
- - Many Git users do not know what a "tree-ish" is. Clarify by using an
- example of each case, and by saying "commit or tree" in the text
- instead of "<tree-ish>"
- - Many Git users do not know what the "index" is. Instead say "stage the
- file's contents" where appropriate, since Git often uses "stage" as a
- verb to mean the same thing as "add to the index" and it's a more
- familiar term.
- - Use "Discard unstaged changes" instead of "checking out paths from
- the index" where relevant
+ Will make it easier to explain the two versions clearly in the following
+ commit. As a bonus, now the structure of the DESCRIPTION
+ matches the SYNOPSIS.
+
+ Also remove -f from git checkout <tree-ish> <pathspec> since it's
+ not relevant in that context.

@@ Documentation/git-checkout.adoc: git checkout [-q] [-f] [-m] [<branch>]
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
-@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modified unless +@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.
+
Omitting _<branch>_ detaches HEAD at the tip of the current branch.

@@ Documentation/git-checkout.adoc: that is, the branch will not be created or modi
- overwrite working tree with the contents in the index.
- When the _<tree-ish>_ is given, overwrite both the index and
- the working tree with the contents at the _<tree-ish>_.
-+ Replace the specified files and/or directories with the version from
-+ the given commit or tree.
- +
--The index may contain unmerged entries because of a previous failed merge.
--By default, if you try to check out such an entry from the index, the
--checkout operation will fail and nothing will be checked out.
--Using -f will ignore these unmerged entries. The contents from a
--specific side of the merge can be checked out of the index by
--using --ours or --theirs. With -m, changes made to the working tree
--file can be discarded to re-create the original conflicted merge result.
-+For example, git checkout main file.txt will restore the version
-+of file.txt from main. This overwrites the file in the working
-+directory and stages the file's contents.
-
-+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] <pathspec>...::
++ Overwrite both the index and the working tree with the
++ contents at the _<tree-ish>_ for the files that match the pathspec.
++
++git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...::
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]::
+
-+ Replace the specified files and/or directories with the latest
-+ committed or staged version.
-++
-+This overwrites the file(s) you specify with either the staged version
-+or the version from the current commit if there is no staged version.
-+For example, if you've been editing file.txt and you want to discard
-+your changes to it, you can run git checkout file.txt to replace it
-+with the latest committed version.
-++
-+This will fail if the file has a merge conflict and you haven't yet run
-+git add file.txt (or something equivalent) to mark it as resolved.
-+You can use -f to ignore the unmerged files instead of failing, use
-+--ours or --theirs to replace them with the version from a specific
-+side of the merge, or use -m to replace them with the original
-+conflicted merge result.
++ Overwrite working tree with the contents in the index for the files
++ that match the pathspec.
+ +
+ The index may contain unmerged entries because of a previous failed merge.
+ By default, if you try to check out such an entry from the index, the
+@@ Documentation/git-checkout.adoc: using --ours or --theirs. With -m, changes made to the working tree
+ file can be discarded to re-create the original conflicted merge result.
+
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
- This is similar to the previous mode, but lets you use the
+ This is similar to the previous two modes, but lets you use the
-: ---------- > 6: 90fe48cfe3 doc: git-checkout: clarify restoring files section

gitgitgadget

From: Julia Evans <[email protected]>

- Reduce use of jargon ("index", "pathspec", "tree") by using an example, and by mirroring the "switch" and "restore" language from the first line of the man page.
- Reference and clarify the ARGUMENT DISAMBIGUATION section, as well as fixing a small error (in "git checkout abc, abc is a commit, not a _<tree-ish>_)

---
 Documentation/git-checkout.adoc | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

index 40e02cfd65..218d3dd13d 100644
@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 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: it can
+**switch branches**, for example with `git checkout <branch>`, and
+**restore files from a different version**, for example with
+`git checkout <commit> <filename>` or `git checkout <filename>`
+
+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

@@ -511,14 +513,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 _<tree-ish>_
-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (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 _<tree-ish>_
-in such a situation.  Use `git checkout -- <pathspec>` if you want
-to checkout these paths out of the index.
+When you run `git checkout <something>`, Git tries to guess whether
+`<something>` 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 `<something>` 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
 --------

gitgitgadget

From: Julia Evans <[email protected]>

- Reduce use of jargon ("index", "HEAD")
- Clarify that only identical files will be left unchanged, and that git checkout will fail rather than overwrite an unchanged file
- Explain what git checkout with no arguments does in a more direct way

---
 Documentation/git-checkout.adoc | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

index 218d3dd13d..50923ff118 100644
@@ -28,11 +28,12 @@ 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. Files which are
+	identical in _<branch>_ and your current commit are left unchanged
+	so that you can keep your uncommitted changes to those files.
+	This will not overwrite uncommitted changes to a file: instead it
+	will fail without making any changes.
 +
 If _<branch>_ is not found but there does exist a tracking branch in
 exactly one remote (call it _<remote>_) with a matching name and

@@ -42,10 +43,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>]`::
 

gitgitgadget

From: Julia Evans <[email protected]>

- Remove some unnecessary detail about --track (users can refer to the OPTIONS section instead)
- Explain what the start point defaults to
- Describe -B much more tersely as "the same as -b, except ..", since potential users of -B are almost certainly already very familiar with -b. Move all of the other contents of -B to -b, updating the example so that it's appropriate for -b

---
 Documentation/git-checkout.adoc | 44 ++++++++++++++-------------------
 1 file changed, 18 insertions(+), 26 deletions(-)

index 50923ff118..a2777fb5b0 100644
@@ -46,27 +46,21 @@ $ git checkout -b <branch> --track <remote>/<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>]`::
-
-	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, _<new-branch>_ is created if it doesn't exist; otherwise, it
-is reset. This is the transactional equivalent of
-+
-------------
-$ git branch -f <branch> [<start-point>]
-$ git checkout <branch>
-------------
+`git checkout -b <new-branch> [<start-point>]`::
+
+	Create a new branch named _<new-branch>_, start it at _<start-point>_
+	(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 fails without making any changes if there's an error checking out
+_<new-branch>_, for example if checking out the `<start-point>`
+commit would overwrite your uncommitted changes.
+
+`git checkout -B <branch> [<start-point>]`::
+
+	The same as `-b`, except that if the branch already exists it
+	resets `_<branch>_` to the start point instead of creating it.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

@@ -156,16 +150,14 @@ of it").
 	see linkgit:git-branch[1] for details.
 
 `-B <new-branch>`::
-	Creates the branch _<new-branch>_, start it at _<start-point>_;
-	if it already exists, then reset it to _<start-point>_. 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 `_<branch>_` to the start point instead of creating it.
 
 `-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

gitgitgadget

From: Julia Evans <[email protected]>

Say that git checkout --detach is almost the same as git checkout instead of duplicating the content of the git checkout section, since many users will already be familiar with what git checkout does.

---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

index a2777fb5b0..d35fd32ce8 100644
@@ -65,16 +65,9 @@ commit would overwrite your uncommitted changes.
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::
 
-	Prepare to work on top of _<commit>_, 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 _<commit>_ argument is a branch name, the `--detach` option can
-be used to detach `HEAD` at the tip of the branch (`git checkout
-<branch>` would check out that branch without detaching `HEAD`).
+	The same as `git checkout <branch>`, 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 _<branch>_ detaches `HEAD` at the tip of the current branch.
 

gitgitgadget

From: Julia Evans <[email protected]>

Will make it easier to explain the two versions clearly in the following commit. As a bonus, now the structure of the DESCRIPTION matches the SYNOPSIS.

Also remove -f from git checkout <tree-ish> <pathspec> since it's not relevant in that context.

---
 Documentation/git-checkout.adoc | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

index d35fd32ce8..b361ff011a 100644
@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]
 git checkout [-q] [-f] [-m] --detach [<branch>]
 git checkout [-q] [-f] [-m] [--detach] <commit>
 git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-git checkout [-f] <tree-ish> [--] <pathspec>...
-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout <tree-ish> [--] <pathspec>...
+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]

@@ -71,14 +71,17 @@ commit would overwrite your uncommitted changes.
 +
 Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+`git checkout <tree-ish> [--] <pathspec>...`::
+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite the contents of the files that match the pathspec.
-	When the _<tree-ish>_ (most often a commit) is not given,
-	overwrite working tree with the contents in the index.
-	When the _<tree-ish>_ is given, overwrite both the index and
-	the working tree with the contents at the _<tree-ish>_.
+	Overwrite both the index and the working tree with the
+	contents at the _<tree-ish>_ for the files that match the pathspec.
+
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+
+	Overwrite working tree with the contents in the index for the files
+	that match the pathspec.
 +
 The index may contain unmerged entries because of a previous failed merge.
 By default, if you try to check out such an entry from the index, the

@@ -89,7 +92,7 @@ using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
 file can be discarded to re-create the original conflicted merge result.
 
 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
-	This is similar to the previous mode, but lets you use the
+	This is similar to the previous two modes, but lets you use the
 	interactive interface to show the "diff" output and choose which
 	hunks to use in the result.  See below for the description of
 	`--patch` option.

gitgitgadget

From: Julia Evans <[email protected]>

- Reword to avoid jargon ("tree-ish", "index") where possible. Use "commit or tree" and "stage" (as a verb) instead where appropriate
- Add examples
- Use a simpler sentence structure to describe options for handling unmerged entries: "use -f to.., use --ours to..., or use -m to.."

---
 Documentation/git-checkout.adoc | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

index b361ff011a..ae19565f4f 100644
@@ -74,23 +74,27 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 `git checkout <tree-ish> [--] <pathspec>...`::
 `git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite both the index and the working tree with the
-	contents at the _<tree-ish>_ for the files that match the pathspec.
+	Replace the specified files and/or directories with the version from
+	the given commit or tree and stage the files' contents.
++
+For example, `git checkout main file.txt` will replace `file.txt`
+with the version from `main`.
 
 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite working tree with the contents in the index for the files
-	that match the pathspec.
+	Discard any unstaged changes to the specified files and/or directories.
+	This works by copying the file from the index to your working directory.
+	For example, `git checkout file.txt` will replace `file.txt` with either
+	the staged version of `file.txt` (if there is one) or the version from the
+	current commit.
 +
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries.  The contents from a
-specific side of the merge can be checked out of the index by
-using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
-file can be discarded to re-create the original conflicted merge result.
-
+This will fail if the file has a merge conflict and you haven't yet run
+`git add file.txt` (or something equivalent) to mark it as resolved.
+You can use `-f` to ignore the unmerged files instead of failing, use
+`--ours` or `--theirs` to replace them with the version from a specific
+side of the merge, or use `-m` to replace them with the original
+conflicted merge result.
 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
 	This is similar to the previous two modes, but lets you use the
 	interactive interface to show the "diff" output and choose which

gitgitgadget

Not just you repeat having bulleted list in your proposed log messages (which I already said something about, remember?), now you have them in your cover letter, too? You must be so fond of bulletted list X-<.

Much better.

Here "left unchanged" is technically correct, but somehow it gives me a (n incorrect) connotation that they are not modified since HEAD, which is not what you wanted to say at all. I recall that we once explained this not as "left unchanged", but as "changes follow you", and I found the explanation easier to absorb.

I cannot come up with a good way to remove duplicates in the following desciption, but what we want the reader to understand are twofold:

* For paths that are not identical between HEAD and the _<branch>_ you are switching to, you MUST NOT have a local change. After you switch to _<branch>_, these paths in the working tree match that of the _<branch_>. This is to avoid losing your local changes.

* For paths that are identical between HEAD and the _<branch>_ you are switching to, you may have local modifications, and they follow you to the switched-to _<branch>_.

OK. Do people understand "making a(ny) changes" refers to creation of the new branch, I have to wonder, but if so, the above is much much nicer than the original text.

This fails without doing anything and without creating a new branch, if checking out the <start-point> has to overwrite your uncommitted changes.

might be slightly better? I dunno.

It's true, I do really love bulleted lists. I see now that I misunderstood your previous comment about this: I'll avoid using bulleted lists in commit messages and emails in the future.

I like the idea of "changes follow you". Will work on making this clearer.

Makes sense. I'll be more explicit.

I got feedback from 22 existing Git users on the existing git checkout man page, using this tool: https://text-feedback.wizardzines.com/git-checkout.
From a short survey they filled out, about 90% of the users who gave the feedback have 5+ years of experience using Git.

This series goes through the DESCRIPTION section from beginning to end, addressing points that users found confusing in each variant of git checkout. The goal is to clarify while communicating the same information.

Changes in v2:

* Remove the numbered list from the beginning, from Junio's review
* Describe what it means to "switch branches" in a way that's hopefully more accessible to newcomers, from Junio's review
* Improve the ARGUMENT DISAMBIGUATION section, from Junio and Ben's reviews ("conflict" => "ambiguity", explain correctly what the default is)
* The explanation of git checkout [<tree-ish>] <pathspec> had a lot of issues, from Junio's review. Resolve this by splitting up the git checkout [] section into two sections. Use "Replace" instead of "Restore".

Changes in v3:

* Fix incorrect description of when git checkout <branch>, from Junio's review
* Take a different approach to the git checkout -b description (keep reset in -B, but simplify the description of -B a lot to remove the "transactional equivalent.." paragraph), from Junio's review
* Say "switch to the commit" instead of "switches commits", from Junio's review
* Try a different approach to git checkout file.txt ("Discard any unstaged changes...")

Changes in v4:

* Rewrite all the commit messages to try to take a more Problem / Solution approach, from Junio's review and thanks to help from @nasamuffin in Discord. Also change the cover letter format to match the style in
https://lore.kernel.org/git/CAOLa=ZStgwBN0fMK3YxoqeR+1i772f621supva3Kvr7YPq4g8g@mail.gmail.com/T/#m8c99a3144cbdfb445e04f8f83a79364bfe8d797d
, which hopefully matches the norms of this mailing list better.
* Try a different approach to the "left unchanged...", from Junio's review
* Bring back "index" (with a few hints about what the word might mean), from Junio's review.
* Bring back the numbered list at the beginning from v1, since I think I misunderstood a comment about lists, and that the original was clearer
* Fix an issue I noticed in -B ("instead of failing", not "instead of creating it")
* Add a comma after branch or commit, to try to make it clear what "either" refers to in that sentence
* Replace "will fail without making any changes" throughout with just "will fail". I think the default assumption is that Git will fail operations in a clean way, and that cases where it does not fail cleanly are the exceptions that the documentation should flag.

Julia Evans (7):
doc: git-checkout: clarify intro sentence
doc: git-checkout: clarify ARGUMENT DISAMBIGUATION
doc: git-checkout: clarify git checkout <branch>
doc: git-checkout: clarify -b and -B
doc: git-checkout: deduplicate --detach explanation
doc: git-checkout: split up restoring files section
doc: git-checkout: clarify restoring files section

 Documentation/git-checkout.adoc | 151 ++++++++++++++++----------------
 1 file changed, 76 insertions(+), 75 deletions(-)

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1962

Range-diff vs v3:

 -:  ---------- > 1:  4b52ffd497 doc: git-checkout: clarify intro sentence
 1:  1975384dd0 ! 2:  08f0a5efab doc: git-checkout: clarify intro

@@ Metadata
Author: Julia Evans <[email protected]>

## Commit message ##
- doc: git-checkout: clarify intro
+ doc: git-checkout: clarify ARGUMENT DISAMBIGUATION

- - Reduce use of jargon ("index", "pathspec", "tree") by using an
- example, and by mirroring the "switch" and "restore" language from the
- first line of the man page.
- - Reference and clarify the ARGUMENT DISAMBIGUATION section, as well
- as fixing a small error (in "git checkout abc, abc is a commit,
- not a _<tree-ish>_)
+ 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.

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...] +@@ Documentation/git-checkout.adoc: DESCRIPTION
+ 2. **Restore a different version of a file**, for example with
+ git checkout <commit> <filename> or git checkout <filename>

- 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: it can
-+**switch branches**, for example with git checkout <branch>, and -+**restore files from a different version**, for example with -+git checkout <commit> <filename> or git checkout <filename> -+
+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
@@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
ARGUMENT DISAMBIGUATION
-----------------------
@@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
-to checkout these paths out of the index.
+When you run git checkout <something>, Git tries to guess whether +<something> 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 ++and then either switches to that branch or commit, or restores the
+specified files.
+
+If there's any ambiguity, Git will treat <something> as a branch or
2: 940cd17e7e ! 3: 551e56dea6 doc: git-checkout: clarify git checkout <branch>
@@ Metadata
## Commit message ##
doc: git-checkout: clarify git checkout <branch>

- - Reduce use of jargon ("index", "HEAD")
- - Clarify that only identical files will be left unchanged, and that
- git checkout will fail rather than overwrite an unchanged file
- - Explain what git checkout with no arguments does in a more direct
- way
+ 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.

@@ Documentation/git-checkout.adoc: DESCRIPTION
- 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. Files which are
-+ identical in _<branch>_ and your current commit are left unchanged
-+ so that you can keep your uncommitted changes to those files.
-+ This will not overwrite uncommitted changes to a file: instead it
-+ will fail without making any changes.
++ 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
3: 043fec7e66 ! 4: e636475cba doc: git-checkout: clarify -b and -B
@@ Metadata
## Commit message ##
doc: git-checkout: clarify -b and -B

- - Remove some unnecessary detail about --track (users can refer
- to the OPTIONS section instead)
- - Explain what the start point defaults to
- - Describe -B much more tersely as "the same as -b, except ..",
- since potential users of -B are almost certainly already very
- familiar with -b. Move all of the other contents of -B to -b,
- updating the example so that it's appropriate for -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 <start-point> 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.

@@ Documentation/git-checkout.adoc: $ git checkout -b <branch> --track <remote>/<br
-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 fails without making any changes if there's an error checking out -+_<new-branch>_, for example if checking out the <start-point> -+commit would overwrite your uncommitted changes.
++This will fail if there's an error checking out _<new-branch>_, for ++example if checking out the <start-point> commit would overwrite your ++uncommitted changes.
+
+git checkout -B <branch> [<start-point>]::
+
+ The same as -b, except that if the branch already exists it
-+ resets _<branch>_ to the start point instead of creating it.
++ resets _<branch>_ to the start point instead of failing.

git checkout --detach [<branch>]::
git checkout [--detach] <commit>::
@@ Documentation/git-checkout.adoc: of it").
- 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 _<branch>_ to the start point instead of creating it.
++ resets _<branch>_ to the start point instead of failing.

-t::
--track[=(direct|inherit)]::
4: 6ce31b6278 ! 5: e7d9641125 doc: git-checkout: deduplicate --detach explanation
@@ Metadata
## Commit message ##
doc: git-checkout: deduplicate --detach explanation

- Say that git checkout --detach is almost the same as git checkout
- instead of duplicating the content of the git checkout section, since
- many users will already be familiar with what git checkout does.
+ 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 <branch> instead of copying over the description from
+ git checkout <branch>, since git checkout <branch> will be a
+ familiar command to many readers.

## Documentation/git-checkout.adoc ##
-@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes. +@@ Documentation/git-checkout.adoc: uncommitted changes.
git checkout --detach [<branch>]::
git checkout [--detach] <commit>::

5: 24793f9a45 ! 6: 7b1e2f265b doc: git-checkout: split up restoring files section
@@ Metadata
## Commit message ##
doc: git-checkout: split up restoring files section

- Will make it easier to explain the two versions clearly in the following
- commit. As a bonus, now the structure of the DESCRIPTION
- matches the SYNOPSIS.
+ From user feedback: one user mentioned that "When the <tree-ish> (most
+ often a commit) is not given" is confusing since it starts with a
+ negative.

- Also remove -f from git checkout <tree-ish> <pathspec> since it's
- not relevant in that context.
+ 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.

@@ Documentation/git-checkout.adoc: git checkout [-q] [-f] [-m] [<branch>]
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
-@@ Documentation/git-checkout.adoc: commit would overwrite your uncommitted changes.
+@@ Documentation/git-checkout.adoc: uncommitted changes.
+
Omitting _<branch>_ detaches HEAD at the tip of the current branch.

6: 90fe48cfe3 ! 7: db603b1e5f doc: git-checkout: clarify restoring files section
@@ Metadata
## Commit message ##
doc: git-checkout: clarify restoring files section

- - Reword to avoid jargon ("tree-ish", "index") where possible.
- Use "commit or tree" and "stage" (as a verb) instead where appropriate
- - Add examples
- - Use a simpler sentence structure to describe options for handling
- unmerged entries: "use -f to.., use --ours to..., or use -m to.."
+ From user feedback on this section: 3 users don't know what "tree-ish"
+ means and 3 users don't know what "pathspec" means. One user also says
+ that the section is very confusing and that they don't understand what
+ the "index" is.
+
+ From conversations on Mastodon, several users said that their impression
+ is that "the index" means the same thing as "HEAD". It would be good to
+ give those users (and other users who do not know what "index" means) a
+ hint as to its meaning.
+
+ Make this section more accessible to users who don't know what the terms
+ "pathspec", "tree-ish", and "index" mean by using more familiar language,
+ adding examples, and using simpler sentence structures.

@@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches HEAD at the tip
- Overwrite both the index and the working tree with the
- contents at the _<tree-ish>_ for the files that match the pathspec.
+ Replace the specified files and/or directories with the version from
-+ the given commit or tree and stage the files' contents.
++ the given commit or tree and add them to the index
++ (also known as "staging area").
++
+For example, git checkout main file.txt will replace file.txt +with the version from main.
@@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches HEAD at the tip

- Overwrite working tree with the contents in the index for the files
- that match the pathspec.
-+ Discard any unstaged changes to the specified files and/or directories.
-+ This works by copying the file from the index to your working directory.
-+ For example, git checkout file.txt will replace file.txt with either
-+ the staged version of file.txt (if there is one) or the version from the
-+ current commit.
++ Replace the specified files and/or directories with the version from
++ the index.
+++
++For example, if you check out a commit, edit file.txt, and then ++decide those changes were a mistake, git checkout file.txt will ++discard any unstaged changes to file.txt.
+
-The index may contain unmerged entries because of a previous failed merge. -By default, if you try to check out such an entry from the index, the
@@ Documentation/git-checkout.adoc: Omitting _<branch>_ detaches HEAD at the tip
-specific side of the merge can be checked out of the index by -using --ours or --theirs. With -m, changes made to the working tree -file can be discarded to re-create the original conflicted merge result.
--
+This will fail if the file has a merge conflict and you haven't yet run +git add file.txt (or something equivalent) to mark it as resolved. +You can use -f to ignore the unmerged files instead of failing, use +--ours or --theirs to replace them with the version from a specific +side of the merge, or use -m to replace them with the original +conflicted merge result.
+
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
This is similar to the previous two modes, but lets you use the
- interactive interface to show the "diff" output and choose which

gitgitgadget

From: Julia Evans <[email protected]>

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 <branch> 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.

---
 Documentation/git-checkout.adoc | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

index 40e02cfd65..9733c73450 100644
@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 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 <branch>`
+2. **Restore a different version of a file**, for example with
+   `git checkout <commit> <filename>` or `git checkout <filename>`
 
 `git checkout [<branch>]`::
 	To prepare for working on _<branch>_, switch to it by updating

gitgitgadget

From: Julia Evans <[email protected]>

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.

---
 Documentation/git-checkout.adoc | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

index 9733c73450..d6f4044a09 100644
@@ -27,6 +27,8 @@ DESCRIPTION
 2. **Restore a different version of a file**, for example with
    `git checkout <commit> <filename>` or `git checkout <filename>`
 
+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

@@ -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 _<tree-ish>_
-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (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 _<tree-ish>_
-in such a situation.  Use `git checkout -- <pathspec>` if you want
-to checkout these paths out of the index.
+When you run `git checkout <something>`, Git tries to guess whether
+`<something>` 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 `<something>` 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
 --------

gitgitgadget

From: Julia Evans <[email protected]>

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.

---
 Documentation/git-checkout.adoc | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

index d6f4044a09..0db32b098e 100644
@@ -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>]`::
 

gitgitgadget

From: Julia Evans <[email protected]>

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 <start-point> 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.

---
 Documentation/git-checkout.adoc | 44 ++++++++++++++-------------------
 1 file changed, 18 insertions(+), 26 deletions(-)

index 0db32b098e..7ae2ae9483 100644
@@ -47,27 +47,21 @@ $ git checkout -b <branch> --track <remote>/<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>]`::
-
-	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, _<new-branch>_ is created if it doesn't exist; otherwise, it
-is reset. This is the transactional equivalent of
-+
-------------
-$ git branch -f <branch> [<start-point>]
-$ git checkout <branch>
-------------
+`git checkout -b <new-branch> [<start-point>]`::
+
+	Create a new branch named _<new-branch>_, start it at _<start-point>_
+	(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 _<new-branch>_, for
+example if checking out the `<start-point>` commit would overwrite your
+uncommitted changes.
+
+`git checkout -B <branch> [<start-point>]`::
+
+	The same as `-b`, except that if the branch already exists it
+	resets `_<branch>_` to the start point instead of failing.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

@@ -157,16 +151,14 @@ of it").
 	see linkgit:git-branch[1] for details.
 
 `-B <new-branch>`::
-	Creates the branch _<new-branch>_, start it at _<start-point>_;
-	if it already exists, then reset it to _<start-point>_. 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 `_<branch>_` 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

gitgitgadget

From: Kristoffer Haugsbakk <[email protected]>

The placeholder markup is underscore (_), not backtick (`) as well.

The inline-verbatim markup (backticks) handle interior formatting. This means in this case that it applies HTML <code> to the underscores and <em> to the placeholder.

That is the effect, anyway; we can see from the rest of 042d6f34 (doc:
git-checkout: clarify -b and -B, 2025-09-10) that this was probably an unintended mix-up.

---

Notes (series):
Since this has landed in master now.

 Documentation/git-checkout.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 431185ca0ba..6f281b298ef 100644
@@ -61,7 +61,7 @@ uncommitted changes.
 `git checkout -B <branch> [<start-point>]`::
 
 	The same as `-b`, except that if the branch already exists it
-	resets `_<branch>_` to the start point instead of failing.
+	resets _<branch>_ to the start point instead of failing.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

@@ -155,7 +155,7 @@ of it").
 
 `-B <new-branch>`::
 	The same as `-b`, except that if the branch already exists it
-	resets `_<branch>_` to the start point instead of failing.
+	resets _<branch>_ to the start point instead of failing.
 
 `-t`::
 `--track[=(direct|inherit)]`::

base-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea

2.51.0.327.gddebdc8c038

From: Kristoffer Haugsbakk <[email protected]>

The placeholder markup is underscore (_), not backtick (`) as well.

The inline-verbatim markup (backticks) handle interior formatting. This means in this case that it applies HTML <code> to the underscores and <em> to the placeholder.

That is the effect, anyway; we can see from the rest of 042d6f34 (doc:
git-checkout: clarify -b and -B, 2025-09-10) that this was probably an unintended mix-up.

---

Notes (series):
Since this has landed in master now.

 Documentation/git-checkout.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 431185ca0ba..6f281b298ef 100644
@@ -61,7 +61,7 @@ uncommitted changes.
 `git checkout -B <branch> [<start-point>]`::
 
 	The same as `-b`, except that if the branch already exists it
-	resets `_<branch>_` to the start point instead of failing.
+	resets _<branch>_ to the start point instead of failing.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

@@ -155,7 +155,7 @@ of it").
 
 `-B <new-branch>`::
 	The same as `-b`, except that if the branch already exists it
-	resets `_<branch>_` to the start point instead of failing.
+	resets _<branch>_ to the start point instead of failing.
 
 `-t`::
 `--track[=(direct|inherit)]`::

base-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea

2.51.1.498.g8f0801f1c10

Thanks, apologies for missing this at the time.

From: Kristoffer Haugsbakk <[email protected]>

The placeholder markup is underscore (_), not backtick (`) as well.

The inline-verbatim markup (backticks) handle interior formatting. This means in this case that it applies HTML <code> to the underscores and <em> to the placeholder.

That is the effect, anyway; we can see from the rest of 042d6f34 (doc:
git-checkout: clarify -b and -B, 2025-09-10) that this was probably an unintended mix-up.

---

Notes (series):
v2:
Add Ack. I also considered removing “probably” from “mix-up” but left it alone as a point-in-time note. The msg + ack makes it clear.

v1:
Since this has landed in master now.

 Documentation/git-checkout.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 431185ca0ba..6f281b298ef 100644
@@ -61,7 +61,7 @@ uncommitted changes.
 `git checkout -B <branch> [<start-point>]`::
 
 	The same as `-b`, except that if the branch already exists it
-	resets `_<branch>_` to the start point instead of failing.
+	resets _<branch>_ to the start point instead of failing.
 
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::

@@ -155,7 +155,7 @@ of it").
 
 `-B <new-branch>`::
 	The same as `-b`, except that if the branch already exists it
-	resets `_<branch>_` to the start point instead of failing.
+	resets _<branch>_ to the start point instead of failing.
 
 `-t`::
 `--track[=(direct|inherit)]`::

Range-diff against v1:
1: 54bc6875cc5 ! 1: cb38c701537 doc: git-checkout: fix placeholder markup
@@ Commit message
git-checkout: clarify -b and -B, 2025-09-10) that this was probably an unintended mix-up.

+ Acked-by: Julia Evans <[email protected]>

## Notes (series) ##
+ v2:
+ Add Ack. I also considered removing “probably” from “mix-up” but
+ left it alone as a point-in-time note. The msg + ack makes it clear.
+
+ v1:
Since this has landed in master now.

## Documentation/git-checkout.adoc ##

base-commit: 83a9405e59e9cdfb587b19c50f0c040f346dd4ea

2.51.1.498.g8f0801f1c10

From: Julia Evans <[email protected]>

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 <branch> instead of copying over the description from git checkout <branch>, since git checkout <branch> will be a familiar command to many readers.

---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

index 7ae2ae9483..dd3cbb210d 100644
@@ -66,16 +66,9 @@ uncommitted changes.
 `git checkout --detach [<branch>]`::
 `git checkout [--detach] <commit>`::
 
-	Prepare to work on top of _<commit>_, 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 _<commit>_ argument is a branch name, the `--detach` option can
-be used to detach `HEAD` at the tip of the branch (`git checkout
-<branch>` would check out that branch without detaching `HEAD`).
+	The same as `git checkout <branch>`, 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 _<branch>_ detaches `HEAD` at the tip of the current branch.
 

gitgitgadget

From: Julia Evans <[email protected]>

From user feedback: one user mentioned that "When the <tree-ish> (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.

---
 Documentation/git-checkout.adoc | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

index dd3cbb210d..1e19e13a0e 100644
@@ -12,8 +12,8 @@ git checkout [-q] [-f] [-m] [<branch>]
 git checkout [-q] [-f] [-m] --detach [<branch>]
 git checkout [-q] [-f] [-m] [--detach] <commit>
 git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-git checkout [-f] <tree-ish> [--] <pathspec>...
-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout <tree-ish> [--] <pathspec>...
+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]

@@ -72,14 +72,17 @@ uncommitted changes.
 +
 Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+`git checkout <tree-ish> [--] <pathspec>...`::
+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite the contents of the files that match the pathspec.
-	When the _<tree-ish>_ (most often a commit) is not given,
-	overwrite working tree with the contents in the index.
-	When the _<tree-ish>_ is given, overwrite both the index and
-	the working tree with the contents at the _<tree-ish>_.
+	Overwrite both the index and the working tree with the
+	contents at the _<tree-ish>_ for the files that match the pathspec.
+
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
+
+	Overwrite working tree with the contents in the index for the files
+	that match the pathspec.
 +
 The index may contain unmerged entries because of a previous failed merge.
 By default, if you try to check out such an entry from the index, the

@@ -90,7 +93,7 @@ using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
 file can be discarded to re-create the original conflicted merge result.
 
 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
-	This is similar to the previous mode, but lets you use the
+	This is similar to the previous two modes, but lets you use the
 	interactive interface to show the "diff" output and choose which
 	hunks to use in the result.  See below for the description of
 	`--patch` option.

gitgitgadget

From: Julia Evans <[email protected]>

From user feedback on this section: 3 users don't know what "tree-ish" means and 3 users don't know what "pathspec" means. One user also says that the section is very confusing and that they don't understand what the "index" is.

From conversations on Mastodon, several users said that their impression is that "the index" means the same thing as "HEAD". It would be good to give those users (and other users who do not know what "index" means) a hint as to its meaning.

Make this section more accessible to users who don't know what the terms "pathspec", "tree-ish", and "index" mean by using more familiar language, adding examples, and using simpler sentence structures.

---
 Documentation/git-checkout.adoc | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

index 1e19e13a0e..d8e8bcf549 100644
@@ -75,22 +75,29 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
 `git checkout <tree-ish> [--] <pathspec>...`::
 `git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite both the index and the working tree with the
-	contents at the _<tree-ish>_ for the files that match the pathspec.
+	Replace the specified files and/or directories with the version from
+	the given commit or tree and add them to the index
+	(also known as "staging area").
++
+For example, `git checkout main file.txt` will replace `file.txt`
+with the version from `main`.
 
 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite working tree with the contents in the index for the files
-	that match the pathspec.
+	Replace the specified files and/or directories with the version from
+	the index.
++
+For example, if you check out a commit, edit `file.txt`, and then
+decide those changes were a mistake, `git checkout file.txt` will
+discard any unstaged changes to `file.txt`.
 +
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries.  The contents from a
-specific side of the merge can be checked out of the index by
-using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
-file can be discarded to re-create the original conflicted merge result.
+This will fail if the file has a merge conflict and you haven't yet run
+`git add file.txt` (or something equivalent) to mark it as resolved.
+You can use `-f` to ignore the unmerged files instead of failing, use
+`--ours` or `--theirs` to replace them with the version from a specific
+side of the merge, or use `-m` to replace them with the original
+conflicted merge result.
 
 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
 	This is similar to the previous two modes, but lets you use the

gitgitgadget

This was pleasant reading to me. Not sure how it felt for you to write? Or if the convention was just not spelled out enough to get you where you wanted to be? :)

Range-diff looks good to me!

Without re-examining the individual patches, I see that 2/7 and 7/7 (possibly also new 1/7) lost pointers to pathspecs. I think I mentioned this previously: I hope we can find some way to direct folks towards the glossary entries that describe them. I would consider pathspecs a power-user feature, and they create lots of useful affordances. So it is fair to more gently introduce newcomers, but I would also still like to make sure it clear when commands accept pathspec “magic” :)

OTOH, I’ll take a look at the docs after this series lands and see if it feels like something is missing. It may be just fine to have pathspecs in the synopses and add a sentence somewhere after the gentle introduction “For more ways to specify paths, see…”

This one took a few hours because I had to backfill all of the "Changes in v2...", "Changes in v3..." but I think future ones will be faster to write.

Re the convention not being spelled out: in the "my first contribution" guide, it says:

The key elements that I was missing from this were:

1. it's actually probably good to keep some (most?) of the body from your original cover letter, so that folks don't have to go back to remember what this is about
2. It's useful to flag which review comments you addressed and which you didn't, and why, not just what the changes you made are

(I might have gotten those 2 points wrong though!)

Sorry for not mentioning that. My idea was to just leave <pathspec> in the synopsis, and then folks can look it up in the glossary if they're curious.

In the web documentation (https://git-scm.com/docs/git-checkout), the word "pathspec" is underlined, and hovering over it will show the definition, which I think will help with discoverability. Of course in the terminal version of the man pages it's harder to build in affordances like that.

Do you think that the concept of a "pathspec" is especially useful/powerful in the case of git checkout? If we're thinking more globally, i wonder if we could find a Git command where more complex pathspecs are especiallly useful and then include some examples of using a complex pathspec there.

If we include a compelling example and then a "see X for more about..." (here or somewhere else) I think it would be much more likely to motivate users to follow the breadcrumbs to learn more.

I think pathspecs are great for git-grep(1).

# Docs but ignore release notes
git grep loop -- Documentation/ ':^Documentation/RelNotes' # Just the git(1) manuals (more or less)
git grep loop -- 'Documentation/git-*adoc'

And also for narrowing a git-diff(1), like ignoring pom.xml changes in a Java project.

(But I never got into the habit of using them with git-checkout(1))

But once you learn about them you indeed can find uses for them in a lot of corners. I used them today and yesterday to selectively git-clean(1) and git-rm(1).

There should be a gitpathspecs(7). Not just a glossary entry.

This sounds like a good #leftoverbits topic for new-ish people to work on, with help from old timers? I do agree that the entry in the glossary has grown to be way too big. The pathspec magic itself should be mentioned there in the glossary, but the details of it feels a bit too much and the topic probably deserves its own manual page, just like gitrevisions(7) has one.

Thanks.

I added it to the unofficial tracker.

https://github.com/gitgitgadget/git/issues/1971

Kristoffer Haugsbakk

In a project that organizes its files reasonably cleanly, after doing a random explory development to reach a good stopping point, a user would realize that changes to subdirectory X and Y are good but changes to subdirectory Z are all useless, in which case of course "git checkout Z" (from the index, if you haven't done 'git add' to record interim state to the index), or "git checkout HEAD Z" (to get back to the pristine state) would be especially useful/powerful.

Of course, all the commands that take pathspec gain its benefits equally well, like "git grep -e pattern ':!not-here/'" to find pattern from everywhere except somewhere, "git log -p Doc/" to see changes that touched subset of paths, "git reset Z/" to undo earlier series of "git add"s only for the specified subset of paths.

If you are trying to find a command that new people are likely to first benefit from pathspec, I tend to think 'checkout' is not one of them. Be it 'reset' or 'checkout', the form with pathspec is typically used to undo the effect of earlier 'add' with pathspec, so in that sense, if we want to give a quick tutorial for pathspec to newbies in the documentation for a single command, 'add' probably is more appropriate than 'checkout'.

Thanks for updating. After re-reading these over, I think the updated text is a vast improvement. Also, after waiting for a while, we haven't heard much more comments on these changes.

Shall we congratulate a job very well done, declare victory, and merge these down to 'next' now?

Thanks.