Documentation: revamp git-cherry(1)
commit7c801fbc74d4c4687ea6db60e24a67f896767824
authorThomas Rast <tr@thomasrast.ch>
Fri, 22 Nov 2013 16:29:16 +0000 (22 17:29 +0100)
committerJunio C Hamano <gitster@pobox.com>
Wed, 27 Nov 2013 20:16:49 +0000 (27 12:16 -0800)
tree9c58bae06a4fc727824a3a787100441bb3472f51
parentccba805681b1b3c3ce4f053f20171b04ced2037a
Documentation: revamp git-cherry(1)

git-cherry(1)'s "description" section has never really managed
to explain to me what the command does.  It contains too much
explanation of the algorithm instead of simply saying what
goals it achieves, and too much terminology that we otherwise
do not use (fork-point instead of merge-base).

Try a much more concise approach: state what it finds out, why
this is neat, and how the output is formatted, in a few short
paragraphs.  In return, provide much longer examples of how it
fits into a "format-patch | am" based workflow, and how it
compares to reading the same from git-log.

Also carefully avoid using "merge" in a context where it does
not mean something that comes from git-merge(1).  Instead, say
"apply" in an attempt to further link to patch workflow
concepts.

While there, also omit the language about _which_ upstream
branch we treat as the default.  I literally just learned that
we support having several, so let's not confuse new users
here, especially considering that git-config(1) does not
document this.

Prompted-by: a.huemer@commend.com on #git
Signed-off-by: Thomas Rast <tr@thomasrast.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-cherry.txt