• Thomas Rast's avatar
    Documentation: revamp git-cherry(1) · 7c801fbc
    Thomas Rast authored
    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: default avatarThomas Rast <tr@thomasrast.ch>
    Signed-off-by: default avatarJunio C Hamano <gitster@pobox.com>
    7c801fbc
git-cherry.txt 3.53 KB