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 `[<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-philipoak...@iee.org/
[2]
https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo
