Stefan Beller <sbeller@xxxxxxxxxx> 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.
