Re: [PATCH] git-rev-list.txt: prune options in synopsis
On Fri, Oct 11, 2019 at 05:02:33PM +0100, Philip Oakley wrote: > 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. Yeah, I agree that "git bundle" could be more clear about this. I think just adding an example like this might help: # generate a bundle similar to what "git clone" would produce git bundle create file.bundle --branches --tags -Peff
Re: [PATCH] git-rev-list.txt: prune options in synopsis
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-philipoak...@iee.org/ [2] https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo
Re: [PATCH] git-rev-list.txt: prune options in synopsis
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
Re: [PATCH] git-rev-list.txt: prune options in synopsis
Denton Liu writes: > 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. I am not sure listing only the most often used ones is harmful. It indeed is annoying and it is a good idea to shrink it down like this patch does. Thanks.
