On Sat, May 5, 2012 at 6:39 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote:
> Scott Chacon <schacon@xxxxxxxxx> 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.
You think he doesn't know about 'git apply' because I'm not listing it
under Basic Snapshotting in the site I put live yesterday? Or because
I'm not teaching that? That makes no sense, I don't understand why
you think I'm to blame for this guy not knowing that. If anything,
this new grouping will help that, since it clearly puts 'apply' under
a section explicitly labeled 'Patching'. It doesn't belong in "Basic
Snapshotting" because that's not at all what it's used for and it
doesn't make sense to put 'diff' under 'Patching' because that's not
it's primary use case - it is mainly used to see what differences are
in various cases, not to create patch files.
> 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...
For one, it's not that I don't care, it's that I don't think that how
you're considering the problem set here is common. I'm trying to make
Git a little bit easier to approach by grouping many of the commands
into groups by the problems they are primarily used to address. If
you can argue that 'diff' is *primarily* used to create patch files
for 'apply' to consume, then I would be happy to argue that, but
that's not what you're saying. You're ignoring my argument that I
believe that 'diff' is used primarily for another use case and that
that use case is closer to 'status' then to 'apply'.
>> ... 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.
There is absolutely no reason to be this condescending. You can read
a similar description of 'apply' in the context of applying patches
produced by 'diff' in my book which is CC licensed and now makes up a
large part of the git-scm.com site here:
http://git-scm.com/book/en/Distributed-Git-Maintaining-a-Project#Applying-Patches-from-E-mail
It is also one of the top results when searching for 'apply' on the
site and it is cross-linked from the git-apply manpage in the sidebar.
It's difficult for me to see how this can be made more clear by me on
this site.
>
> "diff" pairs with "apply", and "format-patch" pairs with "am".
>
If you read on through the next paragraph in that book you will see
this covered as well, as a slightly different use case where the
contributor used 'format-patch' instead.
Or, if you wish, you can read it in German, Japanese, French, Dutch,
Russian, Chinese or Spanish - the languages that have fully translated
my book and are also available on the site. It's difficult to see why
you think I'm making this perceived issue worse.
> 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.
I don't think this is a good idea at all and I've never advocated
this. If people know what GNU 'patch' is they can use that, if people
glance at the new git-scm.com site they should be able to easily see
'git apply' listed under other patch-y workflow tools. What would be
far easier would be for me to simply list 'diff' under both sections,
since what we're really struggling with is the multiple use cases of
the 'diff' command. I think I'll just do that, OK?
Scott
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html