Re: [PATCH] git-rev-list.txt: prune options in synopsis

From: Philip Oakley <philipoakley@iee.email>
Date: Oct 11, 2019, 16:02 UTC
Message-ID: <c9e7fbd6-7ad6-bce9-1e17-6391ab3e0630@iee.email>
In-Reply-To: <20191011060457.GC20094@sigill.intra.peff.net>

On 11/10/2019 07:04, Jeff King wrote:

Show 22 quoted lines

> On Fri, Oct 04, 2019 at 05:13:08PM -0700, Denton Liu wrote:
>
>> The synopsis section in git-rev-list.txt has grown to be a huge list
>> that probably needs its own synopsis. Since the list is huge, users may
>> be given the false impression that the list is complete, however it is
>> not. It is missing many of the available options.
>>
>> Since the list of options in the synopsis is not only annoying but
>> actively harmful, replace it with `[<options>]` so users know to
>> explicitly look through the documentation for further information.
>>
>> While we're at it, update the optional path notation so that it is more
>> modern.
> Yes, thank you! This has bugged me for a while. I suspect there are
> other pages that could use similar treatment, but I don't mind at all
> doing it incrementally.
>
> (One of them is git-branch, where I think the synopsis should focus on
> showing the major modes and not listing every possible branch-listing
> option).
>
> -Peff

I'd agree that simplifying the rev-list page is good.

Another case, of a different style, is that of `git bundle --all` which does need mentioning that particular rev-list option as a major usage (I couldn't manage to understand the three layers of man page that needed reading).

I had proposed a patch many years ago [1] but the feedback wasn't positive, though my SO question continues [2] to get votes.

Philip

[1] https://public-inbox.org/git/1348010734-664-2-git-send-email-philipoakley@iee.org/ [2] https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo