Re: [PATCH] Documentation: simplify synopsis of git-repack(1)

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 13, 2022, 19:00 UTC
Message-ID: <xmqqsfrlvfs8.fsf@gitster.g>
In-Reply-To: <20220312113136.26716-1-bagasdotme@gmail.com>

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Simplify SYNOPSIS section to only mention [<options>...] placeholder.
> Redundant options list can now be avoided for aesthetic and clarity.

The "git cmd --help" output is meant to be readable and useful, so clarity is good, but I do not know much about aesthetics.

More importantly, the above does not answer a lot more important question. Is it just loss of duplicated information that this commit brings in? Isn't the motivation that "not all options are listed in SYNOPSIS section, and/or some options listed there are not described in the body text and are not supported"? And instead of trying to keep them in sync, the author chose to simplify SYNOPSIS and have readers look options up in the body text, no? These two would make a good pair of "what problem do we solve?" and "how we choose to solve it?".

>  [verse]
> -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]
> +'git repack' [<options>...]

Unlike commands with multiple "operation modes", "repack" does one thing and only one thing, so a single-liner "git repack <options>" may work well.