{"thread":{"id":"53125","subject":"[PATCH] doc: log takes multiple revision ranges","startedAt":"2020-03-28T21:11:49Z","lastAt":"2020-07-09T02:17:06Z","messageCount":23,"participants":["Philippe Blain via GitGitGadget","Junio C Hamano","Philippe Blain","Taylor Blau","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"394251","messageId":"pull.590.git.1585429894378.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":null,"subject":"[PATCH] doc: log takes multiple revision ranges","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-03-28T21:11:34Z","receivedAt":"2020-03-28T21:11:49Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\n`git log` accepts multiple revision ranges, but makes no mention of that\nin its documentation. Currently readers have to go to the `git\nrev-list` documentation to discover this useful feature.\n\nMention it and adjust the synopsys in the doc and in the short\nhelp for `git log`.\n\nAlso add links to the documentation for `git rev-list` and `git diff`\ninstead of simply mentioning them, to make it easier for readers to reach\nthese documentation pages. Let's link to `git diff` as this is the\nporcelain command, and the rest of the family (`diff-index`, `diff-tree` and\n`diff-files`) are mentioned in the \"Raw output format\" section of the\n`git diff` documentation.\n\nSigned-off-by: Philippe Blain \n---\n doc: log takes multiple revision ranges\n \n I hesitated to send this in two patches but decided not to, if it would\n be preferred I'll split it.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-590%2Fphil-blain%2Fdoc-log-multiple-ranges-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-590/phil-blain/doc-log-multiple-ranges-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/590\n\n Documentation/git-log.txt | 12 ++++++------\n builtin/log.c | 2 +-\n 2 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex bed09bb09e5..fa8affd436a 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -9,15 +9,15 @@ git-log - Show commit logs\n SYNOPSIS\n --------\n [verse]\n-'git log' [] [] [[--] ...]\n+'git log' [] [...] [[--] ...]\n \n DESCRIPTION\n -----------\n Shows the commit logs.\n \n-The command takes options applicable to the `git rev-list`\n+The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n-the `git diff-*` commands to control how the changes\n+the linkgit:git-diff[1] family of commands to control how the changes\n each commit introduces are shown.\n \n \n@@ -90,9 +90,9 @@ include::line-range-format.txt[]\n \t is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit). `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n-\t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell , see the 'Specifying Ranges'\n-\tsection of linkgit:gitrevisions[7].\n+\t(i.e. `HEAD`), but not from `origin`. You can give more than \n+\tone revision range. For a complete list of ways to spell ,\n+\tsee the 'Specifying Ranges' section of linkgit:gitrevisions[7]. \n \n [--] ...::\n \tShow only commits that are enough to explain how the files\ndiff --git a/builtin/log.c b/builtin/log.c\nindex 83a4a6188e2..51c2ef54823 100644\n--- a/builtin/log.c\n+++ b/builtin/log.c\n@@ -53,7 +53,7 @@ static const char *fmt_patch_subject_prefix = \"PATCH\";\n static const char *fmt_pretty;\n \n static const char * const builtin_log_usage[] = {\n-\tN_(\"git log [] [] [[--] ...]\"),\n+\tN_(\"git log [] [...] [[--] ...]\"),\n \tN_(\"git show [] ...\"),\n \tNULL\n };\n\nbase-commit: 076cbdcd739aeb33c1be87b73aebae5e43d7bcc5\n-- \ngitgitgadget\n"},{"id":"394259","messageId":"xmqqd08wc5bd.fsf@gitster.c.googlers.com","threadId":"53125","inReplyTo":"pull.590.git.1585429894378.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: log takes multiple revision ranges","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-29T01:34:14Z","receivedAt":"2020-03-29T01:34:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> From: Philippe Blain \n>\n> `git log` accepts multiple revision ranges, but makes no mention of that\n> in its documentation. Currently readers have to go to the `git\n> rev-list` documentation to discover this useful feature.\n\nI have a mixed feeling about this change. Surely you can write\n\n\tgit log v1.0..v2.0 v4.0..v5.0 -- Makefile\n\nand you can explain that the command appears to take two \"ranges\",\nbut I do not think we want to encourage it to those who do not\nunderstand what the above actually *means*. \n\nSpecifially, it does *NOT* list commits between v1.0 and v2.0, or\nbetween v4.0 and v5.0, that touch the path Makefile. In other\nwords, you didn't really give two ranges with the syntax. What the\nA..B notation means could be called a range, only when it appears\nalone.\n\nAnd we have *no* intention of changing the semantics.\n\n\"A..B\" is a mere short-hand for ^A B, and it may appear to be a\nrange, but \"A..B C..D\" does not make \"two ranges\". It still merely\nis a short-hand for ^A B ^C D, and if C reaches A and B (in the\nabove example, v4.0 is very likely to reach both v1.0 and v2.0), it\nmeans the same thing as \"C..D\", i.e. \"git log v4.0..v5.0 -- Makefile\".\n\nSo I have a mildly strong opinion against the change to the synopsys\nand the short-help; it is a bad change that does not help users. If\nthere are not sufficient explanation on the equivalence between A..B\nand ^A B on \"git log\" documentation but there is one elsewhere, adding\na reference to help users learn is very much appreciated, though, and\nI initially was hoping that the second hunk of this patch was such a\nchange, but it appears that it is not (it just adds the misleading\n\"you can have more than one\" without making readers aware of what it\nmeans to write \"A..B C..D\").\n\nThanks.\n\n"},{"id":"394341","messageId":"51E0F312-E132-4E8E-AFE6-570CB02B4590@gmail.com","threadId":"53125","inReplyTo":"xmqqd08wc5bd.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] doc: log takes multiple revision ranges","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-30T12:52:52Z","receivedAt":"2020-03-30T12:52:59Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio, \n> Le 28 mars 2020 à 21:34, Junio C Hamano a écrit :\n> \n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> From: Philippe Blain \n>> \n>> `git log` accepts multiple revision ranges, but makes no mention of that\n>> in its documentation. Currently readers have to go to the `git\n>> rev-list` documentation to discover this useful feature.\n> \n> I have a mixed feeling about this change. Surely you can write\n> \n> \tgit log v1.0..v2.0 v4.0..v5.0 -- Makefile\n> \n> and you can explain that the command appears to take two \"ranges\",\n> but I do not think we want to encourage it to those who do not\n> understand what the above actually *means*. \n> \n> Specifially, it does *NOT* list commits between v1.0 and v2.0, or\n> between v4.0 and v5.0, that touch the path Makefile. In other\n> words, you didn't really give two ranges with the syntax. What the\n> A..B notation means could be called a range, only when it appears\n> alone.\n> \n> And we have *no* intention of changing the semantics.\n\nOf course, I understand.\n\n> \n> \"A..B\" is a mere short-hand for ^A B, and it may appear to be a\n> range, but \"A..B C..D\" does not make \"two ranges\". It still merely\n> is a short-hand for ^A B ^C D, and if C reaches A and B (in the\n> above example, v4.0 is very likely to reach both v1.0 and v2.0), it\n> means the same thing as \"C..D\", i.e. \"git log v4.0..v5.0 -- Makefile\".\n\nYes, you are right.\n\n> \n> So I have a mildly strong opinion against the change to the synopsys\n> and the short-help; it is a bad change that does not help users. If\n> there are not sufficient explanation on the equivalence between A..B\n> and ^A B on \"git log\" documentation but there is one elsewhere, adding\n> a reference to help users learn is very much appreciated, though,\n\nSo the 'git log' documentation states: \n\n origin..HEAD specifies all the commits reachable from the current commit \n (i.e. HEAD), but not from origin. For a complete list of ways to spell , \n see the Specifying Ranges section of gitrevisions[7].\n\nWhat I wanted to achieve with this patch is to make readers aware that \nthey can write e.g.\n\n git log branch1 branch2 branch3 branch4 --not master\n\nto see commits on each of branch1-4, that are not on master, \nsince this is not immediately obvious (at least to me)\nin the 'git log' man page. Even following the link to gitrevisions[7], \nit is not explicitly mentioned in the \"Specifying Ranges\" section \nthat a range denotes the set of all commits reachable by all given refs, \nminus the ones reachable by all given refs prefixed by '^' or '--not'.\nHowever, this is really clear in the 'git rev-list' documentation, \nwhich uses '...' in the synopsis\nand clearly talks about the \"set of commits\" point of view:\n\n You can think of this as a set operation. Commits given on the command line form \n a set of commits that are reachable from any of them, and then commits reachable \n from any of the ones given with ^ in front are subtracted from that set. The remaining \n commits are what comes out in the command’s output. Various other options and \n paths parameters can be used to further limit the result.\n\nDo you think it would be appropriate that this explanation could somehow also appear \nin the 'git log' (and maybe also 'gitrevisions') documentation ?\n\nThanks for the quick feedback,\nPhilippe."},{"id":"394380","messageId":"xmqqsghp93d9.fsf@gitster.c.googlers.com","threadId":"53125","inReplyTo":"51E0F312-E132-4E8E-AFE6-570CB02B4590@gmail.com","subject":"Re: [PATCH] doc: log takes multiple revision ranges","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-30T17:09:06Z","receivedAt":"2020-03-30T17:09:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain writes:\n\n> However, this is really clear in the 'git rev-list' documentation, \n> which uses '...' in the synopsis\n> and clearly talks about the \"set of commits\" point of view:\n>\n> You can think of this as a set operation. Commits given on the command line form \n> a set of commits that are reachable from any of them, and then commits reachable \n> from any of the ones given with ^ in front are subtracted from that set. The remaining \n> commits are what comes out in the command’s output. Various other options and \n> paths parameters can be used to further limit the result.\n>\n> Do you think it would be appropriate that this explanation could somehow also appear \n> in the 'git log' (and maybe also 'gitrevisions') documentation ?\n\nThanks for finding that paragraph. \n\nI said in my previous message that I didn't think the synopsis and\nshort-help changes were bad, and I hoped that the other hunk of the\npatch added reference to \"git log\" page that existed elsewhere to\nhelp readers understand what the positive and negative options do.\nA reference to the \"set operation\" is exactly the kind of addition I\nmeant I hoped to see.\n\nBy the way, I do not write \"git log ab/topic-1 cd/topic-2 --not master\",\nbut \"git log ^master ab/topic-1 cd/topic-2 ef/topic-3\" is something I'd\nquite often write.\n\n"},{"id":"394441","messageId":"20200331215356.GC95875@syl.local","threadId":"53125","inReplyTo":"xmqqd08wc5bd.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] doc: log takes multiple revision ranges","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2020-03-31T21:53:56Z","receivedAt":"2020-03-31T21:54:02Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Sat, Mar 28, 2020 at 06:34:14PM -0700, Junio C Hamano wrote:\n> \"Philippe Blain via GitGitGadget\" writes:\n>\n> > From: Philippe Blain \n> >\n> > `git log` accepts multiple revision ranges, but makes no mention of that\n> > in its documentation. Currently readers have to go to the `git\n> > rev-list` documentation to discover this useful feature.\n>\n> I have a mixed feeling about this change. Surely you can write\n>\n> \tgit log v1.0..v2.0 v4.0..v5.0 -- Makefile\n>\n> and you can explain that the command appears to take two \"ranges\",\n> but I do not think we want to encourage it to those who do not\n> understand what the above actually *means*.\n>\n> Specifially, it does *NOT* list commits between v1.0 and v2.0, or\n> between v4.0 and v5.0, that touch the path Makefile. In other\n> words, you didn't really give two ranges with the syntax. What the\n> A..B notation means could be called a range, only when it appears\n> alone.\n>\n> And we have *no* intention of changing the semantics.\n>\n> \"A..B\" is a mere short-hand for ^A B, and it may appear to be a\n> range, but \"A..B C..D\" does not make \"two ranges\". It still merely\n> is a short-hand for ^A B ^C D, and if C reaches A and B (in the\n> above example, v4.0 is very likely to reach both v1.0 and v2.0), it\n> means the same thing as \"C..D\", i.e. \"git log v4.0..v5.0 -- Makefile\".\n>\n> So I have a mildly strong opinion against the change to the synopsys\n> and the short-help; it is a bad change that does not help users.\n\nI second this opinion. I think that reading:\n\n [ [...]]\n\nis very misleading. It guides the reader to think that they can specify\nmultiple ranges, but does not provide clear guidance about how multiple\nranges are interpreted. I think most readers will naturally assume that\nthe interpretation is \"take the union of each provided range\", but this\nis not the case as Junio points out.\n\n> If there are not sufficient explanation on the equivalence between\n> A..B and ^A B on \"git log\" documentation but there is one elsewhere,\n> adding a reference to help users learn is very much appreciated,\n> though, and I initially was hoping that the second hunk of this patch\n> was such a change, but it appears that it is not (it just adds the\n> misleading \"you can have more than one\" without making readers aware\n> of what it means to write \"A..B C..D\").\n\nI think the documentation is probably clearer as it is. Having this\nextra explanation about the difference between the two doesn't guarantee\nthat it will be read, so it may just be adding additional complexity\nthat isn't warranted ;).\n\n> Thanks.\n\nThanks,\nTaylor\n"},{"id":"400994","messageId":"pull.590.v2.git.1593747509.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.git.1585429894378.gitgitgadget@gmail.com","subject":"[PATCH v2 0/4] doc: include git rev-list description in git log doc","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-03T03:38:25Z","receivedAt":"2020-07-03T03:38:33Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"This series moves the nice explanation in the 'Description' section of the \ngit rev-list man page to a separate file and includes this file in the git\nlog man page.\n\nThis goal is to make readers more aware that they can write e.g.\n\ngit log branch1 branch2 branch3 branch4 --not master\n\nto see commits on each of branch1-4, that are not on master, since this is\nnot immediately obvious (at least to me) in the git log man page. \n\nNote that I made several commits for ease of reviewing, I'll squash some if\nthis would be preferred.\n\nChanges since v1: took a completely different approach following the\ncomments received from Junio and Taylor.\n\nPhilippe Blain (4):\n git-log.txt: add links to 'rev-list' and 'diff' docs\n git-rev-list.txt: move description to separate file\n git-log.txt: include rev-list-description.txt\n rev-list-description.txt: fix Asciidoc syntax\n\n Documentation/git-log.txt | 7 ++-\n Documentation/git-rev-list.txt | 40 +----------------\n Documentation/rev-list-description.txt | 61 ++++++++++++++++++++++++++\n 3 files changed, 68 insertions(+), 40 deletions(-)\n create mode 100644 Documentation/rev-list-description.txt\n\n\nbase-commit: a08a83db2bf27f015bec9a435f6d73e223c21c5e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-590%2Fphil-blain%2Fdoc-log-multiple-ranges-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-590/phil-blain/doc-log-multiple-ranges-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/590\n\nRange-diff vs v1:\n\n 1: 16b8cdb55c ! 1: 59c48282a0 doc: log takes multiple revision ranges\n @@ Metadata\n Author: Philippe Blain \n \n ## Commit message ##\n - doc: log takes multiple revision ranges\n + git-log.txt: add links to 'rev-list' and 'diff' docs\n \n - `git log` accepts multiple revision ranges, but makes no mention of that\n - in its documentation. Currently readers have to go to the `git\n - rev-list` documentation to discover this useful feature.\n -\n - Mention it and adjust the synopsys in the doc and in the short\n - help for `git log`.\n -\n - Also add links to the documentation for `git rev-list` and `git diff`\n + Add links to the documentation for `git rev-list` and `git diff`\n instead of simply mentioning them, to make it easier for readers to reach\n these documentation pages. Let's link to `git diff` as this is the\n porcelain command, and the rest of the family (`diff-index`, `diff-tree` and\n @@ Commit message\n Signed-off-by: Philippe Blain \n \n ## Documentation/git-log.txt ##\n -@@ Documentation/git-log.txt: git-log - Show commit logs\n - SYNOPSIS\n - --------\n - [verse]\n --'git log' [] [] [[--] ...]\n -+'git log' [] [...] [[--] ...]\n - \n - DESCRIPTION\n +@@ Documentation/git-log.txt: DESCRIPTION\n -----------\n Shows the commit logs.\n \n @@ Documentation/git-log.txt: git-log - Show commit logs\n each commit introduces are shown.\n \n \n -@@ Documentation/git-log.txt: include::line-range-format.txt[]\n - \t is specified, it defaults to `HEAD` (i.e. the\n - \twhole history leading to the current commit). `origin..HEAD`\n - \tspecifies all the commits reachable from the current commit\n --\t(i.e. `HEAD`), but not from `origin`. For a complete list of\n --\tways to spell , see the 'Specifying Ranges'\n --\tsection of linkgit:gitrevisions[7].\n -+\t(i.e. `HEAD`), but not from `origin`. You can give more than \n -+\tone revision range. For a complete list of ways to spell ,\n -+\tsee the 'Specifying Ranges' section of linkgit:gitrevisions[7]. \n - \n - [--] ...::\n - \tShow only commits that are enough to explain how the files\n -\n - ## builtin/log.c ##\n -@@ builtin/log.c: static const char *fmt_patch_subject_prefix = \"PATCH\";\n - static const char *fmt_pretty;\n - \n - static const char * const builtin_log_usage[] = {\n --\tN_(\"git log [] [] [[--] ...]\"),\n -+\tN_(\"git log [] [...] [[--] ...]\"),\n - \tN_(\"git show [] ...\"),\n - \tNULL\n - };\n -: ---------- > 2: daf00d9398 git-rev-list.txt: move description to separate file\n -: ---------- > 3: eeaf4fe5dc git-log.txt: include rev-list-description.txt\n -: ---------- > 4: 3b923780c1 rev-list-description.txt: fix Asciidoc syntax\n\n-- \ngitgitgadget\n"},{"id":"400995","messageId":"59c48282a094e90b7f4635c4cbcc04b1914b4c0e.1593747509.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v2.git.1593747509.gitgitgadget@gmail.com","subject":"[PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-03T03:38:26Z","receivedAt":"2020-07-03T03:38:35Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nAdd links to the documentation for `git rev-list` and `git diff`\ninstead of simply mentioning them, to make it easier for readers to reach\nthese documentation pages. Let's link to `git diff` as this is the\nporcelain command, and the rest of the family (`diff-index`, `diff-tree` and\n`diff-files`) are mentioned in the \"Raw output format\" section of the\n`git diff` documentation.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-log.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 20e6d21a74..04ea18d1c0 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -15,9 +15,9 @@ DESCRIPTION\n -----------\n Shows the commit logs.\n \n-The command takes options applicable to the `git rev-list`\n+The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n-the `git diff-*` commands to control how the changes\n+the linkgit:git-diff[1] family of commands to control how the changes\n each commit introduces are shown.\n \n \n-- \ngitgitgadget\n\n"},{"id":"400996","messageId":"eeaf4fe5dc51ba651c85c6dd70919cc1126b8a30.1593747509.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v2.git.1593747509.gitgitgadget@gmail.com","subject":"[PATCH v2 3/4] git-log.txt: include rev-list-description.txt","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-03T03:38:28Z","receivedAt":"2020-07-03T03:38:36Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe `git log` synopsis mentions ``, and the description\nof this option links to gitrevisions(7), but a nice explanation of\nhow a revision range can be constructed from individual commits,\noptionnally prefixed with `^`, also exists in `rev-list-description.txt`.\n\nInclude this description in the man page for `git log`.\n\nAdd Asciidoc 'ifdef's to `rev-list-description.txt` so that either `git\nrev-list` or `git log` appears in the respective man pages.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-log.txt | 3 +++\n Documentation/git-rev-list.txt | 1 +\n Documentation/rev-list-description.txt | 23 +++++++++++++++++++++++\n 3 files changed, 27 insertions(+)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 04ea18d1c0..d34d101255 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -15,6 +15,9 @@ DESCRIPTION\n -----------\n Shows the commit logs.\n \n+:git-log: 1\n+include::rev-list-description.txt[]\n+\n The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n the linkgit:git-diff[1] family of commands to control how the changes\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex b06e11ae56..5da66232dc 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -14,6 +14,7 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n+:git-rev-list: 1\n include::rev-list-description.txt[]\n \n 'rev-list' is a very essential Git command, since it\ndiff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt\nindex aa6bbd8cec..dce78561be 100644\n--- a/Documentation/rev-list-description.txt\n+++ b/Documentation/rev-list-description.txt\n@@ -12,9 +12,16 @@ to further limit the result.\n \n Thus, the following command:\n \n+ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n \t$ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n+endif::git-rev-list[]\n+ifdef::git-log[]\n+-----------------------------------------------------------------------\n+\t$ git log foo bar ^baz\n+-----------------------------------------------------------------------\n+endif::git-log[]\n \n means \"list all the commits which are reachable from 'foo' or 'bar', but\n not from 'baz'\".\n@@ -23,16 +30,32 @@ A special notation \"''..''\" can be used as a\n short-hand for \"{caret}'' ''\". For example, either of\n the following may be used interchangeably:\n \n+ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n \t$ git rev-list origin..HEAD\n \t$ git rev-list HEAD ^origin\n -----------------------------------------------------------------------\n+endif::git-rev-list[]\n+ifdef::git-log[]\n+-----------------------------------------------------------------------\n+\t$ git log origin..HEAD\n+\t$ git log HEAD ^origin\n+-----------------------------------------------------------------------\n+endif::git-log[]\n \n Another special notation is \"''...''\" which is useful\n for merges. The resulting set of commits is the symmetric difference\n between the two operands. The following two commands are equivalent:\n \n+ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n \t$ git rev-list A B --not $(git merge-base --all A B)\n \t$ git rev-list A...B\n -----------------------------------------------------------------------\n+endif::git-rev-list[]\n+ifdef::git-log[]\n+-----------------------------------------------------------------------\n+\t$ git log A B --not $(git merge-base --all A B)\n+\t$ git log A...B\n+-----------------------------------------------------------------------\n+endif::git-log[]\n-- \ngitgitgadget\n\n"},{"id":"400997","messageId":"daf00d9398f0bc094272f5b97aa1220fd573db9a.1593747509.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v2.git.1593747509.gitgitgadget@gmail.com","subject":"[PATCH v2 2/4] git-rev-list.txt: move description to separate file","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-03T03:38:27Z","receivedAt":"2020-07-03T03:38:37Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nA following commit will reuse the description of the `git rev-list`\ncommand in the `git log` manpage.\n\nMove this description to a separate file.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-rev-list.txt | 39 +-------------------------\n Documentation/rev-list-description.txt | 38 +++++++++++++++++++++++++\n 2 files changed, 39 insertions(+), 38 deletions(-)\n create mode 100644 Documentation/rev-list-description.txt\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 025c911436..b06e11ae56 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -14,44 +14,7 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-List commits that are reachable by following the `parent` links from the\n-given commit(s), but exclude commits that are reachable from the one(s)\n-given with a '{caret}' in front of them. The output is given in reverse\n-chronological order by default.\n-\n-You can think of this as a set operation. Commits given on the command\n-line form a set of commits that are reachable from any of them, and then\n-commits reachable from any of the ones given with '{caret}' in front are\n-subtracted from that set. The remaining commits are what comes out in the\n-command's output. Various other options and paths parameters can be used\n-to further limit the result.\n-\n-Thus, the following command:\n-\n------------------------------------------------------------------------\n-\t$ git rev-list foo bar ^baz\n------------------------------------------------------------------------\n-\n-means \"list all the commits which are reachable from 'foo' or 'bar', but\n-not from 'baz'\".\n-\n-A special notation \"''..''\" can be used as a\n-short-hand for \"{caret}'' ''\". For example, either of\n-the following may be used interchangeably:\n-\n------------------------------------------------------------------------\n-\t$ git rev-list origin..HEAD\n-\t$ git rev-list HEAD ^origin\n------------------------------------------------------------------------\n-\n-Another special notation is \"''...''\" which is useful\n-for merges. The resulting set of commits is the symmetric difference\n-between the two operands. The following two commands are equivalent:\n-\n------------------------------------------------------------------------\n-\t$ git rev-list A B --not $(git merge-base --all A B)\n-\t$ git rev-list A...B\n------------------------------------------------------------------------\n+include::rev-list-description.txt[]\n \n 'rev-list' is a very essential Git command, since it\n provides the ability to build and traverse commit ancestry graphs. For\ndiff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt\nnew file mode 100644\nindex 0000000000..aa6bbd8cec\n--- /dev/null\n+++ b/Documentation/rev-list-description.txt\n@@ -0,0 +1,38 @@\n+List commits that are reachable by following the `parent` links from the\n+given commit(s), but exclude commits that are reachable from the one(s)\n+given with a '{caret}' in front of them. The output is given in reverse\n+chronological order by default.\n+\n+You can think of this as a set operation. Commits given on the command\n+line form a set of commits that are reachable from any of them, and then\n+commits reachable from any of the ones given with '{caret}' in front are\n+subtracted from that set. The remaining commits are what comes out in the\n+command's output. Various other options and paths parameters can be used\n+to further limit the result.\n+\n+Thus, the following command:\n+\n+-----------------------------------------------------------------------\n+\t$ git rev-list foo bar ^baz\n+-----------------------------------------------------------------------\n+\n+means \"list all the commits which are reachable from 'foo' or 'bar', but\n+not from 'baz'\".\n+\n+A special notation \"''..''\" can be used as a\n+short-hand for \"{caret}'' ''\". For example, either of\n+the following may be used interchangeably:\n+\n+-----------------------------------------------------------------------\n+\t$ git rev-list origin..HEAD\n+\t$ git rev-list HEAD ^origin\n+-----------------------------------------------------------------------\n+\n+Another special notation is \"''...''\" which is useful\n+for merges. The resulting set of commits is the symmetric difference\n+between the two operands. The following two commands are equivalent:\n+\n+-----------------------------------------------------------------------\n+\t$ git rev-list A B --not $(git merge-base --all A B)\n+\t$ git rev-list A...B\n+-----------------------------------------------------------------------\n-- \ngitgitgadget\n\n"},{"id":"400998","messageId":"3b923780c1f38ee183397b5766aae65933eec4aa.1593747509.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v2.git.1593747509.gitgitgadget@gmail.com","subject":"[PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-03T03:38:29Z","receivedAt":"2020-07-03T03:38:38Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nUsing '{caret}' inside double quotes and immediately following with a\nsingle quoted word does not create the desired output: ''\nappears verbatim instead of being emphasized.\n\nUse a litteral caret ('^') instead.\n\nAlso, remove the leading tabs in shell examples to bring them more in\nline with the rest of the documentation.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/rev-list-description.txt | 22 +++++++++++-----------\n 1 file changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt\nindex dce78561be..4bde2fd4fe 100644\n--- a/Documentation/rev-list-description.txt\n+++ b/Documentation/rev-list-description.txt\n@@ -14,12 +14,12 @@ Thus, the following command:\n \n ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n-\t$ git rev-list foo bar ^baz\n+$ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n endif::git-rev-list[]\n ifdef::git-log[]\n -----------------------------------------------------------------------\n-\t$ git log foo bar ^baz\n+$ git log foo bar ^baz\n -----------------------------------------------------------------------\n endif::git-log[]\n \n@@ -27,19 +27,19 @@ means \"list all the commits which are reachable from 'foo' or 'bar', but\n not from 'baz'\".\n \n A special notation \"''..''\" can be used as a\n-short-hand for \"{caret}'' ''\". For example, either of\n+short-hand for \"^'' ''\". For example, either of\n the following may be used interchangeably:\n \n ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n-\t$ git rev-list origin..HEAD\n-\t$ git rev-list HEAD ^origin\n+$ git rev-list origin..HEAD\n+$ git rev-list HEAD ^origin\n -----------------------------------------------------------------------\n endif::git-rev-list[]\n ifdef::git-log[]\n -----------------------------------------------------------------------\n-\t$ git log origin..HEAD\n-\t$ git log HEAD ^origin\n+$ git log origin..HEAD\n+$ git log HEAD ^origin\n -----------------------------------------------------------------------\n endif::git-log[]\n \n@@ -49,13 +49,13 @@ between the two operands. The following two commands are equivalent:\n \n ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n-\t$ git rev-list A B --not $(git merge-base --all A B)\n-\t$ git rev-list A...B\n+$ git rev-list A B --not $(git merge-base --all A B)\n+$ git rev-list A...B\n -----------------------------------------------------------------------\n endif::git-rev-list[]\n ifdef::git-log[]\n -----------------------------------------------------------------------\n-\t$ git log A B --not $(git merge-base --all A B)\n-\t$ git log A...B\n+$ git log A B --not $(git merge-base --all A B)\n+$ git log A...B\n -----------------------------------------------------------------------\n endif::git-log[]\n-- \ngitgitgadget\n"},{"id":"401033","messageId":"f55e0109-af9a-7c21-1cbf-41b2531560e4@iee.email","threadId":"53125","inReplyTo":"51E0F312-E132-4E8E-AFE6-570CB02B4590@gmail.com","subject":"Re: [PATCH] doc: log takes multiple revision ranges","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2020-07-05T20:42:41Z","receivedAt":"2020-07-05T20:42:48Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Philippe,\nThis had been sitting in my inbox..\n\nOn 30/03/2020 13:52, Philippe Blain wrote:\n> Hi Junio, \n>> Le 28 mars 2020 à 21:34, Junio C Hamano a écrit :\n>>\n>> \"Philippe Blain via GitGitGadget\" writes:\n>>\n>>> From: Philippe Blain \n>>>\n>>> `git log` accepts multiple revision ranges, but makes no mention of that\n>>> in its documentation. Currently readers have to go to the `git\n>>> rev-list` documentation to discover this useful feature.\n\nI'd concur that sometime the documentation is not as educationally\ninformative  as it could be. Often it leaves readers to second guess\nwhat is meant, or redirects to other reference sections with similar\npresumptions that the reader already understands.  Documentation is\nharder than coding because of these differences in writing style. Often\nGit appears to prefer the normative standard style.\n\n>> I have a mixed feeling about this change. Surely you can write\n>>\n>> \tgit log v1.0..v2.0 v4.0..v5.0 -- Makefile\n>>\n>> and you can explain that the command appears to take two \"ranges\",\n>> but I do not think we want to encourage it to those who do not\n>> understand what the above actually *means*. \n>>\n>> Specifially, it does *NOT* list commits between v1.0 and v2.0, or\n>> between v4.0 and v5.0, that touch the path Makefile. In other\n>> words, you didn't really give two ranges with the syntax. What the\n>> A..B notation means could be called a range, only when it appears\n>> alone.\n>>\n>> And we have *no* intention of changing the semantics.\n> Of course, I understand.\n>\n>> \"A..B\" is a mere short-hand for ^A B, and it may appear to be a\n>> range, but \"A..B C..D\" does not make \"two ranges\". It still merely\n>> is a short-hand for ^A B ^C D, and if C reaches A and B (in the\n>> above example, v4.0 is very likely to reach both v1.0 and v2.0), it\n>> means the same thing as \"C..D\", i.e. \"git log v4.0..v5.0 -- Makefile\".\n> Yes, you are right.\n>\n>> So I have a mildly strong opinion against the change to the synopsys\n>> and the short-help; it is a bad change that does not help users. If\n>> there are not sufficient explanation on the equivalence between A..B\n>> and ^A B on \"git log\" documentation but there is one elsewhere, adding\n>> a reference to help users learn is very much appreciated, though,\n> So the 'git log' documentation states: \n>\n> origin..HEAD specifies all the commits reachable from the current commit \n> (i.e. HEAD), but not from origin. For a complete list of ways to spell , \n> see the Specifying Ranges section of gitrevisions[7].\n>\n> What I wanted to achieve with this patch is to make readers aware that \n> they can write e.g.\n>\n> git log branch1 branch2 branch3 branch4 --not master\n>\n> to see commits on each of branch1-4, that are not on master, \n> since this is not immediately obvious (at least to me)\n> in the 'git log' man page. \n\nThe whole revision walk stuff is tricky. Finding the right starting\npoint for explanations is key, along with picking out where 'normal'\nerrors are made, as these do help users who aren't simply 'checking the\nmanual'. (the 20-20 hindsight problem)\n\nFor example, your \"that are not on master\", and what that means, needs\nto be brought out to the new reader rather than being buried\nmid-sentence. Most readers will miss those mid-sentence key points and\nthey can't learn until they have some significant problem that points it\nout to them. Sometime we need to point at the 'wrong' things, not just\nthe right things. (e.g. if branch3 had ben merged a couple of revisions\nago...)\n\n> Even following the link to gitrevisions[7], \n> it is not explicitly mentioned in the \"Specifying Ranges\" section \n> that a range denotes the set of all commits reachable by all given refs, \n> minus the ones reachable by all given refs prefixed by '^' or '--not'.\n> However, this is really clear in the 'git rev-list' documentation, \n> which uses '...' in the synopsis\n> and clearly talks about the \"set of commits\" point of view:\n>\n> You can think of this as a set operation. Commits given on the command line form \n> a set of commits that are reachable from any of them, and then commits reachable \n> from any of the ones given with ^ in front are subtracted from that set. The remaining \n> commits are what comes out in the command’s output. Various other options and \n> paths parameters can be used to further limit the result.\n>\nSet operations don't help everyone, just sayin'.\n\nIn some cases: The fact that we exclude any commit reachable from any of\nthe \"^\" commits should be mentioned first, and then we select any left\nthat are reachable from the named tips. This puts a different spin on\nthe  understanding, and helps catch those that have not understood the\nother descriptions. It can then be easily linked to the 'two ranges'\ncase producing otherwise unexpected results.\n> Do you think it would be appropriate that this explanation could somehow also appear \n> in the 'git log' (and maybe also 'gitrevisions') documentation ?\n>\n> Thanks for the quick feedback,\n> Philippe.\nPhilip\n"},{"id":"401059","messageId":"xmqqimf087pq.fsf@gitster.c.googlers.com","threadId":"53125","inReplyTo":"59c48282a094e90b7f4635c4cbcc04b1914b4c0e.1593747509.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-07-07T00:55:13Z","receivedAt":"2020-07-07T00:55:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> From: Philippe Blain \n>\n> Add links to the documentation for `git rev-list` and `git diff`\n> instead of simply mentioning them, to make it easier for readers to reach\n> these documentation pages. Let's link to `git diff` as this is the\n> porcelain command, and the rest of the family (`diff-index`, `diff-tree` and\n> `diff-files`) are mentioned in the \"Raw output format\" section of the\n> `git diff` documentation.\n>\n> Signed-off-by: Philippe Blain \n> ---\n> Documentation/git-log.txt | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index 20e6d21a74..04ea18d1c0 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -15,9 +15,9 @@ DESCRIPTION\n> -----------\n> Shows the commit logs.\n> \n> -The command takes options applicable to the `git rev-list`\n> +The command takes options applicable to the linkgit:git-rev-list[1]\n> command to control what is shown and how, and options applicable to\n> -the `git diff-*` commands to control how the changes\n> +the linkgit:git-diff[1] family of commands to control how the changes\n> each commit introduces are shown.\n\nThe original did mean \"git diff-*\" family of plumbing commands, but\nI think it makes more sense these days to just refer to \"git diff\"\nPorcelain, which is the single entry point everybody uses. So you\nwould probably want to further replace \"family of commands\" with\njust \"command\" in the text.\n\nOther than that, I think making these into links is a good idea.\n"},{"id":"401060","messageId":"xmqqeepo87hz.fsf@gitster.c.googlers.com","threadId":"53125","inReplyTo":"3b923780c1f38ee183397b5766aae65933eec4aa.1593747509.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-07-07T00:59:52Z","receivedAt":"2020-07-07T00:59:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> From: Philippe Blain \n>\n> Using '{caret}' inside double quotes and immediately following with a\n> single quoted word does not create the desired output: ''\n> appears verbatim instead of being emphasized.\n>\n> Use a litteral caret ('^') instead.\n>\n> Also, remove the leading tabs in shell examples to bring them more in\n> line with the rest of the documentation.\n\nThese should be done _before_ 2/4 as a preliminary clean-up, I\nthink.\n\nThanks for a pleasant read.\n"},{"id":"401092","messageId":"11841F90-5F2B-4786-AFE9-7A2CA62C7A19@gmail.com","threadId":"53125","inReplyTo":"f55e0109-af9a-7c21-1cbf-41b2531560e4@iee.email","subject":"Re: [PATCH] doc: log takes multiple revision ranges","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-07-07T13:08:11Z","receivedAt":"2020-07-07T13:08:18Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Philip,\n\n> Le 5 juil. 2020 à 16:42, Philip Oakley a écrit :\n> \n> Hi Philippe,\n> This had been sitting in my inbox..\n> \n-----8<-----\n>> \n>> What I wanted to achieve with this patch is to make readers aware that \n>> they can write e.g.\n>> \n>> git log branch1 branch2 branch3 branch4 --not master\n>> \n>> to see commits on each of branch1-4, that are not on master, \n>> since this is not immediately obvious (at least to me)\n>> in the 'git log' man page. \n> \n> The whole revision walk stuff is tricky. Finding the right starting\n> point for explanations is key, along with picking out where 'normal'\n> errors are made, as these do help users who aren't simply 'checking the\n> manual'. (the 20-20 hindsight problem)\n> \n> For example, your \"that are not on master\", and what that means, needs\n> to be brought out to the new reader rather than being buried\n> mid-sentence. Most readers will miss those mid-sentence key points and\n> they can't learn until they have some significant problem that points it\n> out to them. Sometime we need to point at the 'wrong' things, not just\n> the right things. (e.g. if branch3 had ben merged a couple of revisions\n> ago...)\n\nYes, here I meant \"on master\" in the \"not yet merged into master\" sense, of course.\nI'd be more careful if I was writing a commit message or part of the doc itself.\n\n> \n>> Even following the link to gitrevisions[7], \n>> it is not explicitly mentioned in the \"Specifying Ranges\" section \n>> that a range denotes the set of all commits reachable by all given refs, \n>> minus the ones reachable by all given refs prefixed by '^' or '--not'.\n>> However, this is really clear in the 'git rev-list' documentation, \n>> which uses '...' in the synopsis\n>> and clearly talks about the \"set of commits\" point of view:\n>> \n>> You can think of this as a set operation. Commits given on the command line form \n>> a set of commits that are reachable from any of them, and then commits reachable \n>> from any of the ones given with ^ in front are subtracted from that set. The remaining \n>> commits are what comes out in the command’s output. Various other options and \n>> paths parameters can be used to further limit the result.\n>> \n> Set operations don't help everyone, just sayin'.\n> \n> In some cases: The fact that we exclude any commit reachable from any of\n> the \"^\" commits should be mentioned first, and then we select any left\n> that are reachable from the named tips. This puts a different spin on\n> the understanding, and helps catch those that have not understood the\n> other descriptions. It can then be easily linked to the 'two ranges'\n> case producing otherwise unexpected results.\n\nI'll try to tweak the wording for v3.\n\nThanks,\nPhilippe.\n\n"},{"id":"401093","messageId":"CF9816CD-35BC-44D8-990C-019D8C1F4405@gmail.com","threadId":"53125","inReplyTo":"xmqqimf087pq.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-07-07T13:11:18Z","receivedAt":"2020-07-07T13:11:23Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\n> Le 6 juil. 2020 à 20:55, Junio C Hamano a écrit :\n> \n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> From: Philippe Blain \n>> \n---8<---\n>> \n>> -The command takes options applicable to the `git rev-list`\n>> +The command takes options applicable to the linkgit:git-rev-list[1]\n>> command to control what is shown and how, and options applicable to\n>> -the `git diff-*` commands to control how the changes\n>> +the linkgit:git-diff[1] family of commands to control how the changes\n>> each commit introduces are shown.\n> \n> The original did mean \"git diff-*\" family of plumbing commands, but\n> I think it makes more sense these days to just refer to \"git diff\"\n> Porcelain, which is the single entry point everybody uses. So you\n> would probably want to further replace \"family of commands\" with\n> just \"command\" in the text.\n> \n\nRight. I'll change that.\n\n> Other than that, I think making these into links is a good idea.\n\nThanks,\nPhilippe.\n\nP.S. sorry for the resend, I forgot to convert the message to plain text the first time..."},{"id":"401094","messageId":"4FEB0C20-2CDE-4110-B153-251AABD17CC4@gmail.com","threadId":"53125","inReplyTo":"xmqqeepo87hz.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-07-07T13:12:54Z","receivedAt":"2020-07-07T13:12:59Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 6 juil. 2020 à 20:59, Junio C Hamano a écrit :\n> \n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> From: Philippe Blain \n>> \n>> Using '{caret}' inside double quotes and immediately following with a\n>> single quoted word does not create the desired output: ''\n>> appears verbatim instead of being emphasized.\n>> \n>> Use a litteral caret ('^') instead.\n>> \n>> Also, remove the leading tabs in shell examples to bring them more in\n>> line with the rest of the documentation.\n> \n> These should be done _before_ 2/4 as a preliminary clean-up, I\n> think.\n\nI agree. I'll reorder that for v3.\n\n\n"},{"id":"401214","messageId":"pull.590.v3.git.1594261008.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v2.git.1593747509.gitgitgadget@gmail.com","subject":"[PATCH v3 0/6] doc: include git rev-list description in git log doc","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-09T02:16:42Z","receivedAt":"2020-07-09T02:16:55Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Changes since v2:\n\n * applied Junio's suggestions \n * added a preparatory commit tweaking the wording of one sentence in the \n git rev-list description\n * added a new commit adding a sentence in revisions.txt to mention\n explicitly what it means to list several revisions to form a range.\n\nv2: This series moves the nice explanation in the 'Description' section of\nthe git rev-list man page to a separate file and includes this file in the \ngit log man page.\n\nThis goal is to make readers more aware that they can write e.g.\n\ngit log branch1 branch2 branch3 branch4 --not master\n\nto see commits on each of branch1-4, that are not on master, since this is\nnot immediately obvious (at least to me) in the git log man page. \n\nNote that I made several commits for ease of reviewing, I'll squash some if\nthis would be preferred.\n\nChanges since v1: took a completely different approach following the\ncomments received from Junio and Taylor.\n\nPhilippe Blain (6):\n git-log.txt: add links to 'rev-list' and 'diff' docs\n revisions.txt: describe 'rev1 rev2 ...' meaning for ranges\n git-rev-list.txt: fix Asciidoc syntax\n git-rev-list.txt: tweak wording in set operations\n git-rev-list.txt: move description to separate file\n git-log.txt: include rev-list-description.txt\n\n Documentation/git-log.txt | 7 ++-\n Documentation/git-rev-list.txt | 40 +----------------\n Documentation/rev-list-description.txt | 61 ++++++++++++++++++++++++++\n Documentation/revisions.txt | 3 ++\n 4 files changed, 71 insertions(+), 40 deletions(-)\n create mode 100644 Documentation/rev-list-description.txt\n\n\nbase-commit: a08a83db2bf27f015bec9a435f6d73e223c21c5e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-590%2Fphil-blain%2Fdoc-log-multiple-ranges-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-590/phil-blain/doc-log-multiple-ranges-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/590\n\nRange-diff vs v2:\n\n 1: 59c48282a0 ! 1: 59027b0f6a git-log.txt: add links to 'rev-list' and 'diff' docs\n @@ Documentation/git-log.txt: DESCRIPTION\n +The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n -the `git diff-*` commands to control how the changes\n -+the linkgit:git-diff[1] family of commands to control how the changes\n ++the linkgit:git-diff[1] command to control how the changes\n each commit introduces are shown.\n \n \n -: ---------- > 2: 3c573695a8 revisions.txt: describe 'rev1 rev2 ...' meaning for ranges\n 4: 3b923780c1 ! 3: b8ee4a743c rev-list-description.txt: fix Asciidoc syntax\n @@ Metadata\n Author: Philippe Blain \n \n ## Commit message ##\n - rev-list-description.txt: fix Asciidoc syntax\n + git-rev-list.txt: fix Asciidoc syntax\n \n Using '{caret}' inside double quotes and immediately following with a\n single quoted word does not create the desired output: ''\n @@ Commit message\n \n Signed-off-by: Philippe Blain \n \n - ## Documentation/rev-list-description.txt ##\n -@@ Documentation/rev-list-description.txt: Thus, the following command:\n + ## Documentation/git-rev-list.txt ##\n +@@ Documentation/git-rev-list.txt: to further limit the result.\n + Thus, the following command:\n \n - ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n -\t$ git rev-list foo bar ^baz\n +$ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n - endif::git-rev-list[]\n - ifdef::git-log[]\n - -----------------------------------------------------------------------\n --\t$ git log foo bar ^baz\n -+$ git log foo bar ^baz\n - -----------------------------------------------------------------------\n - endif::git-log[]\n \n -@@ Documentation/rev-list-description.txt: means \"list all the commits which are reachable from 'foo' or 'bar', but\n + means \"list all the commits which are reachable from 'foo' or 'bar', but\n not from 'baz'\".\n \n A special notation \"''..''\" can be used as a\n @@ Documentation/rev-list-description.txt: means \"list all the commits which are re\n +short-hand for \"^'' ''\". For example, either of\n the following may be used interchangeably:\n \n - ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n -\t$ git rev-list origin..HEAD\n -\t$ git rev-list HEAD ^origin\n +$ git rev-list origin..HEAD\n +$ git rev-list HEAD ^origin\n -----------------------------------------------------------------------\n - endif::git-rev-list[]\n - ifdef::git-log[]\n - -----------------------------------------------------------------------\n --\t$ git log origin..HEAD\n --\t$ git log HEAD ^origin\n -+$ git log origin..HEAD\n -+$ git log HEAD ^origin\n - -----------------------------------------------------------------------\n - endif::git-log[]\n \n -@@ Documentation/rev-list-description.txt: between the two operands. The following two commands are equivalent:\n + Another special notation is \"''...''\" which is useful\n +@@ Documentation/git-rev-list.txt: for merges. The resulting set of commits is the symmetric difference\n + between the two operands. The following two commands are equivalent:\n \n - ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n -\t$ git rev-list A B --not $(git merge-base --all A B)\n -\t$ git rev-list A...B\n +$ git rev-list A B --not $(git merge-base --all A B)\n +$ git rev-list A...B\n -----------------------------------------------------------------------\n - endif::git-rev-list[]\n - ifdef::git-log[]\n - -----------------------------------------------------------------------\n --\t$ git log A B --not $(git merge-base --all A B)\n --\t$ git log A...B\n -+$ git log A B --not $(git merge-base --all A B)\n -+$ git log A...B\n - -----------------------------------------------------------------------\n - endif::git-log[]\n + \n + 'rev-list' is a very essential Git command, since it\n -: ---------- > 4: cf934ddf33 git-rev-list.txt: tweak wording in set operations\n 2: daf00d9398 ! 5: f61bbb57cb git-rev-list.txt: move description to separate file\n @@ Documentation/git-rev-list.txt: SYNOPSIS\n -given with a '{caret}' in front of them. The output is given in reverse\n -chronological order by default.\n -\n --You can think of this as a set operation. Commits given on the command\n --line form a set of commits that are reachable from any of them, and then\n --commits reachable from any of the ones given with '{caret}' in front are\n --subtracted from that set. The remaining commits are what comes out in the\n --command's output. Various other options and paths parameters can be used\n --to further limit the result.\n +-You can think of this as a set operation. Commits reachable from any of\n +-the commits given on the command line form a set, and then commits reachable\n +-from any of the ones given with '{caret}' in front are subtracted from that\n +-set. The remaining commits are what comes out in the command's output.\n +-Various other options and paths parameters can be used to further limit the\n +-result.\n -\n -Thus, the following command:\n -\n ------------------------------------------------------------------------\n --\t$ git rev-list foo bar ^baz\n +-$ git rev-list foo bar ^baz\n ------------------------------------------------------------------------\n -\n -means \"list all the commits which are reachable from 'foo' or 'bar', but\n -not from 'baz'\".\n -\n -A special notation \"''..''\" can be used as a\n --short-hand for \"{caret}'' ''\". For example, either of\n +-short-hand for \"^'' ''\". For example, either of\n -the following may be used interchangeably:\n -\n ------------------------------------------------------------------------\n --\t$ git rev-list origin..HEAD\n --\t$ git rev-list HEAD ^origin\n +-$ git rev-list origin..HEAD\n +-$ git rev-list HEAD ^origin\n ------------------------------------------------------------------------\n -\n -Another special notation is \"''...''\" which is useful\n @@ Documentation/git-rev-list.txt: SYNOPSIS\n -between the two operands. The following two commands are equivalent:\n -\n ------------------------------------------------------------------------\n --\t$ git rev-list A B --not $(git merge-base --all A B)\n --\t$ git rev-list A...B\n +-$ git rev-list A B --not $(git merge-base --all A B)\n +-$ git rev-list A...B\n ------------------------------------------------------------------------\n +include::rev-list-description.txt[]\n \n @@ Documentation/rev-list-description.txt (new)\n +given with a '{caret}' in front of them. The output is given in reverse\n +chronological order by default.\n +\n -+You can think of this as a set operation. Commits given on the command\n -+line form a set of commits that are reachable from any of them, and then\n -+commits reachable from any of the ones given with '{caret}' in front are\n -+subtracted from that set. The remaining commits are what comes out in the\n -+command's output. Various other options and paths parameters can be used\n -+to further limit the result.\n ++You can think of this as a set operation. Commits reachable from any of\n ++the commits given on the command line form a set, and then commits reachable\n ++from any of the ones given with '{caret}' in front are subtracted from that\n ++set. The remaining commits are what comes out in the command's output.\n ++Various other options and paths parameters can be used to further limit the\n ++result.\n +\n +Thus, the following command:\n +\n +-----------------------------------------------------------------------\n -+\t$ git rev-list foo bar ^baz\n ++$ git rev-list foo bar ^baz\n +-----------------------------------------------------------------------\n +\n +means \"list all the commits which are reachable from 'foo' or 'bar', but\n +not from 'baz'\".\n +\n +A special notation \"''..''\" can be used as a\n -+short-hand for \"{caret}'' ''\". For example, either of\n ++short-hand for \"^'' ''\". For example, either of\n +the following may be used interchangeably:\n +\n +-----------------------------------------------------------------------\n -+\t$ git rev-list origin..HEAD\n -+\t$ git rev-list HEAD ^origin\n ++$ git rev-list origin..HEAD\n ++$ git rev-list HEAD ^origin\n +-----------------------------------------------------------------------\n +\n +Another special notation is \"''...''\" which is useful\n @@ Documentation/rev-list-description.txt (new)\n +between the two operands. The following two commands are equivalent:\n +\n +-----------------------------------------------------------------------\n -+\t$ git rev-list A B --not $(git merge-base --all A B)\n -+\t$ git rev-list A...B\n ++$ git rev-list A B --not $(git merge-base --all A B)\n ++$ git rev-list A...B\n +-----------------------------------------------------------------------\n 3: eeaf4fe5dc ! 6: d04b6c62a3 git-log.txt: include rev-list-description.txt\n @@ Documentation/git-log.txt: DESCRIPTION\n +\n The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n - the linkgit:git-diff[1] family of commands to control how the changes\n + the linkgit:git-diff[1] command to control how the changes\n \n ## Documentation/git-rev-list.txt ##\n @@ Documentation/git-rev-list.txt: SYNOPSIS\n @@ Documentation/git-rev-list.txt: SYNOPSIS\n 'rev-list' is a very essential Git command, since it\n \n ## Documentation/rev-list-description.txt ##\n -@@ Documentation/rev-list-description.txt: to further limit the result.\n +@@ Documentation/rev-list-description.txt: result.\n \n Thus, the following command:\n \n +ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n - \t$ git rev-list foo bar ^baz\n + $ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n +endif::git-rev-list[]\n +ifdef::git-log[]\n +-----------------------------------------------------------------------\n -+\t$ git log foo bar ^baz\n ++$ git log foo bar ^baz\n +-----------------------------------------------------------------------\n +endif::git-log[]\n \n means \"list all the commits which are reachable from 'foo' or 'bar', but\n not from 'baz'\".\n @@ Documentation/rev-list-description.txt: A special notation \"''..''\" can be used as a\n - short-hand for \"{caret}'' ''\". For example, either of\n + short-hand for \"^'' ''\". For example, either of\n the following may be used interchangeably:\n \n +ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n - \t$ git rev-list origin..HEAD\n - \t$ git rev-list HEAD ^origin\n + $ git rev-list origin..HEAD\n + $ git rev-list HEAD ^origin\n -----------------------------------------------------------------------\n +endif::git-rev-list[]\n +ifdef::git-log[]\n +-----------------------------------------------------------------------\n -+\t$ git log origin..HEAD\n -+\t$ git log HEAD ^origin\n ++$ git log origin..HEAD\n ++$ git log HEAD ^origin\n +-----------------------------------------------------------------------\n +endif::git-log[]\n \n @@ Documentation/rev-list-description.txt: A special notation \"''..'\n\nAdd links to the documentation for `git rev-list` and `git diff`\ninstead of simply mentioning them, to make it easier for readers to reach\nthese documentation pages. Let's link to `git diff` as this is the\nporcelain command, and the rest of the family (`diff-index`, `diff-tree` and\n`diff-files`) are mentioned in the \"Raw output format\" section of the\n`git diff` documentation.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-log.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 20e6d21a74..0fcaf34d62 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -15,9 +15,9 @@ DESCRIPTION\n -----------\n Shows the commit logs.\n \n-The command takes options applicable to the `git rev-list`\n+The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n-the `git diff-*` commands to control how the changes\n+the linkgit:git-diff[1] command to control how the changes\n each commit introduces are shown.\n \n \n-- \ngitgitgadget\n\n"},{"id":"401216","messageId":"cf934ddf33e94871bd8b7fcba1c420c89c88e6d2.1594261008.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v3.git.1594261008.gitgitgadget@gmail.com","subject":"[PATCH v3 4/6] git-rev-list.txt: tweak wording in set operations","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-09T02:16:46Z","receivedAt":"2020-07-09T02:16:58Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nTweak a sentence to make it a little more readable.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-rev-list.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex aa95334a79..f2b83df2fa 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -19,12 +19,12 @@ given commit(s), but exclude commits that are reachable from the one(s)\n given with a '{caret}' in front of them. The output is given in reverse\n chronological order by default.\n \n-You can think of this as a set operation. Commits given on the command\n-line form a set of commits that are reachable from any of them, and then\n-commits reachable from any of the ones given with '{caret}' in front are\n-subtracted from that set. The remaining commits are what comes out in the\n-command's output. Various other options and paths parameters can be used\n-to further limit the result.\n+You can think of this as a set operation. Commits reachable from any of\n+the commits given on the command line form a set, and then commits reachable\n+from any of the ones given with '{caret}' in front are subtracted from that\n+set. The remaining commits are what comes out in the command's output.\n+Various other options and paths parameters can be used to further limit the\n+result.\n \n Thus, the following command:\n \n-- \ngitgitgadget\n\n"},{"id":"401217","messageId":"3c573695a804c2103e69a2760fa28e4aa67f9f4b.1594261008.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v3.git.1594261008.gitgitgadget@gmail.com","subject":"[PATCH v3 2/6] revisions.txt: describe 'rev1 rev2 ...' meaning for ranges","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-09T02:16:44Z","receivedAt":"2020-07-09T02:16:59Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe \"Specifying ranges\" section does not mention explicitly that\nseveral commits can be specified to form a range.\n\nAdd a mention to that effect.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/revisions.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 1ad95065c1..d9169c062e 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -254,6 +254,9 @@ specifying a single revision, using the notation described in the\n previous section, means the set of commits `reachable` from the given\n commit.\n \n+Specifying several revisions means the set of commits reachable from\n+any of the given commits.\n+\n A commit's reachable set is the commit itself and the commits in\n its ancestry chain.\n \n-- \ngitgitgadget\n\n"},{"id":"401218","messageId":"b8ee4a743c49553ba479839a234c421876fa14a4.1594261008.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v3.git.1594261008.gitgitgadget@gmail.com","subject":"[PATCH v3 3/6] git-rev-list.txt: fix Asciidoc syntax","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-09T02:16:45Z","receivedAt":"2020-07-09T02:17:01Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nUsing '{caret}' inside double quotes and immediately following with a\nsingle quoted word does not create the desired output: ''\nappears verbatim instead of being emphasized.\n\nUse a litteral caret ('^') instead.\n\nAlso, remove the leading tabs in shell examples to bring them more in\nline with the rest of the documentation.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-rev-list.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 025c911436..aa95334a79 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -29,19 +29,19 @@ to further limit the result.\n Thus, the following command:\n \n -----------------------------------------------------------------------\n-\t$ git rev-list foo bar ^baz\n+$ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n \n means \"list all the commits which are reachable from 'foo' or 'bar', but\n not from 'baz'\".\n \n A special notation \"''..''\" can be used as a\n-short-hand for \"{caret}'' ''\". For example, either of\n+short-hand for \"^'' ''\". For example, either of\n the following may be used interchangeably:\n \n -----------------------------------------------------------------------\n-\t$ git rev-list origin..HEAD\n-\t$ git rev-list HEAD ^origin\n+$ git rev-list origin..HEAD\n+$ git rev-list HEAD ^origin\n -----------------------------------------------------------------------\n \n Another special notation is \"''...''\" which is useful\n@@ -49,8 +49,8 @@ for merges. The resulting set of commits is the symmetric difference\n between the two operands. The following two commands are equivalent:\n \n -----------------------------------------------------------------------\n-\t$ git rev-list A B --not $(git merge-base --all A B)\n-\t$ git rev-list A...B\n+$ git rev-list A B --not $(git merge-base --all A B)\n+$ git rev-list A...B\n -----------------------------------------------------------------------\n \n 'rev-list' is a very essential Git command, since it\n-- \ngitgitgadget\n\n"},{"id":"401219","messageId":"f61bbb57cbcd52144e81f093cf7c4c80249397f2.1594261008.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v3.git.1594261008.gitgitgadget@gmail.com","subject":"[PATCH v3 5/6] git-rev-list.txt: move description to separate file","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-09T02:16:47Z","receivedAt":"2020-07-09T02:17:03Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nA following commit will reuse the description of the `git rev-list`\ncommand in the `git log` manpage.\n\nMove this description to a separate file.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-rev-list.txt | 39 +-------------------------\n Documentation/rev-list-description.txt | 38 +++++++++++++++++++++++++\n 2 files changed, 39 insertions(+), 38 deletions(-)\n create mode 100644 Documentation/rev-list-description.txt\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex f2b83df2fa..b06e11ae56 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -14,44 +14,7 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-List commits that are reachable by following the `parent` links from the\n-given commit(s), but exclude commits that are reachable from the one(s)\n-given with a '{caret}' in front of them. The output is given in reverse\n-chronological order by default.\n-\n-You can think of this as a set operation. Commits reachable from any of\n-the commits given on the command line form a set, and then commits reachable\n-from any of the ones given with '{caret}' in front are subtracted from that\n-set. The remaining commits are what comes out in the command's output.\n-Various other options and paths parameters can be used to further limit the\n-result.\n-\n-Thus, the following command:\n-\n------------------------------------------------------------------------\n-$ git rev-list foo bar ^baz\n------------------------------------------------------------------------\n-\n-means \"list all the commits which are reachable from 'foo' or 'bar', but\n-not from 'baz'\".\n-\n-A special notation \"''..''\" can be used as a\n-short-hand for \"^'' ''\". For example, either of\n-the following may be used interchangeably:\n-\n------------------------------------------------------------------------\n-$ git rev-list origin..HEAD\n-$ git rev-list HEAD ^origin\n------------------------------------------------------------------------\n-\n-Another special notation is \"''...''\" which is useful\n-for merges. The resulting set of commits is the symmetric difference\n-between the two operands. The following two commands are equivalent:\n-\n------------------------------------------------------------------------\n-$ git rev-list A B --not $(git merge-base --all A B)\n-$ git rev-list A...B\n------------------------------------------------------------------------\n+include::rev-list-description.txt[]\n \n 'rev-list' is a very essential Git command, since it\n provides the ability to build and traverse commit ancestry graphs. For\ndiff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt\nnew file mode 100644\nindex 0000000000..14d78b91aa\n--- /dev/null\n+++ b/Documentation/rev-list-description.txt\n@@ -0,0 +1,38 @@\n+List commits that are reachable by following the `parent` links from the\n+given commit(s), but exclude commits that are reachable from the one(s)\n+given with a '{caret}' in front of them. The output is given in reverse\n+chronological order by default.\n+\n+You can think of this as a set operation. Commits reachable from any of\n+the commits given on the command line form a set, and then commits reachable\n+from any of the ones given with '{caret}' in front are subtracted from that\n+set. The remaining commits are what comes out in the command's output.\n+Various other options and paths parameters can be used to further limit the\n+result.\n+\n+Thus, the following command:\n+\n+-----------------------------------------------------------------------\n+$ git rev-list foo bar ^baz\n+-----------------------------------------------------------------------\n+\n+means \"list all the commits which are reachable from 'foo' or 'bar', but\n+not from 'baz'\".\n+\n+A special notation \"''..''\" can be used as a\n+short-hand for \"^'' ''\". For example, either of\n+the following may be used interchangeably:\n+\n+-----------------------------------------------------------------------\n+$ git rev-list origin..HEAD\n+$ git rev-list HEAD ^origin\n+-----------------------------------------------------------------------\n+\n+Another special notation is \"''...''\" which is useful\n+for merges. The resulting set of commits is the symmetric difference\n+between the two operands. The following two commands are equivalent:\n+\n+-----------------------------------------------------------------------\n+$ git rev-list A B --not $(git merge-base --all A B)\n+$ git rev-list A...B\n+-----------------------------------------------------------------------\n-- \ngitgitgadget\n\n"},{"id":"401220","messageId":"d04b6c62a3186c4d244384887a555e7875130045.1594261008.git.gitgitgadget@gmail.com","threadId":"53125","inReplyTo":"pull.590.v3.git.1594261008.gitgitgadget@gmail.com","subject":"[PATCH v3 6/6] git-log.txt: include rev-list-description.txt","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-07-09T02:16:48Z","receivedAt":"2020-07-09T02:17:06Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe `git log` synopsis mentions ``, and the description\nof this option links to gitrevisions(7), but a nice explanation of\nhow a revision range can be constructed from individual commits,\noptionnally prefixed with `^`, also exists in `rev-list-description.txt`.\n\nInclude this description in the man page for `git log`.\n\nAdd Asciidoc 'ifdef's to `rev-list-description.txt` so that either `git\nrev-list` or `git log` appears in the respective man pages.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-log.txt | 3 +++\n Documentation/git-rev-list.txt | 1 +\n Documentation/rev-list-description.txt | 23 +++++++++++++++++++++++\n 3 files changed, 27 insertions(+)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 0fcaf34d62..3fd26d5212 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -15,6 +15,9 @@ DESCRIPTION\n -----------\n Shows the commit logs.\n \n+:git-log: 1\n+include::rev-list-description.txt[]\n+\n The command takes options applicable to the linkgit:git-rev-list[1]\n command to control what is shown and how, and options applicable to\n the linkgit:git-diff[1] command to control how the changes\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex b06e11ae56..5da66232dc 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -14,6 +14,7 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n+:git-rev-list: 1\n include::rev-list-description.txt[]\n \n 'rev-list' is a very essential Git command, since it\ndiff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt\nindex 14d78b91aa..a9efa7fa27 100644\n--- a/Documentation/rev-list-description.txt\n+++ b/Documentation/rev-list-description.txt\n@@ -12,9 +12,16 @@ result.\n \n Thus, the following command:\n \n+ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n $ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n+endif::git-rev-list[]\n+ifdef::git-log[]\n+-----------------------------------------------------------------------\n+$ git log foo bar ^baz\n+-----------------------------------------------------------------------\n+endif::git-log[]\n \n means \"list all the commits which are reachable from 'foo' or 'bar', but\n not from 'baz'\".\n@@ -23,16 +30,32 @@ A special notation \"''..''\" can be used as a\n short-hand for \"^'' ''\". For example, either of\n the following may be used interchangeably:\n \n+ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n $ git rev-list origin..HEAD\n $ git rev-list HEAD ^origin\n -----------------------------------------------------------------------\n+endif::git-rev-list[]\n+ifdef::git-log[]\n+-----------------------------------------------------------------------\n+$ git log origin..HEAD\n+$ git log HEAD ^origin\n+-----------------------------------------------------------------------\n+endif::git-log[]\n \n Another special notation is \"''...''\" which is useful\n for merges. The resulting set of commits is the symmetric difference\n between the two operands. The following two commands are equivalent:\n \n+ifdef::git-rev-list[]\n -----------------------------------------------------------------------\n $ git rev-list A B --not $(git merge-base --all A B)\n $ git rev-list A...B\n -----------------------------------------------------------------------\n+endif::git-rev-list[]\n+ifdef::git-log[]\n+-----------------------------------------------------------------------\n+$ git log A B --not $(git merge-base --all A B)\n+$ git log A...B\n+-----------------------------------------------------------------------\n+endif::git-log[]\n-- \ngitgitgadget\n"}]}