From: Mark Lodato <lodatom@gmail.com>
Date: Fri, 05 Nov 2010 01:57:16 GMT
Subject: Re: [PATCH] docs: clarify git diff modes of operation
Message-ID: <AANLkTimqA=2+fG10mP=zmXHksHvr6iVZQHRE85ab-aMV@mail.gmail.com>
In-Reply-To: <20101104215056.GA18475@burratino>

On Thu, Nov 4, 2010 at 5:50 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> .  So I guess technically the separate operation modes are
>
>        git diff [--cached]
>        git diff [--cached] <tree>
>        git diff <tree> <tree>
>        git diff --no-index <path> <path>
>        git diff <blob> <blob>
>
> where --cached means "use the version of the work tree stored
> in the index in place of the real thing".

I prefer this above the other proposals.  This breakdown makes the
most sense to me, and I see no reason to use <commit> when we really
mean <tree>.  One minor thing: should the "<blob> <blob>" form be
moved above "<path> <path>" so that all the git object forms are
together?

On a related note, I find it a bit confusing that <path> is used to
mean two very different things.  For "<path> <path>", it means a file
that must exist on disk.  For "[<path>...]", it means a pattern on
which to filter the output of the command.  Since we already have a
name for the latter, perhaps we should use the term "[<pathspec>...]".