From: Philip Oakley Date: Fri, 11 Oct 2019 16:02:33 GMT Subject: Re: [PATCH] git-rev-list.txt: prune options in synopsis Message-ID: In-Reply-To: <20191011060457.GC20094@sigill.intra.peff.net> On 11/10/2019 07:04, Jeff King wrote: > 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 `[]` 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