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

From: Nanako Shiraishi <nanako3@lavabit.com>
Date: Nov 13, 2009, 21:06 UTC
Message-ID: <20091114060600.6117@nanako3.lavabit.com>
In-Reply-To: <4AFBF18E.7070906@drmicha.warpmail.net>

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

Show 5 quoted lines

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