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

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

 * 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