Re: git-scm.com refresh

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

Scott Chacon <schacon@gmail.com> writes:

>> 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) ...

The other day when I was surfing the 'net, I found a blog that was
complaining about Git UI.  Some of the things were worth listening to, but
there was one item I really had to scratch my head where the misconception
behind the complaint came from.  I am typing from memory without bothering
to go back to the site to quote, but the complaint essentially was:

        Getting a patch is easy with "git diff", but to apply it you need
        to make it an email and feed it to "git am"???  That's crazy.

Of course it *is* crazy, if that were the case. I was wondering why the
obvious "patch" (or "git apply") did not get into the mind of the author,
and I think I now know why.

If the owner of the site that people call "git's home page" does not care
about those who take diffs and apply them as patches, and thinks "git
apply" as a mere implementation detail of "git am", it is understandable
that such a misconception is spread widely to harm users without getting
corrected. Who knows other Git fanboys are spreading misinformation in a
similar way. Sigh...

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

As you are supposed to be one of the top-level Git Teachers, I wish you
knew better.  Here is a free Git lesson.  Consider "git apply" as

    a better version of "patch" that knows how to work better with Git by
    understanding rename and binary patches, and allows them to be applied
    to the working tree and the index (the latter is most useful when the
    patch contains new files)

and teach it as such.

"diff" pairs with "apply", and "format-patch" pairs with "am".

I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
apply", if you think that would make the above pairing more obvious.  Many
computer users know what "patch" does already even they have never used
any SCM.

[Footnote]