Re: Consistent terminology: cached/staged/index

From: Miles Bader <miles@gnu.org>
To: Junio C Hamano <gitster@pobox.com>
Cc: Michael J Gruber <git@drmicha.warpmail.net>,
	Johannes Sixt <j.sixt@viscovery.net>,
	Jonathan Nieder <jrnieder@gmail.com>,
	Piotr Krukowiecki <piotr.krukowiecki.news@gmail.com>,
	git@vger.kernel.org
Subject: Re: Consistent terminology: cached/staged/index
Date: Tue, 15 Feb 2011 08:47:00 +0900	[thread overview]
Message-ID: <AANLkTikyc5QEou8Em-3HkLSHWHQyx+MnYMQ9OSN33_QS@mail.gmail.com> (raw)
In-Reply-To: <7vzkpyql2r.fsf@alter.siamese.dyndns.org>

On Tue, Feb 15, 2011 at 7:59 AM, Junio C Hamano <gitster@pobox.com> wrote:
> I actually was hoping that it was obvious that -s is a no-starter from the
> messages so far in this thread, as neither --cached nor its more
> descriptive spelling --index-only has character 's' anywhere in it, and we
> have been keeping --staged as a low-key synonym for a reason.

It was not at all obvious.  Even if you like --cached more than
--staged, there's a difference between advocating "--staged", and
using "-s" as a short-option for the operation which --cached /
--staged invoke.

Short option names are often a compromise, because clearly there are
often conflicts.  That _doesn't_ mean that one should simply not have
a short option, when a "perfect" choice cannot be found.  If a
"perfect" short-option isn't available, then usually one turns to
somewhat less perfect choices, trying to at least find some heuristic
that can make them easier to memorize -- because in the end, short
options must be memorized (and if they are truly common operations,
this isn't generally difficult; it's memorizing _rarely_ used short
options that's hard).

Of the various choices, "-s" does at least have such a heuristic
connection to an appropriate long option ("-i" is arguably worse than
-s, because it doesn't have any such connection...).  Can you suggest
something better?

[BTW, isn't the name "--index-only" something of a misnomer?  If
something is called "--XXX-only", that implies that the default
operation uses "XXX + something else" instead of XXX, but that
otherwise they are the same.  However in fact the difference in
behavior resulting from --cached is more subtle: it changes _both_
sides of the diff (default: worktree<->index; --cached: index<->HEAD).
 The names --cached and --staged actually capture this well -- they
basically say "the default is worktree changes, and --cached/--staged
diffs cached/staged changes instead" -- but the name "--index-only"
does not.]

-Miles

-- 
Cat is power.  Cat is peace.