freshlybakedca.ke / git
Git fork
fork atom

doc: git-checkout: clarify restoring files section

From user feedback on this section: 3 users don't know what "tree-ish"
means and 3 users don't know what "pathspec" means. One user also says
that the section is very confusing and that they don't understand what
the "index" is.

From conversations on Mastodon, several users said that their impression
is that "the index" means the same thing as "HEAD". It would be good to
give those users (and other users who do not know what "index" means) a
hint as to its meaning.

Make this section more accessible to users who don't know what the terms
"pathspec", "tree-ish", and "index" mean by using more familiar language,
adding examples, and using simpler sentence structures.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

authored by

Julia Evans and committed by
Junio C Hamano 83a9405e bfe7b17c

+18 -11
unified split
+18 -11
Documentation/git-checkout.adoc
··· 75 75 `git checkout <tree-ish> [--] <pathspec>...`:: 76 76 `git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`:: 77 77 78 - Overwrite both the index and the working tree with the 79 - contents at the _<tree-ish>_ for the files that match the pathspec. 78 + Replace the specified files and/or directories with the version from 79 + the given commit or tree and add them to the index 80 + (also known as "staging area"). 81 + + 82 + For example, `git checkout main file.txt` will replace `file.txt` 83 + with the version from `main`. 80 84 81 85 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`:: 82 86 `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`:: 83 87 84 - Overwrite working tree with the contents in the index for the files 85 - that match the pathspec. 88 + Replace the specified files and/or directories with the version from 89 + the index. 90 + + 91 + For example, if you check out a commit, edit `file.txt`, and then 92 + decide those changes were a mistake, `git checkout file.txt` will 93 + discard any unstaged changes to `file.txt`. 86 94 + 87 - The index may contain unmerged entries because of a previous failed merge. 88 - By default, if you try to check out such an entry from the index, the 89 - checkout operation will fail and nothing will be checked out. 90 - Using `-f` will ignore these unmerged entries. The contents from a 91 - specific side of the merge can be checked out of the index by 92 - using `--ours` or `--theirs`. With `-m`, changes made to the working tree 93 - file can be discarded to re-create the original conflicted merge result. 95 + This will fail if the file has a merge conflict and you haven't yet run 96 + `git add file.txt` (or something equivalent) to mark it as resolved. 97 + You can use `-f` to ignore the unmerged files instead of failing, use 98 + `--ours` or `--theirs` to replace them with the version from a specific 99 + side of the merge, or use `-m` to replace them with the original 100 + conflicted merge result. 94 101 95 102 `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`:: 96 103 This is similar to the previous two modes, but lets you use the