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

From: Junio C Hamano <[email-masked]>
Date: Sun, 13 Mar 2022 19:00:39 +0000

Bagas Sanjaya <[email-masked]> 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.