Re: [PATCH] filter-branch: add --prune-empty to option summary

[Jeff King <peff@peff.net>]

On Thu, Oct 01, 2009 at 08:52:11PM -0400, Adam Brewster wrote:

> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index 451950b..2cc3bd8 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -12,6 +12,7 @@ SYNOPSIS
>  	[--index-filter <command>] [--parent-filter <command>]
>  	[--msg-filter <command>] [--commit-filter <command>]
>  	[--tag-name-filter <command>] [--subdirectory-filter <directory>]
> +	[--prune-empty]
>  	[--original <namespace>] [-d <directory>] [-f | --force]
>  	[--] [<rev-list options>...]

Thanks. This makes sense given the existing structure, though I have to
wonder how useful some of these gigantic synopses really are. Do we
really need to list all of the options here in a cluttered, annoyingly
wrapped format, when we are just going to list them in a nice
easy-to-read format with their descriptions later on in the page?

And this is really not so much to do with your patch as a meta-rant, so
feel free to stop reading.

What should the synopsis really be communicating? In something like
git-cat-file(1), the synopsis nicely shows a few key facts:

  1. There are two "modes" if invocation.

  2. In one mode, you give an action and an object on the command line.

  3. In the other mode, you give --batch and feed some stuff over stdin.

Those are all useful pieces of information, and they are communicated
more quickly than they would be by forcing me to read the
paragraph-formatted text of the description section.

But look at the 18-line synopsis for git-grep or the 17-line one for
git-format-patch. Are they really helping anyone? (And it is not just
the line count. The 18-line synopsis for git-config is actually useful,
because there really are 18 modes of operation).

Non-git programs seem to take a more sparse approach. For example, some
one-line synopses from my system:

       sed [OPTION]... {script-only-if-no-other-script} [input-file]...
       ls [OPTION]... [FILE]...

or even this longer one:

       vim [options] [file ..]
       vim [options] -
       vim [options] -t tag
       vim [options] -q [errorfile]

Those all communicate some useful information (how to generally invoke
the program) cluttering it with redundant information.

-Peff