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

From: Nanako Shiraishi <nanako3@lavabit.com>
To: Michael J Gruber <git@drmicha.warpmail.net>
Cc: Felipe Contreras <felipe.contreras@gmail.com>,
	Jonathan Nieder <jrnieder@gmail.com>,
	Junio C Hamano <gitster@pobox.com>,
	git@vger.kernel.org, "J. Bruce Fields" <bfields@fieldses.org>,
	Hannu Koivisto <azure@iki.fi>, Jeff King <peff@peff.net>,
	Wincent Colaiuta <win@wincent.com>,
	Matthias Lederhofer <matled@gmx.net>
Subject: Re: [PATCH v2 0/2] user-manual: new "getting started" section
Date: Sat, 14 Nov 2009 06:06:00 +0900	[thread overview]
Message-ID: <20091114060600.6117@nanako3.lavabit.com> (raw)
In-Reply-To: <4AFBF18E.7070906@drmicha.warpmail.net>

Quoting Michael J Gruber <git@drmicha.warpmail.net>

> Regarding this specific patch series: I took part in the initial
> discussion, and got frustrated by the original poster's seemingly
> unwillingness to accept advice, so I left. I'm not drawing any general
> conclusions, and please don't take this as an ad hominem argument.
> Sometimes it's simply a matter of mismatching participants.

I didn't get myself involved in the follow-up discussion exactly 
for the same reason.

> If you care to go back to that discussion you see that there is good
> reason for having both --cached and --index. They are different. "git
> help cli" explains this nicely.

The need to support both options in the same command (eg. apply) means 
that anybody who says "I don't like 'index' nor 'cache'; why don't we 
change them all to 'stage'" doesn't understand the issue.

But that doesn't mean "apply --cached" vs "apply --index" is the best 
way to let the users specify which operation is requested. 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.

There was a similar discussion about "diff --cached". The command 
compares two things and the current syntax relies on counting the 
number of treeish on the command line to specify what these two things 
are, and sometimes people are confused which way the comparison occurs.

 * If you have two treeish, it compares the two treeish. Specifically, 
   it shows the change to make one treeish into the other treeish.

 * If you have one treeish, it compares the treeish with working tree 
   or the index (it shows the change to make the treeish into working 
   tree or the index). You need --cached to choose the "index", and
   this can safely be aliased to --staged.

 * If you have zero treeish, it compares the index with working tree 
   (it shows the change to make the index into working tree).

But it is also possible to have an alternate syntax to explicitly say
what you are comparing with what. Perhaps these may make it unnecessary
to remember which way the comparison occurs:

 git diff --tree-vs-staged HEAD
	same as "git diff --cached HEAD"
 git diff --staged-vs-tree HEAD
	same as "git diff -R --cached HEAD"

 git diff --staged-vs-working
	same as "git diff"
 git diff --working-vs-staged
	same as "git diff -R"

 git diff --tree-vs-working HEAD
	same as "git diff HEAD"
 git diff --working-vs-tree HEAD
	same as "git diff -R HEAD"

If people like this as a concept we can introduce shorter way to spell 
them, eg. "git diff --ts HEAD", etc.

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