[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

[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

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

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

[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

[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

[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

[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

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

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

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

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

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