Re: [PATCH v2] Remove --allow-empty from the git-commit synopsis

[Junio C Hamano <gitster@pobox.com>]

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> The --allow-empty option is too rarley used to warrant being displayed
> in the SYNOPSIS. It should only be mentioned in the main body of the
> documentation like --porcelain.
>
> The issue was raised in the thread discussing the new
> --allow-empty-message option by Jeff King <peff@peff.net>:

If you mention what Peff said, it would be nice to Cc: him.

>     http://marc.info/?l=git&m=127039258902941
>     http://marc.info/?l=git&m=127054334121604

Please don't cite marc, especially when you refer to a thread or a patch.
Their interface, even in the "raw" mode, does not give the message headers
(presumably by design, in order to block e-mail address harvesters) that
makes it unusable to get patches out of for applying.

Giving a message-ID would be vendor neutral and a useful alternative
instead, like so:

    Message-ID: <20100406055530.GE3901@coredump.intra.peff.net>

Then people can paste it after "http://mid.gmane.org/" or feed it to their
favourite MUA.

>  Documentation/git-commit.txt |    5 ++---
>  1 files changed, 2 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 64fb458..ed2cd95 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -10,9 +10,8 @@ SYNOPSIS
>  [verse]
>  'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run]
>  	   [(-c | -C) <commit>] [-F <file> | -m <msg>] [--reset-author]
> -	   [--allow-empty] [--no-verify] [-e] [--author=<author>]
> -	   [--date=<date>] [--cleanup=<mode>] [--status | --no-status] [--]
> -	   [[-i | -o ]<file>...]
> +	   [--no-verify] [-e] [--author=<author>] [--date=<date>]
> +	   [--cleanup=<mode>] [--status | --no-status] [--] [[-i | -o ]<file>...]

I do not think Jeff was against having a complete listing in the
documentation.  Wasn't his suggestion about "git commit -h" output?