Junio C Hamano <gitster@xxxxxxxxx> writes: > - there are three distinct kinds of states: a committed state, the state > in the index (aka "what you have staged so far to the index"), and the > state in your work tree. > > - many commands understand that you want to operate on and/or inspect > states in one or more of these states. They default to what is often > used (e.g. "git diff" compares the index and the work tree, "git grep" > looks in the work tree, "git apply" patches the work tree [*1*]), but > you can tell them to use different entities via options and arguments. > > How does it help understanding any of the above to introduce STAGE? For the first, if there are three kinds of states, I would find it natural to have three kinds of ways to talk about these states. Sure, it doesn't change the second, since it makes things more explicit, it doesn't make them more concise. > - when you want to work with the index, you say --cached; But that doesn't apply to "git diff". Both "git diff" and "git diff --cached" work with the index. "git diff" works with the index and work tree, while "git diff --cached" work with the index and HEAD. > - when you want to work with both the index and the work tree at the > same time, you say --index. ... which is everything but intuitive. The option name doesn't tell the user what the command is doing. First thing is that with Git, the user has to learn 3 words for one concept (index, cache, staging area). And then, he has to learn that although people use "index" and "cache" as synomyms, --index and --cached have different meanings. And that one can also have a --cache, and that it's possible to have a --stage too, but with different meaning. I can understand the historical reasons, but I think finding a way to get rid of this historical terminology mess should be encourraged. > - for all commands, working with work tree is the default, so there is > no --work-tree option (we could add one, if you really want). Except "git checkout", which takes the index by default, and a commit if specified. It makes sense since checking-out from the working tree doesn't make sense, but it is a special case, and learning the general rules you give doesn't tell the user what "git checkout" does. Except "git ls-files", too. And I may have missed some. See, you complain about special cases with the proposal, but the current UI _has_ tons of special cases like this. > and the STAGE would work something like this: > > - when you want to work with a committed state (or more in general, > with a tree-ish), you give the name of the commit; It's not just "I want to work with". It's also about the role of the things you want to work with. "git diff WORKTREE STAGE" would mean "diff from the worktree to the staging area", while "git diff STAGE WORKTREE" would mean the other way around. > Think. What does "git log STAGE" mean? Can you explain why it does not > make any sense? It could make sense. Actually, gitk does show the work-tree and the index in a way similar to commits. Fundamentally, I don't see a difference between "git log" and "gitk" except that gitk is graphical. Sure, STAGE and WORKTREE cannot have a commit message, and hardly have an author, but I could very well imagine "git log --stat WORKTREE" showing roughly what "git diff --stat; git diff --stat --cached; git log --stat HEAD" does today. I don't know how usefull this would be, but I wouldn't say it doesn't make sense either. -- Matthieu -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html