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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 5, 2007, 22:21 UTC
Message-ID: <7vlk9cmiyq.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <CD2E6759-9E7E-41E6-8B58-AB6CA9604111@midwinter.com>

Steven Grimm <koreth@midwinter.com> writes:

Show 10 quoted lines

> 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.