Re: [PATCH v2] git-checkout.txt: Document "git checkout <pathspec>" better

["Andres G. Aragoneses" <knocte@gmail.com>]

On 17/06/15 19:24, Matthieu Moy wrote:
> Torsten Bögershausen <tboegi@web.de> writes:
>
>> My v3 will probably use the original line:
>> git-checkout - Checkout a branch or paths to the working tree
>
> I think mentionning "Switch branch" was a real improvement. For someone
> not familiar with the version control vocabulary, "checkout" does not
> mean much (just looked in a dictionary, it talks about payment and
> leaving a room in a hotel ...). And someone not understanding what
> "checkout" means in this context won't be helped much reading the
> description and getting "checkout" there.
>
> (Ironically, Junio did almost the same remark when I proposed to
> document "git describe" as "Describe ...", but the word "describe" does
> not have the ambiguity problem that "checkout" has)
>
>> 'git checkout <commit> -- <path>'
>> will "copy" the version from another commit into the workspace.
>
> If <commit> exists, it means that the state of this path existed
> somewhere in <path> in the past (well, modulo "git add -p" and other
> ways to cheat with history).
>
> So, to me, "restore a previous version" does apply in this case. Perhaps
> "restore a recorded state into the worktree" (my favorite up to now I
> think).
>
> But as you say, it copies into the workspace, so "copy a previous
> version into the workspace" sounds good to me.
>
> Basically, I'm fine with anything starting with "Switch branches or",
> but please do change the headline ;-).
>

Having read all this thread, I think it's really confusing that:
1) We have this command named "checkout", as Matthieu points out.
2) This command allows different distinct operations (one for when it 
receives a path, other for when it receives a branch, other for when it 
receives a commit...).

So what I would propose is fix the root of the problem: split these 
command in several ones, and mark the "checkout" command as deprecated 
(it would still allow the same functions as before, but it would not be 
documented, and would be announced as deprecated when used).

So then we could have a "git switch <branchname>" for switching to a 
different branch.

Also a "git discard <path>" to discard local changes.

Etcetera.

Comments?