From: Paul Tan <pyokagan@gmail.com>
Date: Wed, 01 Jul 2015 10:22:33 GMT
Subject: Re: [PATCH v4 28/44] builtin-am: pass git-apply's options to git-apply
Message-ID: <CACRoPnTeg08nJfMw6Lh6RUAOaKsSx30-=hhj2QD7_bPfKTHtTQ@mail.gmail.com>
In-Reply-To: <CAGZ79kbzwv8m47t5W+1djFEWGL_X1nHPf7FWcwcKAZ34oFszxg@mail.gmail.com>

On Tue, Jun 30, 2015 at 7:56 AM, Stefan Beller <sbeller@google.com> wrote:
> I realize this was in am.sh as well, but I find the help strings a bit
> unfortunate.
> (Yes, you actually need to look them up at another place as most people are
> not familiar with the apply options).

Yeah I agree, it would be an improvement. I think the same can be said
for git-mailinfo's and git-mailsplit's options. e.g. "pass -k flag to
git-mailinfo" is not very descriptive either, so we should change
their help strings as well.

Since git-am combines most of the options from git-mailsplit,
git-mailinfo and git-apply together, I wonder if we should split their
options into different groups, e.g:

usage: git am [options] [(<mbox>|<Maildir>)...]
   or: git am [options] (--continue | --skip | --abort)

    -i, --interactive     run interactively
    -3, --3way            allow fall back on 3way merging if needed
    -q, --quiet           be quiet
    -s, --signoff         add a Signed-off-by line to the commit message
    --patch-format <format>
                          format the patch(es) are in
    --resolvemsg ...      override error message when patch failure occurs
    --continue            continue applying patches after resolving a conflict
    -r, --resolved        synonyms for --continue
    --skip                skip the current patch
    --abort               restore the original branch and abort the
patching operation.
    --committer-date-is-author-date
                          lie about committer date
    --ignore-date         use current timestamp for author date
    --rerere-autoupdate   update the index with reused conflict
resolution if possible
    -S, --gpg-sign[=<key-id>]
                          GPG-sign commits

options for git-mailsplit
    --keep-cr             pass --keep-cr flag to git-mailsplit for mbox format
    --no-keep-cr          do not pass --keep-cr flag to git-mailsplit
independent of am.keepcr

options for git-mailinfo
    -u, --utf8            recode into utf8 (default)
    -m, --message-id      pass -m flag to git-mailinfo
    -c, --scissors        strip everything before a scissors line
    -k, --keep            pass -k flag to git-mailinfo
    --keep-non-patch      pass -b flag to git-mailinfo

options for git-apply
    --whitespace <action>
                          detect new or modified lines that have
whitespace errors
    --ignore-space-change
                          ignore changes in whitespace when finding context
    --ignore-whitespace   ignore changes in whitespace when finding context
    --directory <root>    prepend <root> to all filenames
    --exclude <path>      don't apply changes matching the given path
    --include <path>      apply changes matching the given path
    -C <n>                ensure at least <n> lines of context match
    -p <num>              remove <num> leading slashes from
traditional diff paths
    --reject              leave the rejected hunks in corresponding *.rej files

We may wish to put these changes in their own preparatory patch series though.

What do you think?

Regards,
Paul