Re: [PATCH] git-revert is one of the most misunderstood command in git, help users out.

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

Steven Grimm <koreth@midwinter.com> writes:

> But that suggested command is not going to convince anyone they were
> wrong about git being hard to learn. I wonder if instead of saying, "I
> know what you meant, but I'm going to make you type a different
> command," we should make git revert just do what the user meant.
>
> There is already precedent for that kind of mixed-mode UI:
>
> git checkout my-branch
> vs.
> git checkout my/source/file.c

That's an example of mixed-mode UI, but what you are suggesting
is quite different, isn't it?

There is no other officially supported single-command-way to
checkout paths out of the index.  "git checkout paths..." does
not introduce a confusion because of that.  The user learns the
way git supports that concept and that's the end of the story.
The same thing can be said about "git checkout <commit>
paths...".  That's _the_ way to checkout paths out of an
arbitrary commit.

In the case being discussed, we already have the concept of
checking out paths from the index, which has an officially
supported way to express.

You are proposing to give it a synonym "git revert paths...",
which superfitially sounds friendlier.  But I actually think
allowing a mistaken

	git revert path...

to be burned to users' fingers and brains is doing the user a
great disservice.

The next person would say "Why doesn't 'git revert HEAD path...'
work?", and you would add the synonym to do 'git checkout HEAD
path...'.  Up to that point it is sort-of Ok (but not quite).
You already have "git checkout" that let's you do so, but you
introduced new concepts that are "revert paths to the index" and
"revert paths to the last commit".

Which may make you feel good, but you just introduced a narrower
synonym the user needs to learn, than a more established and
wider concept that we already have: "checkout paths out of X",
where X are either the index or an arbitrary commit.

The reason I think the narrower synonym is bad and will lead to
more user confusion is because after that point you will have
a few issues.

Another newcomer would say "I like the fact that 'git revert
HEAD path...' works but why doesn't 'git revert HEAD~12 path...'
work?".

 - You may further allow "git revert <arbitrary-commit>
   path...".  But what does that _mean_?  "revert the path to
   the twelfth commit"?  You may implement that _anyway_.

   Then, the user would say "eh, why do you have both 'git
   checkout path...' and 'git revert path...' that seem to do
   the same thing?  There's no difference?  Why Why Why, git is
   so hard to learn".

 - You may instead not to do so, and explain that the "arbitrary
   commit" form is not supported and tell the user to use "git
   checkout <commit> paths...".

   The user will say: "but you earlier told me to use revert --
   you could have taught me to use checkout from the beginning
   and saved me from great confusion instead".

Giving the same concept two different names is bad unless there
is a compelling reason to do so.  Labelling an initially
narrower subset of an existing concept with a different name,
and having to extended that 'new concept' ending up with the
same as the existing concept is even worse.