git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Scott Chacon <schacon@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: git list <git@vger.kernel.org>
Subject: Re: git-scm.com refresh
Date: Sat, 5 May 2012 20:51:07 -0700	[thread overview]
Message-ID: <CAP2yMaJwT6=hEwt+v2OHB8yDdXQzV2P1kAimkN_a6GHtqkRJkQ@mail.gmail.com> (raw)
In-Reply-To: <7vwr4q6qbh.fsf@alter.siamese.dyndns.org>

On Sat, May 5, 2012 at 6:39 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

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

  parent reply	other threads:[~2012-05-06  3:52 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2012-05-04 23:29 Scott Chacon
2012-05-05  0:26 ` Jakub Narebski
2012-05-05 22:24   ` Scott Chacon
2012-05-05 23:20   ` Josh Juran
2012-05-05  1:31 ` Junio C Hamano
2012-05-05 16:47   ` Felipe Contreras
2012-05-05 22:38   ` Scott Chacon
2012-05-06  1:39     ` Junio C Hamano
2012-05-06  2:31       ` Felipe Contreras
2012-05-06  3:51       ` Scott Chacon [this message]
2012-05-06  8:33       ` Philip Oakley
2012-05-07 17:06         ` Junio C Hamano
2012-05-08 16:51           ` Junio C Hamano
2012-05-08 17:46             ` Andreas Schwab
2012-05-08 18:00               ` Junio C Hamano
2012-05-05  9:14 ` Andrew Sayers
2012-05-05 14:01 ` Felipe Contreras
2012-05-05 14:36 ` Philip Oakley
2012-05-06  0:08 ` Neal Kreitzinger
2012-05-06  5:10 ` Neal Kreitzinger
2012-05-06 11:04 ` Matthieu Moy
2012-05-06 13:36   ` Scott Chacon
2012-05-07  4:18 ` Christian Couder
2012-05-07 17:08   ` Ævar Arnfjörð Bjarmason
2012-05-07 15:08 ` A Large Angry SCM
2012-05-07 21:04 ` Matthieu Moy
2012-05-09 22:13   ` Heiko Voigt
2012-05-08 12:29 ` Antonio Ospite

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAP2yMaJwT6=hEwt+v2OHB8yDdXQzV2P1kAimkN_a6GHtqkRJkQ@mail.gmail.com' \
    --to=schacon@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --subject='Re: git-scm.com refresh' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).