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

From: Miles Bader <miles@gnu.org>
Date: Jun 13, 2011, 04:46 UTC
Message-ID: <BANLkTikUOXwN9YrC25_mo2z5EWcsjrkg7A@mail.gmail.com>
In-Reply-To: <buotybu2wx7.fsf@dhlpc061.dev.necel.com>

On Mon, Jun 13, 2011 at 4:11 AM, Miles Bader <miles@gnu.org> wrote:

Show 5 quoted lines

>> Do you think it would be valuable to introduce --added as a synonym
>> for --cached and slowly steer documentation to encourage the latter
>> in place of the former?
>
> "--added" sounds very awkward though; "--staged" is much more natural.

I should note _why_ this is so:

The main problem is well-known -- that "git add" is a bit overloaded and slightly awkward in some case (e.g., to remove a file, you need to add it...). But whatever, it works well enough, because people are used to it.

However in the case of git diff, if one sees "git diff --added", it sounds like it means "show me a diff of added files" -- but the term "added files" is ambiguous; and the fact that "git add" is in fact, overloaded with multiple meanings doesn't really help, the basic ambiguity makes "git diff --added" awkward and unclear.

A far better way would be to (1) make "git diff --staged" an alias for "git-diff --cached" (2) start promoting "git stage" in documentation, instead of "git add".

-Miles

-- 
Cat is power.  Cat is peace.