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

From: Jeff King <peff@peff.net>
Date: Oct 2, 2009, 07:45 UTC
Message-ID: <20091002074537.GA27664@coredump.intra.peff.net>
In-Reply-To: <1254444731-6852-1-git-send-email-adambrewster@gmail.com>

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

Show 11 quoted lines

> 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