[PATCH v4] Remove --allow-empty from the git-commit synopsis

The --allow-empty option is too rarely used to warrant being displayed
in the SYNOPSIS. It should only be mentioned in the main body of the
documentation like --porcelain.

Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---

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

Corrected.

Please don't cite marc

Sorry, I'm new here and there was no mention of this in
Documentation/SubmittingPatches. I looked through `git log' for the
project and found 10 such links in other commit messages.

Now that I look closer there are 14 references to some `Message-ID:',
but of course someone getting it wrong in the past doesn't mean that
it's a good idea to follow their example. I won't cite marc.info
again.

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

Yes I misread (or rather, mis-recalled) the content of his message. He
was indeed talking about `git commit -h' output, but I subsequently
updated my --allow-empty-message patch to omit it from the SYNOPSIS
for git-commit(1). I've removed the links to `marc.info' (or any
Message-ID's) since they aren't pertinent anymore.

The relatively obscure --allow-empty* options should regardless of
that misunderstanding probably be omitted from the SYNOPSIS
section. It would reduce the cognitive load of the casual manual
reader who's trying to get an idea of the most common usage for the
command.

As for Jeff's suggestion of omitting options from the `--help' output:
I couldn't find a way to do that using parse-options.[ch]. It's also
customary for `--help' to include the full usage examples regardless
of how long they get (just look at wget, ls etc.). The SYNOPSIS
sections in manual pages by comparison usually aim for brevity.

 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>...]
 
 DESCRIPTION
 -----------

-- 
1.7.0.4.298.gc81d