Re: [PATCH v2 0/2] user-manual: new "getting started" section

From: Nanako Shiraishi <nanako3@lavabit.com>
Date: Nov 17, 2009, 12:06 UTC
Message-ID: <20091117210625.6117@nanako3.lavabit.com>
In-Reply-To: <94a0d4530911161452xe82858el322a1985341bf13c@mail.gmail.com>

Quoting Felipe Contreras <felipe.contreras@gmail.com>

Show 11 quoted lines

> On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
>> ... I don't
>> think Felipe seriously wants to change them to --gogo vs --dance, but
>> if he made a more constructive proposal, instead of making such a
>> comment whose intended effect is only to annoy people, we may see
>> an improved UI at the end.  Proposing "--index-only" vs "--index-too"
>> or even "--stage-only" vs "--stage-too" would have helped him appear
>> to be more serious and constructive and I think your expression
>> "mismatching participants" was a great way to say this.
>
> Right, your explanation is more clear:

You have a funny way of saying "I'm sorry, I wasn't constructive, and my attitude repelled many participants from the discussion".

> the fact that we need both
> doesn't mean we cannot use the term "stage". As to "constructive
> proposal" I deliberately tried to avoid them in case somebody tried to
> disregard it as bike-shedding, and move on.

If the only constructive proposal you could make is to replace words used in two operations without clarifying concepts any better to newbies, then what you are doing is bike-shedding. I don't think trying to hide that by not making any proposal changes that.

> What I'm trying to do is
> bring up the issue that the stage is not user friendly.

I thought you were the one who wanted to use "stage" everywhere?

For what it's worth, "stage" isn't very user friendly to me; maybe it is because I'm not a native English speaker. I'm not saying that when I hear "index" or "cached" I'll understand what they mean even if I didn't have any prior knowledge of git, but I am saying "stage" isn't any better than these two words in that respect. Of course the user needs to understand what it is and how it is used, no matter what word you use.

I think a proposal to replace the word "index" with "stage" will sound nothing but bike-shedding to anybody, especially after getting familiar with "index" and seeing it taught on many web pages and books.

> I like David Kågedal's suggestion more:
> http://kerneltrap.org/mailarchive/git/2008/10/29/3857134

For people who like a usable threaded interface to read the message in context here is its URL.

http://thread.gmane.org/gmane.comp.version-control.git/99332/focus=99401

Yes, I had David's proposal in mind when I wrote my response. Even though the fundamental idea is the same, I used --X-vs-Y option to avoid the problems David's proposal has in a slightly nicer way.

David's proposal introduced two magic tokens STAGE and WORKTREE.

  git diff STAGE WORKTREE   (like "git diff" today)
  git diff HEAD WORKTREE    (like "git diff HEAD" today)
  git diff WORKTREE HEAD    (like "git diff -R HEAD" today)
  git diff HEAD STAGE       (like "git diff --cached" today)
  git diff commit STAGE     (like "git diff --cached commit" today)

This looks nice on surface, but I think the apparent niceness is shallow. If of course has a small problem of introducing an obvious backward incompatibility. You can't use a branch whose name is STAGE anymore, but a deeper problem is that these two magic tokens pretend to be refs. But they do so only to the diff command. I don't see how you can make them sanely be usable to other commands like "git log v1.0.0..WORKTREE".

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/