* 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@xxxxxxx> ## 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@xxxxxxx> ## 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@xxxxxxx> ## 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
