{"thread":{"id":"51975","subject":"[PATCH] git-rev-list.txt: prune options in synopsis","startedAt":"2019-10-05T00:13:14Z","lastAt":"2019-10-11T16:11:14Z","messageCount":5,"participants":["Denton Liu","Junio C Hamano","Jeff King","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"383457","messageId":"645cc54c4c86493c855ec6b0b892a0bc8e999249.1570234118.git.liu.denton@gmail.com","threadId":"51975","inReplyTo":null,"subject":"[PATCH] git-rev-list.txt: prune options in synopsis","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-10-05T00:13:08Z","receivedAt":"2019-10-05T00:13:14Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"The synopsis section in git-rev-list.txt has grown to be a huge list\nthat probably needs its own synopsis. Since the list is huge, users may\nbe given the false impression that the list is complete, however it is\nnot. It is missing many of the available options.\n\nSince the list of options in the synopsis is not only annoying but\nactively harmful, replace it with `[]` so users know to\nexplicitly look through the documentation for further information.\n\nWhile we're at it, update the optional path notation so that it is more\nmodern.\n\nSigned-off-by: Denton Liu \n---\nI initially wrote a patch to document --children in the synopsis\nalongside --parents. However, I quickly realised that --children was\nonly one of many missing options. Other options included:\n\n\t--since\n\t--after\n\t--until\n\t--before\n\t--show-notes\n\t--all-match\n\t--invert-grep\n\t--basic-regexp\n\t--perl-regexp\n\t--exclude\n\t--reflog\n\t--alternate-refs\n\t--single-worktree\n\t--boundary\n\t--progress\n\t--simplify-by-decoration\n\t... stopped checking here\n\nso I decided it wasn't worth it to keep this list around if it's so\nincomplete when even the porcelain git-log.txt doesn't carry a huge list\nin the synopsis.\n\nI went through and manually checked each option to ensure that there was\na corresponding option in either rev-list-options.txt or\npretty-options.txt so we shouldn't lose any information by deleting this\nlist.\n\n Documentation/git-rev-list.txt | 54 +---------------------------------\n 1 file changed, 1 insertion(+), 53 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 9392760b25..025c911436 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -9,59 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order\n SYNOPSIS\n --------\n [verse]\n-'git rev-list' [ --max-count= ]\n-\t [ --skip= ]\n-\t [ --max-age= ]\n-\t [ --min-age= ]\n-\t [ --sparse ]\n-\t [ --merges ]\n-\t [ --no-merges ]\n-\t [ --min-parents= ]\n-\t [ --no-min-parents ]\n-\t [ --max-parents= ]\n-\t [ --no-max-parents ]\n-\t [ --first-parent ]\n-\t [ --remove-empty ]\n-\t [ --full-history ]\n-\t [ --not ]\n-\t [ --all ]\n-\t [ --branches[=] ]\n-\t [ --tags[=] ]\n-\t [ --remotes[=] ]\n-\t [ --glob= ]\n-\t [ --ignore-missing ]\n-\t [ --stdin ]\n-\t [ --quiet ]\n-\t [ --topo-order ]\n-\t [ --parents ]\n-\t [ --timestamp ]\n-\t [ --left-right ]\n-\t [ --left-only ]\n-\t [ --right-only ]\n-\t [ --cherry-mark ]\n-\t [ --cherry-pick ]\n-\t [ --encoding= ]\n-\t [ --(author|committer|grep)= ]\n-\t [ --regexp-ignore-case | -i ]\n-\t [ --extended-regexp | -E ]\n-\t [ --fixed-strings | -F ]\n-\t [ --date=]\n-\t [ [ --objects | --objects-edge | --objects-edge-aggressive ]\n-\t [ --unpacked ]\n-\t [ --object-names | --no-object-names ]\n-\t [ --filter= [ --filter-print-omitted ] ] ]\n-\t [ --missing= ]\n-\t [ --pretty | --header ]\n-\t [ --bisect ]\n-\t [ --bisect-vars ]\n-\t [ --bisect-all ]\n-\t [ --merge ]\n-\t [ --reverse ]\n-\t [ --walk-reflogs ]\n-\t [ --no-walk ] [ --do-walk ]\n-\t [ --count ]\n-\t [ --use-bitmap-index ]\n-\t ... [ \\-- ... ]\n+'git rev-list' [] ... [[--] ...]\n \n DESCRIPTION\n -----------\n-- \n2.23.0.687.g391267506c\n\n"},{"id":"383463","messageId":"xmqqmuef7e87.fsf@gitster-ct.c.googlers.com","threadId":"51975","inReplyTo":"645cc54c4c86493c855ec6b0b892a0bc8e999249.1570234118.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-rev-list.txt: prune options in synopsis","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-10-05T09:07:04Z","receivedAt":"2019-10-05T09:07:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu writes:\n\n> The synopsis section in git-rev-list.txt has grown to be a huge list\n> that probably needs its own synopsis. Since the list is huge, users may\n> be given the false impression that the list is complete, however it is\n> not. It is missing many of the available options.\n>\n> Since the list of options in the synopsis is not only annoying but\n> actively harmful, replace it with `[]` so users know to\n> explicitly look through the documentation for further information.\n\nI am not sure listing only the most often used ones is harmful. It\nindeed is annoying and it is a good idea to shrink it down like this\npatch does.\n\nThanks.\n\n"},{"id":"383876","messageId":"20191011060457.GC20094@sigill.intra.peff.net","threadId":"51975","inReplyTo":"645cc54c4c86493c855ec6b0b892a0bc8e999249.1570234118.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-rev-list.txt: prune options in synopsis","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-10-11T06:04:57Z","receivedAt":"2019-10-11T06:04:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 04, 2019 at 05:13:08PM -0700, Denton Liu wrote:\n\n> The synopsis section in git-rev-list.txt has grown to be a huge list\n> that probably needs its own synopsis. Since the list is huge, users may\n> be given the false impression that the list is complete, however it is\n> not. It is missing many of the available options.\n> \n> Since the list of options in the synopsis is not only annoying but\n> actively harmful, replace it with `[]` so users know to\n> explicitly look through the documentation for further information.\n> \n> While we're at it, update the optional path notation so that it is more\n> modern.\n\nYes, thank you! This has bugged me for a while. I suspect there are\nother pages that could use similar treatment, but I don't mind at all\ndoing it incrementally.\n\n(One of them is git-branch, where I think the synopsis should focus on\nshowing the major modes and not listing every possible branch-listing\noption).\n\n-Peff\n"},{"id":"383898","messageId":"c9e7fbd6-7ad6-bce9-1e17-6391ab3e0630@iee.email","threadId":"51975","inReplyTo":"20191011060457.GC20094@sigill.intra.peff.net","subject":"Re: [PATCH] git-rev-list.txt: prune options in synopsis","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2019-10-11T16:02:33Z","receivedAt":"2019-10-11T16:02:38Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 11/10/2019 07:04, Jeff King wrote:\n> On Fri, Oct 04, 2019 at 05:13:08PM -0700, Denton Liu wrote:\n>\n>> The synopsis section in git-rev-list.txt has grown to be a huge list\n>> that probably needs its own synopsis. Since the list is huge, users may\n>> be given the false impression that the list is complete, however it is\n>> not. It is missing many of the available options.\n>>\n>> Since the list of options in the synopsis is not only annoying but\n>> actively harmful, replace it with `[]` so users know to\n>> explicitly look through the documentation for further information.\n>>\n>> While we're at it, update the optional path notation so that it is more\n>> modern.\n> Yes, thank you! This has bugged me for a while. I suspect there are\n> other pages that could use similar treatment, but I don't mind at all\n> doing it incrementally.\n>\n> (One of them is git-branch, where I think the synopsis should focus on\n> showing the major modes and not listing every possible branch-listing\n> option).\n>\n> -Peff\nI'd agree that simplifying the rev-list page is good.\n\nAnother case, of a different style, is that of `git bundle --all` which \ndoes need mentioning that particular rev-list option as a major usage (I \ncouldn't manage to understand the three layers of man page that needed \nreading).\n\nI had proposed a patch many years ago [1] but the feedback wasn't \npositive, though my SO question continues [2] to get votes.\n\nPhilip\n\n[1] \nhttps://public-inbox.org/git/1348010734-664-2-git-send-email-philipoakley@iee.org/\n[2] \nhttps://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo\n\n"},{"id":"383900","messageId":"20191011161112.GA19741@sigill.intra.peff.net","threadId":"51975","inReplyTo":"c9e7fbd6-7ad6-bce9-1e17-6391ab3e0630@iee.email","subject":"Re: [PATCH] git-rev-list.txt: prune options in synopsis","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-10-11T16:11:12Z","receivedAt":"2019-10-11T16:11:14Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 11, 2019 at 05:02:33PM +0100, Philip Oakley wrote:\n\n> Another case, of a different style, is that of `git bundle --all` which does\n> need mentioning that particular rev-list option as a major usage (I couldn't\n> manage to understand the three layers of man page that needed reading).\n> \n> I had proposed a patch many years ago [1] but the feedback wasn't positive,\n> though my SO question continues [2] to get votes.\n\nYeah, I agree that \"git bundle\" could be more clear about this. I think\njust adding an example like this might help:\n\n # generate a bundle similar to what \"git clone\" would produce\n git bundle create file.bundle --branches --tags\n\n-Peff\n"}]}