Re: git-scm.com refresh

[Scott Chacon <schacon@gmail.com>]

Hey,

On Fri, May 4, 2012 at 6:31 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
> Thanks.  The Reference Manual area lists "apply" in a very funny place.
> It should go together with "diff", whichever section you decide to put
> "diff" in.  As "diff" is listed in "Basic Snapshotting", and it will not
> be able to achieve that without being able to apply its output back to the
> working tree or to the index, I would suggest moving "apply" to the
> section as well.

I have to disagree.  You are thinking of 'apply' from an internals
perspective I have to assume, because I use 'diff' every single day
for all sorts of stuff ("what is modified and unstaged?", "what is
modified and staged?", "what is different between these two branches?"
etc) where I can't think of a single time I've ever used 'apply'.  In
fact, even the times when I have needed to apply a patch generated
from 'diff' I used 'patch -p1' because I know it better.  I, and most
people I would guess, almost never use 'diff' to generate patch files,
we use it to see what has changed before committing or things like
that - in general usage, it's more like an advanced 'status' honestly.

> I am fairly happy about the look of the new site except for a few things
> ;-).
>
> It seems that you are trying to advocate "staging area" as some sort of
> official term.  I think "it is like a staging area" is a good phrase to
> use when answering "what is the index?", but I think repeating it million
> times without telling the casual readers what its official name is is
> counterproductive.  Don't do that.  It will confuse these same people when
> they start reading manuals.

I'm not really trying to advocate it as much as using terminology that
is already quite popular.  It's true that it's not what is used in the
man pages, but neither is 'index' used consistently - there is 'cache'
too, in addition to 'index' having two meanings - packfile and cache.
I'm open to making things clearer, but I just don't think that
changing the terminology to something more technical and vague would
be overall less confusing to people.

That said, in most places I use phrases like 'Git has something called
the "staging area" or "index"' letting people know that there are
multiple phrases for it and what it's technical term tends to be.  So
your "without telling the casual readers what its official name is" is
generally not true - I do try to do that too.

Scott