Package: git-doc
Version: 1:1.8.5.2-2
Severity: minor
Justification: documentation
Tags: upstream
>From #git:
EugeneKay> man git-checkout always makes me cry
The overview at the top of DESCRIPTION says "Update files in the working
tree to match [...]. If no paths are given, 'git checkout' will also
update HEAD [...]". That is a true description, but it is
(1) incomplete and
(2) unilluminating.
It would be better to offer some mnemonic about how "git checkout" is
for retrieving file content, in two different cases: starting to work
on a different branch, or retrieving selected files. Then:
(i) pre-checkout checks that prevent it from clobbering local changes
(ii) what each mode does, in terms of flow of data
(git checkout BRANCH --: modifies HEAD, index, and worktree.
"context switch".
git checkout BRANCH -- PATHS: modifies index and worktree.
"copy".
git checkout -- PATHS: modifies worktree.
"undo".
)
(iii) shortcuts: -b, -B, --orphan
(iv) SEE ALSO: gitindex(5). The latter would explain its usual
relationship to the worktree.
The section (i) would address bug#609128.
--
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]
