* 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.Julia Evans via GitGitGadget <gitgitgadget@gmail.com>