Merge branch 'bg/format-patch-doc-update'

* bg/format-patch-doc-update:
  format-patch: Add "--no-stat" as a synonym for "-p"
  format-patch documentation: Fix formatting
  format-patch documentation: Remove diff options that are not useful
  format-patch: Always generate a patch

diff --combined Documentation/diff-options.txt
index e26b84706f8f29de26036ceec691e8cd6aac4661,8f793825626bedb05b12e58e0f380eec42916213..2b37193a37da9715b0ae4b8aa47c85064694ef8e
--- 1/Documentation/diff-options.txt
--- 2/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@@ -14,7 -14,8 +14,8 @@@ endif::git-format-patch[
  
  ifdef::git-format-patch[]
  -p::
-       Generate patches without diffstat.
+ --no-stat::
+       Generate plain patches without any diffstats.
  endif::git-format-patch[]
  
  ifndef::git-format-patch[]
@@@ -27,33 -28,40 +28,40 @@@ endif::git-format-patch[
  -U<n>::
  --unified=<n>::
        Generate diffs with <n> lines of context instead of
-       the usual three. Implies "-p".
+       the usual three.
+ ifndef::git-format-patch[]
+       Implies `-p`.
+ endif::git-format-patch[]
  
+ ifndef::git-format-patch[]
  --raw::
        Generate the raw format.
        {git-diff-core? This is the default.}
+ endif::git-format-patch[]
  
+ ifndef::git-format-patch[]
  --patch-with-raw::
-       Synonym for "-p --raw".
+       Synonym for `-p --raw`.
+ endif::git-format-patch[]
  
  --patience::
        Generate a diff using the "patience diff" algorithm.
  
  --stat[=width[,name-width]]::
        Generate a diffstat.  You can override the default
-       output width for 80-column terminal by "--stat=width".
+       output width for 80-column terminal by `--stat=width`.
        The width of the filename part can be controlled by
        giving another width to it separated by a comma.
  
  --numstat::
-       Similar to \--stat, but shows number of added and
+       Similar to `\--stat`, but shows number of added and
        deleted lines in decimal notation and pathname without
        abbreviation, to make it more machine friendly.  For
        binary files, outputs two `-` instead of saying
        `0 0`.
  
  --shortstat::
-       Output only the last line of the --stat format containing total
+       Output only the last line of the `--stat` format containing total
        number of modified files, as well as number of added and deleted
        lines.
  
@@@ -61,24 -69,26 +69,26 @@@
        Output the distribution of relative amount of changes (number of lines added or
        removed) for each sub-directory. Directories with changes below
        a cut-off percent (3% by default) are not shown. The cut-off percent
-       can be set with "--dirstat=limit". Changes in a child directory is not
-       counted for the parent directory, unless "--cumulative" is used.
+       can be set with `--dirstat=limit`. Changes in a child directory is not
+       counted for the parent directory, unless `--cumulative` is used.
  
  --dirstat-by-file[=limit]::
-       Same as --dirstat, but counts changed files instead of lines.
+       Same as `--dirstat`, but counts changed files instead of lines.
  
  --summary::
        Output a condensed summary of extended header information
        such as creations, renames and mode changes.
  
+ ifndef::git-format-patch[]
  --patch-with-stat::
-       Synonym for "-p --stat".
-       {git-format-patch? This is the default.}
+       Synonym for `-p --stat`.
+ endif::git-format-patch[]
  
+ ifndef::git-format-patch[]
  -z::
-       NUL-line termination on output.  This affects the --raw
+       NUL-line termination on output.  This affects the `--raw`
        output field terminator.  Also output from commands such
-       as "git-log" will be delimited with NUL between commits.
+       as `git-log` will be delimited with NUL between commits.
  
  --name-only::
        Show only names of changed files.
@@@ -87,13 -97,6 +97,13 @@@
        Show only names and status of changed files. See the description
        of the `--diff-filter` option on what the status letters mean.
  
 +--submodule[=<format>]::
 +      Chose the output format for submodule differences. <format> can be one of
 +      'short' and 'log'. 'short' just shows pairs of commit names, this format
 +      is used when this option is not given. 'log' is the default value for this
 +      option and lists the commits in that commit range like the 'summary'
 +      option of linkgit:git-submodule[1] does.
 +
  --color::
        Show colored diff.
  
@@@ -117,16 -120,19 +127,19 @@@ The regex can also be set via a diff dr
  linkgit:gitattributes[1] or linkgit:git-config[1].  Giving it explicitly
  overrides any diff driver or configuration setting.  Diff drivers
  override configuration settings.
+ endif::git-format-patch[]
  
  --no-renames::
        Turn off rename detection, even when the configuration
        file gives the default to do so.
  
+ ifndef::git-format-patch[]
  --check::
        Warn if changes introduce trailing whitespace
        or an indent that uses a space before a tab. Exits with
        non-zero status if problems are found. Not compatible with
        --exit-code.
+ endif::git-format-patch[]
  
  --full-index::
        Instead of the first handful of characters, show the full
@@@ -134,16 -140,16 +147,16 @@@
        line when generating patch format output.
  
  --binary::
-       In addition to --full-index, output "binary diff" that
-       can be applied with "git apply".
+       In addition to `--full-index`, output a binary diff that
+       can be applied with `git-apply`.
  
  --abbrev[=<n>]::
        Instead of showing the full 40-byte hexadecimal object
        name in diff-raw format output and diff-tree header
        lines, show only a partial prefix.  This is
-       independent of --full-index option above, which controls
+       independent of the `--full-index` option above, which controls
        the diff-patch output format.  Non default number of
-       digits can be specified with --abbrev=<n>.
+       digits can be specified with `--abbrev=<n>`.
  
  -B::
        Break complete rewrite changes into pairs of delete and create.
@@@ -154,6 -160,7 +167,7 @@@
  -C::
        Detect copies as well as renames.  See also `--find-copies-harder`.
  
+ ifndef::git-format-patch[]
  --diff-filter=[ACDMRTUXB*]::
        Select only files that are Added (`A`), Copied (`C`),
        Deleted (`D`), Modified (`M`), Renamed (`R`), have their
@@@ -165,6 -172,7 +179,7 @@@
        paths are selected if there is any file that matches
        other criteria in the comparison; if there is no file
        that matches other criteria, nothing is selected.
+ endif::git-format-patch[]
  
  --find-copies-harder::
        For performance reasons, by default, `-C` option finds copies only
@@@ -176,12 -184,13 +191,13 @@@
        `-C` option has the same effect.
  
  -l<num>::
-       -M and -C options require O(n^2) processing time where n
+       The `-M` and `-C` options require O(n^2) processing time where n
        is the number of potential rename/copy targets.  This
        option prevents rename/copy detection from running if
        the number of rename/copy targets exceeds the specified
        number.
  
+ ifndef::git-format-patch[]
  -S<string>::
        Look for differences that introduce or remove an instance of
        <string>. Note that this is different than the string simply
@@@ -189,18 -198,20 +205,20 @@@
        linkgit:gitdiffcore[7] for more details.
  
  --pickaxe-all::
-       When -S finds a change, show all the changes in that
+       When `-S` finds a change, show all the changes in that
        changeset, not just the files that contain the change
        in <string>.
  
  --pickaxe-regex::
        Make the <string> not a plain string but an extended POSIX
        regex to match.
+ endif::git-format-patch[]
  
  -O<orderfile>::
        Output the patch in the order specified in the
        <orderfile>, which has one shell glob pattern per line.
  
+ ifndef::git-format-patch[]
  -R::
        Swap two inputs; that is, show differences from index or
        on-disk file to tree contents.
@@@ -212,6 -223,7 +230,7 @@@
        not in a subdirectory (e.g. in a bare repository), you
        can name which subdirectory to make the output relative
        to by giving a <path> as an argument.
+ endif::git-format-patch[]
  
  -a::
  --text::
@@@ -236,13 -248,15 +255,15 @@@
        Show the context between diff hunks, up to the specified number
        of lines, thereby fusing hunks that are close to each other.
  
+ ifndef::git-format-patch[]
  --exit-code::
        Make the program exit with codes similar to diff(1).
        That is, it exits with 1 if there were differences and
        0 means no differences.
  
  --quiet::
-       Disable all output of the program. Implies --exit-code.
+       Disable all output of the program. Implies `--exit-code`.
+ endif::git-format-patch[]
  
  --ext-diff::
        Allow an external diff helper to be executed. If you set an

diff --combined builtin-log.c
index ef5b3c3ae393b09f2dfb643ea1dd3bfc623ddc55,06424f3ca8828244df2c959ed99ae898df66b0c0..33fa6ea6c855df904cfcf30f0b413cb8bca61fa9
--- 1/builtin-log.c
--- 2/builtin-log.c
+++ b/builtin-log.c
@@@ -50,12 -50,6 +50,12 @@@ static void cmd_log_init(int argc, cons
        if (default_date_mode)
                rev->date_mode = parse_date_format(default_date_mode);
  
 +      /*
 +       * Check for -h before setup_revisions(), or "git log -h" will
 +       * fail when run without a git directory.
 +       */
 +      if (argc == 2 && !strcmp(argv[1], "-h"))
 +              usage(builtin_log_usage);
        argc = setup_revisions(argc, argv, rev, "HEAD");
  
        if (rev->diffopt.pickaxe || rev->diffopt.filter)
@@@ -927,10 -921,11 +927,11 @@@ int cmd_format_patch(int argc, const ch
                            PARSE_OPT_NOARG | PARSE_OPT_NONEG, keep_callback },
                OPT_BOOLEAN(0, "no-binary", &no_binary_diff,
                            "don't output binary diffs"),
-               OPT_BOOLEAN('p', NULL, &use_patch_format,
-                       "show patch format instead of default (patch + stat)"),
                OPT_BOOLEAN(0, "ignore-if-in-upstream", &ignore_if_in_upstream,
                            "don't include a patch matching a commit upstream"),
+               { OPTION_BOOLEAN, 'p', "no-stat", &use_patch_format, NULL,
+                 "show patch format instead of default (patch + stat)",
+                 PARSE_OPT_NONEG | PARSE_OPT_NOARG },
                OPT_GROUP("Messaging"),
                { OPTION_CALLBACK, 0, "add-header", NULL, "header",
                            "add email header", PARSE_OPT_NONEG,
@@@ -1036,11 -1031,20 +1037,20 @@@
        if (argc > 1)
                die ("unrecognized argument: %s", argv[1]);
  
-       if (use_patch_format)
-               rev.diffopt.output_format |= DIFF_FORMAT_PATCH;
-       else if (!rev.diffopt.output_format ||
-                 rev.diffopt.output_format == DIFF_FORMAT_PATCH)
-               rev.diffopt.output_format = DIFF_FORMAT_DIFFSTAT | DIFF_FORMAT_SUMMARY | DIFF_FORMAT_PATCH;
+       if (rev.diffopt.output_format & DIFF_FORMAT_NAME)
+               die("--name-only does not make sense");
+       if (rev.diffopt.output_format & DIFF_FORMAT_NAME_STATUS)
+               die("--name-status does not make sense");
+       if (rev.diffopt.output_format & DIFF_FORMAT_CHECKDIFF)
+               die("--check does not make sense");
+ 
+       if (!use_patch_format &&
+               (!rev.diffopt.output_format ||
+                rev.diffopt.output_format == DIFF_FORMAT_PATCH))
+               rev.diffopt.output_format = DIFF_FORMAT_DIFFSTAT | DIFF_FORMAT_SUMMARY;
+ 
+       /* Always generate a patch */
+       rev.diffopt.output_format |= DIFF_FORMAT_PATCH;
  
        if (!DIFF_OPT_TST(&rev.diffopt, TEXT) && !no_binary_diff)
                DIFF_OPT_SET(&rev.diffopt, BINARY);
@@@ -1248,9 -1252,6 +1258,9 @@@ int cmd_cherry(int argc, const char **a
                argv++;
        }
  
 +      if (argc > 1 && !strcmp(argv[1], "-h"))
 +              usage(cherry_usage);
 +
        switch (argc) {
        case 4:
                limit = argv[3];
@@@ -1318,9 -1319,8 +1328,9 @@@
  
                if (verbose) {
                        struct strbuf buf = STRBUF_INIT;
 +                      struct pretty_print_context ctx = {0};
                        pretty_print_commit(CMIT_FMT_ONELINE, commit,
 -                                          &buf, 0, NULL, NULL, 0, 0);
 +                                          &buf, &ctx);
                        printf("%c %s %s\n", sign,
                               sha1_to_hex(commit->object.sha1), buf.buf);
                        strbuf_release(&buf);