Re: git-scm.com refresh

From: Philip Oakley <philipoakley@iee.org>
Date: May 6, 2012, 08:33 UTC
Message-ID: <C0239E9A908644EAB06A52AE4A90F401@PhilipOakley>
In-Reply-To: <7vwr4q6qbh.fsf@alter.siamese.dyndns.org>

From: "Junio C Hamano" <gitster@pobox.com> Sent: Sunday, May 06, 2012 2:39
AM
 > Scott Chacon <schacon@gmail.com> writes:

Show 22 quoted lines

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

<snip>

Show 7 quoted lines

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

Part of the problem is that the `git diff` man page [1] doesn't actively tell the user that its result will be in a patch format, and that such a patch can be `apply`ed. There are only 5 uses of 'apply' buried in the body text, never as a command, as if they are special cases. There is a section on the -p option, again it feels like it is a special case.

The "--patch" option in [1] is corrupted(?) relative to my desktop in that it misses the "(This is the default.)" ending (which most readers skip over when speed reading).

The normal case of `git diff` for most users is simply as an extended 'what changed' git status.

The `git apply` page [2] does say its about a diff:
    "DESCRIPTION - Reads the supplied diff output (i.e. "a patch") and
    applies it to files."
so it reads ok in reverse.

Perhaps for `git diff` man page
    NAME - git-diff - Show changes/, usually as a patch,/ between commits,
    commit and working tree, etc.

Then
    DESCRIPTION - Show changes ...two files on disk.
     /You can implement a diff patch by using git-apply(1)./

The main point is that the new user is probably unaware of many of the conventions others take for granted. This gives them 'a clue' about `apply`.

Philip

[1] http://git-scm.com/docs/git-diff [2] http://git-scm.com/docs/git-apply.html