From: Jeff King <peff@peff.net>
Date: Fri, 11 Oct 2019 06:04:57 GMT
Subject: Re: [PATCH] git-rev-list.txt: prune options in synopsis
Message-ID: <20191011060457.GC20094@sigill.intra.peff.net>
In-Reply-To: <645cc54c4c86493c855ec6b0b892a0bc8e999249.1570234118.git.liu.denton@gmail.com>

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