Re: [RFC] Introduce two new commands, switch-branch and restore-paths

[Junio C Hamano <gitster@pobox.com>]

Stefan Beller <sbeller@google.com> writes:

> Maybe we need to step back and consider what the command does.
> And from that I would name it "rewire-HEAD-and-update-index&worktree"
> and then simplify from there. For the beginner user, the concept of
> HEAD might be overwhelming, such that we don't want to have that
> in there.

I'd have to say that it is totally backwards.

Use of HEAD, ref, etc. is merely a means to what the end users want
to achieve, which is to switch to a "branch" (in air quotes, as the
word in this sentence means a bit broader than "a ref that is in
refs/heads/"), to choose which lineage of commits to work on to grow
or reshape the history.  Most of the time, you would be working on a
branch (that is a ref that is in refs/heads/), sometimes you would
be working on an unnamed "branch" (i.e. detached HEAD state, only
difference between being on it and a normal branch is whether it is
named---the history manipulation can happen exactly the same way).

In other words, your initial motivation of stepping back and
thinking about what the command is about is very good.  But in the
context of checking out a branch, the concept the end user works
with are at the level of "branch", not HEAD, ref, index, working
tree (all of which are underlying implementation details that let
you work on manipulating the history, represented by the "branch").

> "content-to-path", maybe(?) ...

Path is not a place.  A path t/Makefile is a shared name of a place
in a tree, the index, or in the working tree.  Renaming "git add" to
"content-to-path" because it adds the content to the index at path
may be equally OK, but it misses the essense (which is that it is to
add to the index and not to anythng else like a tree or the working
tree).

I actually think the easiest-to-understand shorthand for the
operation "checking out the contents at the path to the working
tree" is "checkout".  

These...

>   git tree-to-worktree # git checkout <commit> -- <path>
>   git index-to-worktree # git checkout -- <path>

...are interesting and worth learning lessons from.  These would be
something people would suggest when users start making noises about
"restore-to-path" or "content-to-path" overloads three different
operations and is confusing.

I think "restore-to-path" that can take contents for individual
paths out of either a treeish or the index and update the index and
the working tree, depending on what the user tells it to do, is not
confusing to the end users.  At the conceptual level, the users need
to have a mental model that has three places (tree-ish, index and
working tree) that can hold contents to make use of these
operations, so it is only the matter of how to express it clearly
and concisely.

For that matter, "checkout <branch>", "checkout <treeish> -- <path>"
and "checkout -- <path>" already is a trio of clear and cocncise way
to spell three distinct operations, so with the right mental model,
it may not be so confusing to the users.  And "checkout-branch",
"checkout-contents-from-tree", and "checkout-contents-from-index"
longhands may be a good way to help new users form the right mental
model, as they are more explicit in their names; once they form the
right mental model (that is, there are three places the contents
live, and there are a few operations to move contents from the two
places to the working tree, i.e. what traditionally is called
"checking things out"), they may gradulate to the shorthand form.