Re: git diff --added (Re: Command-line interface thoughts)

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 13, 2011, 12:55 UTC
Message-ID: <7vhb7triu8.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110613080617.GC4570@elie>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 7 quoted lines

> -Show changes between the working tree and the index or a tree, changes
> -between the index and a tree, changes between two trees, or changes
> -between two files on disk.
> +The primary purpose of 'git diff' is to compare files in the working
> +tree to stored versions in the repository.  It can also be used to
> +show changes between the index and a tree, changes between two trees,
> +or changes between two files on disk.

I agree that it is a good idea to clarify whatever likely misunderstanding new people might have, and I further agree that to some people the command line syntax of diff to compare a tree with the index or with the working tree may look like a different "modes" from the syntax to compare two tree-ish.

I however am not sure it is a good idea to declare "comparing the index with the working tree" is the "primary". People who are just starting out, just downloading and sightseeing, are likely to use "git clone" followed by "git diff v2.6.39 v3.0", I suspect, and to them, the primary use would be to compare two revisions, no?

Instead of making them sound as if they are different "modes", I think it may make more sense to teach them upfront that in addition to the two "modes" they may be familiar with from their past experiences with other SCMs, namely, comparing two revisions and comparing a revision with the working tree, there are two extra pairs they could be comparing in git, namely, comparing the index (the data you prepared for your next commit) with the working tree, and comparing the index with a revision.

	Side note: note that even in the context of other SCMs, the choice
	the user makes when using "diff" is not about what two things to
	compare, i.e. "scm diff REV1 WTREE" vs "scm diff REV1 REV2". They
	choose two "modes" and then fill in the parameter(s) the chosen
	mode requires. When comparing two revs, you need two revs; when
	comparing a rev with the working tree, you need one rev, and
	worktree does not have to be specified. That way, you do not
	explicitly specify which "mode" you are using, as that can be
	inferred from the command line.

	But if we do not call these two "modes", I do not see a reason for
	us to call two extra pairs git gives them "modes" either.

Then if you feel "comparing the index with the working tree" the most important combination, start your description from that "mode".

For the reason I stated in the other message, I think it was a wise decision not to advertise "diff --staged" synonym when we introduced it at 2baf185 (git-diff: Add --staged as a synonym for --cached., 2008-10-29), by the way.