From: "Junio C Hamano" <gitster@xxxxxxxxx> Sent: Sunday, May 06, 2012 2:39
AM
> 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.
<snip>
"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
--
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