git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] repack: Sync list of options between synopsis and description in the documentation

From
Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
Date
Mar 9, 2022, 13:17 UTC
Message-ID
<CAJyCBORGGbn6d5UYMdRnfrbn9OONcgMMxaCyJ4qUoQY3+s8-uQ@mail.gmail.com>
In-Reply-To
<20220309123447.852883-1-bagasdotme@gmail.com>
On Wed, Mar 9, 2022 at 9:01 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
Show 30 quoted lines
>
> Options list in the synopsis and description section of git-repack(1)
> are out of sync. The latest addition was in commit 1d89d88d37
> (builtin/repack.c: support writing a MIDX while repacking, 2021-09-28),
> which only adds -m/--write-midx option.
>
> Add missing options to the synopsis. Additionaly, sort according to the
> order they appear in the description.
>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/git-repack.txt | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
> index ee30edc178..26e997bde1 100644
> --- a/Documentation/git-repack.txt
> +++ b/Documentation/git-repack.txt
> @@ -9,7 +9,13 @@ git-repack - Pack unpacked objects in a repository
>  SYNOPSIS
>  --------
>  [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' [-a] [-A] [-d] [-l] [-f] [-F] [-q | --quiet] [-n] [--window=<n>]
> +            [--depth=<n>] [--threads=<n>] [--window-memory=<n>]
> +            [--max-pack-size=<n>] [-b | --write-bitmap-index]
> +            [--pack-kept-objects] [--keep-pack=<pack-name>]
> +            [--unpack-unreachable=<when>] [-k | --keep-unreachable]
> +            [-i | --delta-islands] [-g | --geometric <factor>]
> +            [-m | --write-midx]
Could we possibly just shorten the synopsis to something like this?
"git repack [<options>]"

As Junio mentioned here [1], this could be a more "modern" style? Since the OPTIONS chunk below gives a more detailed usage, I think we can get rid of the redundancy in the SYNOPSIS. And it also helps with the aesthetic and clarity.

[1]: https://lore.kernel.org/git/xmqq1r0awse5.fsf@gitster.g/
-- 
Thanks & Regards,
Shaoxuan
Previous: Bagas Sanjaya
Message 2 of 2 in “repack: Sync list of options between synopsis and description in the documentation”
  1. repack: Sync list of options between synopsis and description in the documentationBagas Sanjaya, Mar 9, 2022
  2. Shaoxuan YuanMar 9, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.