Re: [RFC/PATCH 5/4] Documentation: flesh out diff --no-index description

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 13, 2010, 22:40 UTC
Message-ID: <7vtykphg2q.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20101011160718.GF25842@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 12 quoted lines

> +'git diff' [--options] --no-index [--] <path> <path>::
> +
> +	In this form, 'git diff' will compare a pair of files or
> +	directories that are not necessarily being managed by git.
> +	The tracked content of files in the index and the object
> +	database are ignored.
> ++
> +In other words, this form allows 'git diff' to be used as a
> +traditional 'diff' command (plus the familiar extras like --check,
> +color, pagination, automatic use of -r, --stat/--name-status,
> +--pickaxe, --binary, copy/rename detection, -Oorderfile, and
> +--patience).

My initial knee-jerk reaction was "how would -C/-M/-O be useful when you can only give two paths?" Perhaps it would become easier to read if we phrased it like this?

    This form allows 'git diff' to be used as a better 'diff' command,
    with extras like whitespace checks (--check), coloring (--color),
    wordwise diff (--color-words), pagination, diffstat (--stat), binary
    patch (--binary), alternative algorithm (e.g. --patience).  In
    addition, when comparing two directories, rename detection (-M) may
    come in handy.

Note, by the way, that I didn't verify all the claims the above makes.