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

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> +'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.