From: Julia Evans <julia@xxxxxxx> - 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@xxxxxxx> --- 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
