From: Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
Date: Wed, 03 Sep 2025 16:49:56 GMT
Subject: [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section
Message-ID: <pull.1962.v3.git.1756918202.gitgitgadget@gmail.com>
In-Reply-To: <pull.1962.v2.git.1756467934.gitgitgadget@gmail.com>

 * 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