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 <avarab@xxxxxxxxx> --- > 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html