[PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section

[PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section

[Julia Evans via GitGitGadget]

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

[PATCH 1/5] doc: git-checkout: clarify intro

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

- 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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd6562..ddda891c0ff7 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> - 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

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

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

As promised in the proposed log message, this conveys the same
information much more clearly.

"A different version of" neatly sidesteps the need to hint we can
check out paths from a tree or the index.  "Restore a different
version of files" (or "files from a different version") perhaps?
The point being you can grab multiple with a single operation, but
they all have to come from a single source.

Other than that, very nicely done.

> +Here's a description of all of the modes:

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

>  `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:

I do not think you are dealing with a conflict here, rather
ambiguity.  "You can use double-dash `--` to disambiguate between
branches and paths".


> +* `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)

We do not have to teach the full pathspec syntax here, but I wonder
if we should do something to avoid leading a new reader into
thinking they have to list files.  "...as a set of files and/or
directories", perhaps?

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> -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:

Another thing I noticed but forgot to mention.

>> +
>> +1. **Switch branches**, with `git checkout <branch>`

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.

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[Julia Evans]

Thanks for the comments!

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

Ok, will change.

> "Restore a different
> version of files" (or "files from a different version") perhaps?
> The point being you can grab multiple with a single operation, but
> they all have to come from a single source.

I like that, will change.

>> +Here's a description of all of the modes:
>
> I am not sure if we want/need this line, though.

Will remove.

> I do not think you are dealing with a conflict here, rather
> ambiguity.  "You can use double-dash `--` to disambiguate between
> branches and paths".

Will change.

>> +* `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)
>
> We do not have to teach the full pathspec syntax here, but I wonder
> if we should do something to avoid leading a new reader into
> thinking they have to list files.  "...as a set of files and/or
> directories", perhaps?

I like that, will change.

>>> +1. **Switch branches**, with `git checkout <branch>`
>
> Does everybody really understand what it means to "switch branches"
> without further explanation?

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

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

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.

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[D. Ben Knoble]

On Mon, Aug 25, 2025 at 3:09 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Julia Evans <julia@jvns.ca>
>
> - 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
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-checkout.adoc | 31 +++++++++++++++++++------------
>  1 file changed, 19 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 40e02cfd6562..ddda891c0ff7 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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:

This looks good—I initially scratched my head thinking there were 3
modes, but unifying "update files to match index" and "update files to
match specified tree" is easier to digest in this presentation.

>
>  `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)

I think we've dropped the bit about the default interpretation of "git
checkout <something>". Maybe

    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.

    By default, Git interprets `<something>` as a _<tree-ish>_.
    [explain what choosing a tree-ish means for the user?]

    [Your notes on disambiguation as before]

?

>
>  EXAMPLES
>  --------
> --
> gitgitgadget
>
>


-- 
D. Ben Knoble

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[Julia Evans]

> I think we've dropped the bit about the default interpretation of "git
> checkout <something>". Maybe
>
>     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.
>
>     By default, Git interprets `<something>` as a _<tree-ish>_.
>     [explain what choosing a tree-ish means for the user?]
>
>     [Your notes on disambiguation as before]

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")

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

>> I think we've dropped the bit about the default interpretation of "git
>> checkout <something>". Maybe
>>
>>     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.
>>
>>     By default, Git interprets `<something>` as a _<tree-ish>_.
>>     [explain what choosing a tree-ish means for the user?]
>>
>>     [Your notes on disambiguation as before]
>
> 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).

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[D. Ben Knoble]

On Thu, Aug 28, 2025 at 7:44 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Julia Evans" <julia@jvns.ca> writes:
>
> >> I think we've dropped the bit about the default interpretation of "git
> >> checkout <something>". Maybe
> >>
> >>     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.
> >>
> >>     By default, Git interprets `<something>` as a _<tree-ish>_.
> >>     [explain what choosing a tree-ish means for the user?]
> >>
> >>     [Your notes on disambiguation as before]
> >
> > 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")

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.

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

Yep, makes sense.

-- 
D. Ben Knoble

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[Junio C Hamano]

"D. Ben Knoble" <ben.knoble@gmail.com> writes:

>> +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:
>
> This looks good—I initially scratched my head thinking there were 3
> modes, but unifying "update files to match index" and "update files to
> match specified tree" is easier to digest in this presentation.

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.

Re: [PATCH 1/5] doc: git-checkout: clarify intro

[D. Ben Knoble]

On Fri, Aug 29, 2025 at 5:00 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>
> >> +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:
> >
> > This looks good—I initially scratched my head thinking there were 3
> > modes, but unifying "update files to match index" and "update files to
> > match specified tree" is easier to digest in this presentation.
>
> 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.

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?

> Anyway, thanks for a review.

:)

-- 
D. Ben Knoble

[PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index ddda891c0ff7..a3edb95973a2 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> - "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.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-checkout.adoc | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index ddda891c0ff7..a3edb95973a2 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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.

Do we expect readers to truly understand what is to "switch to branch"
without explanation?  IOW, I am undecided if the lost "To prepare for
working on" is a good thing.

Usually with "changes on _<branch>_", people mean quite a different
thing from what the above paragraph refers to.

Imagine that you are on a branch that you forked from 'main' some
time ago, built a handful of commits, among which there may be ones
that touch file F.  You further have local modification to file F.
Now you want to switch to another branch.  That branch, since it
forked from 'main', never touched F.  Your local changes do not
conflict with "the changes on branch" (there is no changes on branch
to conflict with your work, as F stayed the same).

To improve, "with the changes on _<branch>_" should be phrased more like
"with the differences between the current state and that of the
_<branch>_" or something.

>  +
>  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`.

I do not think "glorified no-op" is a reference to "status".  At least,
when I wrote it, I didn't mean it that way to compare this glorified
no-op with "git status" [*].  It is a reference to "even though you are
invoking the 'checkout' command, you are not checking out anything."
The side effect is to see the tracking information, which is "rather
expensive side-effects"---compared to doing nothing, anything is
expensive ;-).

I strongly suspect that running "git status" is much more costly than
"git checkout", simply because the former has to do a lot more than just
peeking the tracking information; it internally runs diff between HEAD
and the index, and between the index and the working tree, and it also
has to find and list untracked paths.  Both commands compute the
tracking info by calling the same remote.c::format_tracking_info()
function.

Other than these minor points, the new text seems a definite
improvement.


[References]

 * https://lore.kernel.org/git/7vk3shm5d5.fsf@alter.siamese.dyndns.org/
   is where the "glorified no-op" came from.

Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans]

> Do we expect readers to truly understand what is to "switch to branch"
> without explanation?  IOW, I am undecided if the lost "To prepare for
> working on" is a good thing.

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?

> Usually with "changes on _<branch>_", people mean quite a different
> thing from what the above paragraph refers to.
>
> Imagine that you are on a branch that you forked from 'main' some
> time ago, built a handful of commits, among which there may be ones
> that touch file F.  You further have local modification to file F.
> Now you want to switch to another branch.  That branch, since it
> forked from 'main', never touched F.  Your local changes do not
> conflict with "the changes on branch" (there is no changes on branch
> to conflict with your work, as F stayed the same).
>
> To improve, "with the changes on _<branch>_" should be phrased more like
> "with the differences between the current state and that of the
> _<branch>_" or something.

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

> I do not think "glorified no-op" is a reference to "status".  At least,
> when I wrote it, I didn't mean it that way to compare this glorified
> no-op with "git status" [*].  It is a reference to "even though you are
> invoking the 'checkout' command, you are not checking out anything."
> The side effect is to see the tracking information, which is "rather
> expensive side-effects"---compared to doing nothing, anything is
> expensive ;-).
>
> I strongly suspect that running "git status" is much more costly than
> "git checkout", simply because the former has to do a lot more than just
> peeking the tracking information; it internally runs diff between HEAD
> and the index, and between the index and the working tree, and it also
> has to find and list untracked paths.  Both commands compute the
> tracking info by calling the same remote.c::format_tracking_info()
> function.

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]

Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

>> Do we expect readers to truly understand what is to "switch to branch"
>> without explanation?  IOW, I am undecided if the lost "To prepare for
>> working on" is a good thing.
>
> 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:

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.

> ("Please commit your changes or stash them before you switch branches.")
> Which readers do you think would be confused by it?

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

Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans]

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

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

[PATCH 3/5] doc: git-checkout: don't use "reset"

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index a3edb95973a2..dc9607d9ea39 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH 4/5] doc: git-checkout: deduplicate --detach explanation

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index dc9607d9ea39..b343d292b30b 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH 5/5] doc: git-checkout: clarify restoring files section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index b343d292b30b..9f2b86ac5368 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index b343d292b30b..9f2b86ac5368 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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 same comment about "files and directories from a different
version" applies here.

Also, I am not so sure about the claim that the verb "restore" is
better understood than "overwrite" due to the presence of "git
restore".  If you are working on, say, an older maintenance track,
and want to borrow what is in a few files from the development
branch, you may say "git restore --source=develop files..." go grab
them down to your current working tree.  But at least to me,
"restore" has a connotation to get back what you used to have, but
the contents in these files you are grabbing had not existed on the
older maintenance track you are working on, ever, and "restore" had
always made me go "Huh?".

I am not suggesting to change the command name "restore"; I am
suggesting the operation that command does using a verb that is
different from "restore" (in an ancient thread, we tried to explain
"checkout" without using "checkout" as the primary verb to describe
what it does, it is the same thing).

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

OK.  I suspect the most common is to "restore" from HEAD, and the
"Huh?"ness of using the verb "restore" goes away.  It clearly is
getting you back to where you were back when your working tree was
in sync with HEAD.  Perhaps use "git checkout HEAD file.txt" for the
example?

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

That is a very negative way to state it.  It is not "do not specify
where".  If you do not give tree, you are actively specifying that
you want things 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.

This is confusing in a way different from the original.  During a
conflicted merge, you will see a few stages until they are resolved.

 (1) The working tree file has conflict markers and text from
     multiple variants.  The index has higher-stage cache entry for
     such a path.

 (2) The user edits the working tree file to resolve the conflicts.
     Once all the conflict markers are removed, some people may say
     "the merge conflict has been resolved".  To Git, the path is
     still unmerged.

 (3) The user tells the index what the resolution is, with commands
     like "git add", "git rm", and the like.  The higher-stage cache
     entries in the index for the path are moved and replaced with a
     single stage-0 entry.  To Git, the path is now merged.

So, "a file with an unresolved merge conflict" would not mean what
you wanted to say for those who consider that dealing with the
working tree files is enough to declare victory and consider the
conflict has been resolved.

> +Using `-f` will ignore the merge conflict.  The contents from a

This changes the meaning to most people from what the original
meant.  If you have a file F with merge conflicts in the earlier
part but the later part merged cleanly, does "git checkout -f F"
ignore the conflicted part and overwrite the rest of the file
somehow?

If you wanted to avoid the term "unmerged cache entries", you can
say "unmerged paths".

Taking all of the above into consideration, perhaps...

    When you are in the middle of a conflicted merge (or
    cherry-pick, "stash pop", etc.) and haven't told Git what the
    resolution for these conflicted paths are with "git add" and
    friends, using "git checkout" to check out such an unmerged path
    out of the index would fail and the command exits with non-zero
    exit status.

    When the `-f` option is given, these unmerged paths are left
    untouched, instead of triggering an error.  For all other
    (i.e. merged) paths that match the <pathspec>, the working tree
    files are overwritten by the version recorded in the index.

or something along that line, but with a readability enhancement
like you have been doing in your series ;-).

Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

[Julia Evans]

On Tue, Aug 26, 2025, at 6:43 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
>> index b343d292b30b..9f2b86ac5368 100644
>> --- a/Documentation/git-checkout.adoc
>> +++ b/Documentation/git-checkout.adoc
>> @@ -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 same comment about "files and directories from a different
> version" applies here.
>
> Also, I am not so sure about the claim that the verb "restore" is
> better understood than "overwrite" due to the presence of "git
> restore".  If you are working on, say, an older maintenance track,
> and want to borrow what is in a few files from the development
> branch, you may say "git restore --source=develop files..." go grab
> them down to your current working tree.  But at least to me,
> "restore" has a connotation to get back what you used to have, but
> the contents in these files you are grabbing had not existed on the
> older maintenance track you are working on, ever, and "restore" had
> always made me go "Huh?".
>
> I am not suggesting to change the command name "restore"; I am
> suggesting the operation that command does using a verb that is
> different from "restore" (in an ancient thread, we tried to explain
> "checkout" without using "checkout" as the primary verb to describe
> what it does, it is the same thing).
>
>>  +
>> -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.
>
> OK.  I suspect the most common is to "restore" from HEAD, and the
> "Huh?"ness of using the verb "restore" goes away.  It clearly is
> getting you back to where you were back when your working tree was
> in sync with HEAD.  Perhaps use "git checkout HEAD file.txt" for the
> example?
>
>> +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.
>
> That is a very negative way to state it.  It is not "do not specify
> where".  If you do not give tree, you are actively specifying that
> you want things 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.
>
> This is confusing in a way different from the original.  During a
> conflicted merge, you will see a few stages until they are resolved.
>
>  (1) The working tree file has conflict markers and text from
>      multiple variants.  The index has higher-stage cache entry for
>      such a path.
>
>  (2) The user edits the working tree file to resolve the conflicts.
>      Once all the conflict markers are removed, some people may say
>      "the merge conflict has been resolved".  To Git, the path is
>      still unmerged.
>
>  (3) The user tells the index what the resolution is, with commands
>      like "git add", "git rm", and the like.  The higher-stage cache
>      entries in the index for the path are moved and replaced with a
>      single stage-0 entry.  To Git, the path is now merged.
>
> So, "a file with an unresolved merge conflict" would not mean what
> you wanted to say for those who consider that dealing with the
> working tree files is enough to declare victory and consider the
> conflict has been resolved.
>
>> +Using `-f` will ignore the merge conflict.  The contents from a
>
> This changes the meaning to most people from what the original
> meant.  If you have a file F with merge conflicts in the earlier
> part but the later part merged cleanly, does "git checkout -f F"
> ignore the conflicted part and overwrite the rest of the file
> somehow?
>
> If you wanted to avoid the term "unmerged cache entries", you can
> say "unmerged paths".
>
> Taking all of the above into consideration, perhaps...
>
>     When you are in the middle of a conflicted merge (or
>     cherry-pick, "stash pop", etc.) and haven't told Git what the
>     resolution for these conflicted paths are with "git add" and
>     friends, using "git checkout" to check out such an unmerged path
>     out of the index would fail and the command exits with non-zero
>     exit status.
>
>     When the `-f` option is given, these unmerged paths are left
>     untouched, instead of triggering an error.  For all other
>     (i.e. merged) paths that match the <pathspec>, the working tree
>     files are overwritten by the version recorded in the index.
>
> or something along that line, but with a readability enhancement
> like you have been doing in your series ;-).

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

Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

[D. Ben Knoble]

On Mon, Aug 25, 2025 at 3:31 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Julia Evans <julia@jvns.ca>
>
> - 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>"

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.

> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index b343d292b30b..9f2b86ac5368 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
> -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

Possibly a missing paragraph break here?

> +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>...]`::

I think I would expect to keep this break, but I might be misreading something.

-- 
D. Ben Knoble

Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

[Julia Evans]

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

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 :)

Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

> $ git checkout HEAD:Documentation/ git-commit.adoc
>
> to restore `file.txt` into a different directory than it was originally.

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.

> 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 :)

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

Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

[D. Ben Knoble]

On Thu, Aug 28, 2025 at 4:00 PM Julia Evans <julia@jvns.ca> wrote:
>
> > 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.
>
> 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.

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'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 :)

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

[PATCH v2 0/5] doc: git-checkout: clarify DESCRIPTION section

[Julia Evans via GitGitGadget]

 * 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
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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

[PATCH v2 1/5] doc: git-checkout: clarify intro

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

- 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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd65..c86941ad53 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH v2 1/5] doc: git-checkout: clarify intro

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> - 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
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---

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

https://lore.kernel.org/git/de40e0ed-ca12-41b0-acd0-3c594078cc14@app.fastmail.com/

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

>  Documentation/git-checkout.adoc | 29 +++++++++++++++++------------
>  1 file changed, 17 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 40e02cfd65..c86941ad53 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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.

"Switches branches" I can understand.  You were on your old branch
(your HEAD usually is pointing at some branch), and you move to your
new branch by making it your "current" branch.

I do not understand "switches commits".  When you move to a commit
(i.e. your HEAD can point directly at a commit without referring to
any branch), are you switching one commit with another?  I do not
think users would view it that way.

Phrasing it with "switch to" may make it easier to handle.  Then
your previous state would not matter as much.

    ... and then switch to the named branch or the named commit, or
    restores the files in the working tree (i.e. overwrites them
    from different versions).

perhaps.

> +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
> +----------

Good.

>  
>  EXAMPLES
>  --------

Re: [PATCH v2 1/5] doc: git-checkout: clarify intro

[Julia Evans]

> You seem to have forgotten to update the proposed log message ...
>
> https://lore.kernel.org/git/de40e0ed-ca12-41b0-acd0-3c594078cc14@app.fastmail.com/
>
> ... to avoid making it just an enumeration of "these random things
> were done in this patch" (and instead tell a coherent story).

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 :)

> I do not understand "switches commits".  When you move to a commit
> (i.e. your HEAD can point directly at a commit without referring to
> any branch), are you switching one commit with another?  I do not
> think users would view it that way.
>
> Phrasing it with "switch to" may make it easier to handle.  Then
> your previous state would not matter as much.

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

[PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index c86941ad53..4de3ac6680 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

The condition to stop you is a bit stronger than that.

By default, we would not even attempt to "merge into the branch" at
all.  If your previous HEAD and the branch you are switching to are
different at a path you have local modifications in, then no changes
will be made and the checkout will fail.  With "-m", we try to merge
and this merge can leave conflicts for you to sort out.

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

This is much better than the crappy original I wrote years ago.
Thanks.

Re: [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans]

> The condition to stop you is a bit stronger than that.
>
> By default, we would not even attempt to "merge into the branch" at
> all.  If your previous HEAD and the branch you are switching to are
> different at a path you have local modifications in, then no changes
> will be made and the checkout will fail.  With "-m", we try to merge
> and this merge can leave conflicts for you to sort out.

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.

[PATCH v2 3/5] doc: git-checkout: don't use "reset"

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 4de3ac6680..e4614674f0 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH v2 3/5] doc: git-checkout: don't use "reset"

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> Many Git users don't know what the term "reset" means. Resolve this by:

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*?

> - Expanding it into its definition, in one case

    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?

> - Giving a simpler but still accurate explanation ("the branch will not
>   be created or modified"), in the other case

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:").
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-checkout.adoc | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 4de3ac6680..e4614674f0 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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. ...

Good.

> ... 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>`::

This is in response to "transactional equivalent".  I've always felt
that there is no need to say "transactional" in this at all.  IOW, I
wouldn't have minded if we rewrote this more heavily.

When you have to clarify with things like "that is", "what this
means is", etc., after some text, I've often found that the result
becomes crispier and more clear if we removed fuzzy text that needed
such clarification and rewrite the sentence using elements form only
the clarifying text.

    If `-B` is given, _<new-branch>_ is created if it doesn't exist,
    otherwise, it is made to point at the given commit.  And the
    branch is made the current branch.
    +
    Creation of the new branch or reseting of the existing branch to
    point at the commit happens only if the resulting branch can be
    successfully checked out.  Oterwise branch creation is not done
    and the exiting branch is left as-is.

or something?  I dunno.

Re: [PATCH v2 3/5] doc: git-checkout: don't use "reset"

[Julia Evans]

> 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*?

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

>> Many Git users don't know what the term "reset" means. Resolve this by:
>
> 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'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.

>> ... 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>`::
>
> This is in response to "transactional equivalent".  I've always felt
> that there is no need to say "transactional" in this at all.  IOW, I
> wouldn't have minded if we rewrote this more heavily.

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

Re: [PATCH v2 3/5] doc: git-checkout: don't use "reset"

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

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

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

>>>  `git checkout --detach [<branch>]`::
>>>  `git checkout [--detach] <commit>`::
>>
>> This is in response to "transactional equivalent".  I've always felt
>> that there is no need to say "transactional" in this at all.  IOW, I
>> wouldn't have minded if we rewrote this more heavily.
>
> "Transactional equivalent" was bothering me too and I like the
> idea of rewriting it, will give it a shot.

Thanks.

[PATCH v2 4/5] doc: git-checkout: deduplicate --detach explanation

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index e4614674f0..4d522a5f75 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v2 5/5] doc: git-checkout: clarify restoring files section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

- 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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 45 ++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 4d522a5f75..dababe452a 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section

[Julia Evans via 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>_`)
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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 <julia@jvns.ca>
      
       ## 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`
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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 <julia@jvns.ca>
      
       ## 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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

[PATCH v3 1/6] doc: git-checkout: clarify intro

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

- 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>_`)

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd65..218d3dd13d 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v3 2/6] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

- 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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 218d3dd13d..50923ff118 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

- 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`

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 44 ++++++++++++++-------------------
 1 file changed, 18 insertions(+), 26 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 50923ff118..a2777fb5b0 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v3 4/6] doc: git-checkout: deduplicate --detach explanation

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index a2777fb5b0..d35fd32ce8 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v3 5/6] doc: git-checkout: split up restoring files section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index d35fd32ce8..b361ff011a 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v3 6/6] doc: git-checkout: clarify restoring files section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index b361ff011a..ae19565f4f 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH v3 6/6] doc: git-checkout: clarify restoring files section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

Hmph.  I agree that there is no reason to stress that you are not
required to use a commit here (hence not much point in saying
tree-ish).  I do not think avoiding "index" (which is not even a
jargon; it is the official name of the thing) is necessarily a good
idea, given that ...

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

... we'd have to say "from the index to your working tree files"
here.  In contrast, the earlier one is "from the commit to the index
and to your working tree files", and explaining it as such may make
the similarity & differences stand out more clearly.

Also, I personally find it easier to follow if you did
"directories. This works by copying" -> "directories, by copying".
It comes from the same "think again when you find that you are
saying 'it means that' and such" principle.

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

OK.

Re: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  * 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...")

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

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

Much better.

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

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

>      ++`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.
>        +
>      ++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.

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.

Re: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section

[Julia Evans]

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

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.

>>      ++	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.
>
> 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 like the idea of "changes follow you". Will work on making this clearer.

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

Makes sense. I'll be more explicit.

[PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Julia Evans via GitGitGadget]

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 <julia@jvns.ca>
      
       ## 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ 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

[PATCH v4 1/7] doc: git-checkout: clarify intro sentence

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd65..9733c73450 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v4 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

There's no need to use the terms "pathspec" or "tree-ish" in the
ARGUMENT DISAMBIGUATION section, which are terms that (from user
feedback on this page) many users do not understand.

"tree-ish" is actually not accurate here: `git checkout` in this case
takes a commit-ish, not a tree-ish. So we can say "branch or commit"
instead of "tree-ish" which is both more accurate and uses more familiar
terms.

And now that the intro to the man pages mentions that `git checkout` has
"two main modes", it makes sense to refer to this disambiguation section
to understand how Git decides which one to use when there's an overlap
in syntax.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

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

[PATCH v4 3/7] doc: git-checkout: clarify `git checkout <branch>`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback: several users commented that "Local modifications
to the files in the working tree are kept, so that they can be committed
to the <branch>." didn't seem accurate to them, since
`git checkout <branch>` will often fail.

One user also thought that "... and by pointing HEAD at the branch"
was something that _they_ had to do somehow ("How do I point HEAD at
a branch?") rather than a description of what the `git checkout`
operation is doing for them.

Explain when `git checkout <branch>` will fail and clarify that
"pointing HEAD at the branch" is part of what the command does.

6 users commented that the "You could omit <branch>..." section is
extremely confusing. Explain this in a much more direct way.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

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

[PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 44 ++++++++++++++-------------------
 1 file changed, 18 insertions(+), 26 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 0db32b098e..7ae2ae9483 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B`

[Kristoffer Haugsbakk]

On Wed, Sep 10, 2025, at 21:14, Julia Evans via GitGitGadget wrote:
>[snip]
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 0db32b098e..7ae2ae9483 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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.

s/`_<branch>_`/_<branch>_/

The backticks causes it to be rendered with the underlines.

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

s/`_<branch>_`/_<branch>_/

>
>  `-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

[PATCH] doc: git-checkout: fix placeholder markup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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

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

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 431185ca0ba..6f281b298ef 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH resend] doc: git-checkout: fix placeholder markup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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

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

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 431185ca0ba..6f281b298ef 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH resend] doc: git-checkout: fix placeholder markup

[Julia Evans]

Thanks, apologies for missing this at the time.

On Thu, Oct 16, 2025, at 6:11 PM, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 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.
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>
> Notes (series):
>     Since this has landed in `master` now.
>
>  Documentation/git-checkout.adoc | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 431185ca0ba..6f281b298ef 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -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

[PATCH v2] doc: git-checkout: fix placeholder markup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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.

Acked-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 431185ca0ba..6f281b298ef 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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 <julia@jvns.ca>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## 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

[PATCH v4 5/7] doc: git-checkout: deduplicate --detach explanation

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 7ae2ae9483..dd3cbb210d 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v4 6/7] doc: git-checkout: split up restoring files section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index dd3cbb210d..1e19e13a0e 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

[PATCH v4 7/7] doc: git-checkout: clarify restoring files section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

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.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-checkout.adoc | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 1e19e13a0e..d8e8bcf549 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -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

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Ben Knoble]

> Le 10 sept. 2025 à 15:14, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> 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.

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? :)

> * 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:

Range-diff looks good to me!

> 
> -:  ---------- > 1:  4b52ffd497 doc: git-checkout: clarify intro sentence
> 1:  1975384dd0 ! 2:  08f0a5efab doc: git-checkout: clarify intro
>     @@ Metadata
>      Author: Julia Evans <julia@jvns.ca>
> 
>       ## 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.
> 
>          Signed-off-by: Julia Evans <julia@jvns.ca>
> 
>       ## 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

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

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…”

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Julia Evans]

>> * 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.
>
> 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? :)

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:

> Edit your cover letter again. Now is a good time to mention what's different
> between your last version and now, if it's something significant. You do not
> need the exact same body in your second cover letter; focus on explaining to
> reviewers the changes you've made that may not be as visible.

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!)

>>     +    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.
>
> 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…”

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.

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Kristoffer Haugsbakk]

On Fri, Sep 12, 2025, at 16:05, Julia Evans wrote:
>> 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…”
>
> 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.

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

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

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Kristoffer Haugsbakk]

On Tue, Sep 16, 2025, at 01:22, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>> 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.

I added it to the unofficial tracker.

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

-- 
Kristoffer Haugsbakk

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

> Do you think that the concept of a "pathspec" is especially useful/powerful
> in the case of `git checkout`?

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

Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

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.