From: Philip Oakley Date: Sun, 06 May 2012 08:33:10 GMT Subject: Re: git-scm.com refresh Message-ID: In-Reply-To: <7vwr4q6qbh.fsf@alter.siamese.dyndns.org> From: "Junio C Hamano" Sent: Sunday, May 06, 2012 2:39 AM > Scott Chacon 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. > > "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