{"thread":{"id":"5445","subject":"[PATCH] git-rev-list(1): group options; reformat; document more options","startedAt":"2006-08-31T22:37:15Z","lastAt":"2006-09-01T20:33:48Z","messageCount":6,"participants":["Jonas Fonseca","Linus Torvalds","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"26166","messageId":"20060831223715.GC482@diku.dk","threadId":"5445","inReplyTo":null,"subject":"[PATCH] git-rev-list(1): group options; reformat; document more options","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2006-08-31T22:37:15Z","receivedAt":"2006-08-31T22:37:15Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Signed-off-by: Jonas Fonseca <fonseca@diku.dk>\n---\n Documentation/git-rev-list.txt |  254 ++++++++++++++++++++++++++++++----------\n 1 files changed, 188 insertions(+), 66 deletions(-)\n\nAn attempted facelift to the neglected git-rev-list manpage. One\nquestion if I may, the diff-related -r and -t options, how are they\nsupposed to work?\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex a446a6b..d6c86db 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -27,111 +27,233 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n+\n Lists commit objects in reverse chronological order starting at the\n given commit(s), taking ancestry relationship into account.  This is\n useful to produce human-readable log output.\n \n-Commits which are stated with a preceding '{caret}' cause listing to stop at\n-that point. Their parents are implied. \"git-rev-list foo bar {caret}baz\" thus\n+Commits which are stated with a preceding '{caret}' cause listing to\n+stop at that point. Their parents are implied. Thus the following\n+command:\n+\n+-----------------------------------------------------------------------\n+\t$ git-rev-list foo bar ^baz\n+-----------------------------------------------------------------------\n+\n means \"list all the commits which are included in 'foo' and 'bar', but\n not in 'baz'\".\n \n-A special notation <commit1>..<commit2> can be used as a\n-short-hand for {caret}<commit1> <commit2>.\n+A special notation \"'<commit1>'..'<commit2>'\" can be used as a\n+short-hand for \"{caret}'<commit1>' '<commit2>'\". For example, either of\n+the following may be used interchangeably:\n \n-Another special notation is <commit1>...<commit2> which is useful for\n-merges.  The resulting set of commits is the symmetric difference\n+-----------------------------------------------------------------------\n+\t$ git-rev-list origin..HEAD\n+\t$ git-rev-list HEAD ^origin\n+-----------------------------------------------------------------------\n+\n+Another special notation is \"'<commit1>'...'<commit2>'\" 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+-----------------------------------------------------------------------\n+\t$ git-rev-list A B --not $(git-merge-base --all A B)\n+\t$ git-rev-list A...B\n+-----------------------------------------------------------------------\n+\n+gitlink:git-rev-list[1] is a very essential git program, since it\n+provides the ability to build and traverse commit ancestry graphs. For\n+this reason, it has a lot of different options that enables it to be\n+used by commands as different as gitlink:git-bisect[1] and\n+gitlink:git-repack[1].\n \n OPTIONS\n -------\n---pretty::\n-\tPrint the contents of the commit changesets in human-readable form.\n+\n+Commit Formatting\n+~~~~~~~~~~~~~~~~~\n+\n+Using these options, gitlink:git-rev-list[1] will act similar to the\n+more specialized family of commit log tools: gitlink:git-log[1],\n+gitlink:git-show[1], and gitlink:git-whatchanged[1]\n+\n+--pretty[='<format>']::\n+\n+\tPretty print the contents of the commit logs in a given format,\n+\twhere '<format>' can be one of 'raw', 'medium', 'short', 'full',\n+\tand 'oneline'. When left out the format default to 'medium'.\n+\n+--relative-date::\n+\n+\tShow dates relative to the current time, e.g. \"2 hours ago\".\n+\tOnly takes effect for dates shown in human-readable format, such\n+\tas when using \"--pretty\".\n \n --header::\n-\tPrint the contents of the commit in raw-format; each\n-\trecord is separated with a NUL character.\n+\n+\tPrint the contents of the commit in raw-format; each record is\n+\tseparated with a NUL character.\n \n --parents::\n+\n \tPrint the parents of the commit.\n \n---objects::\n-\tPrint the object IDs of any object referenced by the listed commits.\n-\t'git-rev-list --objects foo ^bar' thus means \"send me all object IDs\n-\twhich I need to download if I have the commit object 'bar', but\n-\tnot 'foo'\".\n+Diff Formatting\n+~~~~~~~~~~~~~~~\n \n---objects-edge::\n-\tSimilar to `--objects`, but also print the IDs of\n-\texcluded commits prefixed with a `-` character.  This is\n-\tused by `git-pack-objects` to build 'thin' pack, which\n-\trecords objects in deltified form based on objects\n-\tcontained in these excluded commits to reduce network\n-\ttraffic.\n+Below are listed options that control the formatting of diff output.\n+Some of them are specific to gitlink:git-rev-list[1], however other diff\n+options may be given. See gitlink:git-diff-files[1] for more options.\n \n---unpacked::\n-\tOnly useful with `--objects`; print the object IDs that\n-\tare not in packs.\n+-c::\n+\n+\tThis flag changes the way a merge commit is displayed.  It shows\n+\tthe differences from each of the parents to the merge result\n+\tsimultaneously instead of showing pairwise diff between a parent\n+\tand the result one at a time. Furthermore, it lists only files\n+\twhich were modified from all parents.\n+\n+--cc::\n+\n+\tThis flag implies the '-c' options and further compresses the\n+\tpatch output by omitting hunks that show differences from only\n+\tone parent, or show the same change from all but one parent for\n+\tan Octopus merge.\n+\n+-r::\n+\n+\tShow recursive diffs.\n+\n+-t::\n+\n+\tShow the tree objects in the diff output. This implies '-r'.\n+\n+Commit Limiting\n+~~~~~~~~~~~~~~~\n+\n+Besides specifying a range of commits that should be listed using the\n+special notations explained in the description, additional commit\n+limiting may be applied.\n+\n+--\n+\n+-n 'number', --max-count='number'::\n \n---bisect::\n-\tLimit output to the one commit object which is roughly halfway\n-\tbetween the included and excluded commits. Thus, if 'git-rev-list\n-\t--bisect foo {caret}bar {caret}baz' outputs 'midpoint', the output\n-\tof 'git-rev-list foo {caret}midpoint' and 'git-rev-list midpoint\n-\t{caret}bar {caret}baz' would be of roughly the same length.\n-\tFinding the change\n-\twhich introduces a regression is thus reduced to a binary search:\n-\trepeatedly generate and test new 'midpoint's until the commit chain\n-\tis of length one.\n-\n---max-count::\n \tLimit the number of commits output.\n \n---max-age=timestamp, --min-age=timestamp::\n-\tLimit the commits output to specified time range.\n+--since='date', --after='date'::\n+\n+\tShow commits more recent than a specific date.\n+\n+--until='date', --before='date'::\n \n---sparse::\n-\tWhen optional paths are given, the command outputs only\n-\tthe commits that changes at least one of them, and also\n-\tignores merges that do not touch the given paths.  This\n-\tflag makes the command output all eligible commits\n-\t(still subject to count and age limitation), but apply\n-\tmerge simplification nevertheless.\n+\tShow commits older than a specific date.\n+\n+--max-age='timestamp', --min-age='timestamp'::\n+\n+\tLimit the commits output to specified time range.\n \n --remove-empty::\n+\n \tStop when a given path disappears from the tree.\n \n --no-merges::\n+\n \tDo not print commits with more than one parent.\n \n --not::\n-\tReverses the meaning of the '{caret}' prefix (or lack\n-\tthereof) for all following revision specifiers, up to\n-\tthe next `--not`.\n+\n+\tReverses the meaning of the '{caret}' prefix (or lack thereof)\n+\tfor all following revision specifiers, up to the next '--not'.\n \n --all::\n-\tPretend as if all the refs in `$GIT_DIR/refs/` are\n-\tlisted on the command line as <commit>.\n \n---topo-order::\n-\tBy default, the commits are shown in reverse\n-\tchronological order.  This option makes them appear in\n-\ttopological order (i.e. descendant commits are shown\n-\tbefore their parents).\n+\tPretend as if all the refs in `$GIT_DIR/refs/` are listed on the\n+\tcommand line as '<commit>'.\n \n --merge::\n+\n \tAfter a failed merge, show refs that touch files having a\n \tconflict and don't exist on all heads to merge.\n \n---relative-date::\n-\tShow dates relative to the current time, e.g. \"2 hours ago\".\n-\tOnly takes effect for dates shown in human-readable format,\n-\tsuch as when using \"--pretty\".\n+--boundary::\n+\n+\tOutput uninteresting commits at the boundary, which are usually\n+\tnot shown.\n+\n+--dense, --sparse::\n+\n+When optional paths are given, the default behaviour ('--dense') is to\n+only output commits that changes at least one of them, and also ignore\n+merges that do not touch the given paths.\n+\n+Use the '--sparse' flag to makes the command output all eligible commits\n+(still subject to count and age limitation), but apply merge\n+simplification nevertheless.\n+\n+--bisect::\n+\n+Limit output to the one commit object which is roughly halfway between\n+the included and excluded commits. Thus, if\n+\n+-----------------------------------------------------------------------\n+\t$ git-rev-list --bisect foo ^bar ^baz\n+-----------------------------------------------------------------------\n+\n+outputs 'midpoint', the output of the two commands\n+\n+-----------------------------------------------------------------------\n+\t$ git-rev-list foo ^midpoint\n+\t$ git-rev-list midpoint ^bar ^baz\n+-----------------------------------------------------------------------\n+\n+would be of roughly the same length.  Finding the change which\n+introduces a regression is thus reduced to a binary search: repeatedly\n+generate and test new 'midpoint's until the commit chain is of length\n+one.\n+\n+--\n+\n+Commit Ordering\n+~~~~~~~~~~~~~~~\n+\n+By default, the commits are shown in reverse chronological order.\n+\n+--topo-order::\n+\n+\tThis option makes them appear in topological order (i.e.\n+\tdescendant commits are shown before their parents).\n+\n+--date-order::\n+\n+\tThis option is similar to '--topo-order' in the sense that no\n+\tparent comes before all of its children, but otherwise things\n+\tare still ordered in the commit timestamp order.\n+\n+Object Traversal\n+~~~~~~~~~~~~~~~~\n+\n+These options are mostly targeted for packing of git repositories.\n+\n+--objects::\n+\n+\tPrint the object IDs of any object referenced by the listed\n+\tcommits.  'git-rev-list --objects foo ^bar' thus means \"send me\n+\tall object IDs which I need to download if I have the commit\n+\tobject 'bar', but not 'foo'\".\n+\n+--objects-edge::\n+\n+\tSimilar to '--objects', but also print the IDs of excluded\n+\tcommits prefixed with a \"-\" character.  This is used by\n+\tgitlink:git-pack-objects[1] to build \"thin\" pack, which records\n+\tobjects in deltified form based on objects contained in these\n+\texcluded commits to reduce network traffic.\n+\n+--unpacked::\n+\n+\tOnly useful with '--objects'; print the object IDs that are not\n+\tin packs.\n \n Author\n ------\n@@ -139,9 +261,9 @@ Written by Linus Torvalds <torvalds@osdl\n \n Documentation\n --------------\n-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.\n+Documentation by David Greaves, Junio C Hamano and the git-list\n+<git@vger.kernel.org>.\n \n GIT\n ---\n Part of the gitlink:git[7] suite\n-\n-- \n1.4.2.g2ba6b-dirty\n\n-- \nJonas Fonseca\n"},{"id":"26169","messageId":"Pine.LNX.4.64.0608311557470.27779@g5.osdl.org","threadId":"5445","inReplyTo":"20060831223715.GC482@diku.dk","subject":"Re: [PATCH] git-rev-list(1): group options; reformat; document more options","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2006-08-31T23:02:56Z","receivedAt":"2006-08-31T23:02:56Z","isPatch":true,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Fri, 1 Sep 2006, Jonas Fonseca wrote:\n>\n> An attempted facelift to the neglected git-rev-list manpage. One\n> question if I may, the diff-related -r and -t options, how are they\n> supposed to work?\n\nUmm? You should get a \"usage\" error, no?\n\n\t\tLinus\n"},{"id":"26170","messageId":"20060831230811.GE482@diku.dk","threadId":"5445","inReplyTo":"Pine.LNX.4.64.0608311557470.27779@g5.osdl.org","subject":"Re: [PATCH] git-rev-list(1): group options; reformat; document more options","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2006-08-31T23:08:11Z","receivedAt":"2006-08-31T23:08:11Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Linus Torvalds <torvalds@osdl.org> wrote Thu, Aug 31, 2006:\n> \n> \n> On Fri, 1 Sep 2006, Jonas Fonseca wrote:\n> >\n> > An attempted facelift to the neglected git-rev-list manpage. One\n> > question if I may, the diff-related -r and -t options, how are they\n> > supposed to work?\n> \n> Umm? You should get a \"usage\" error, no?\n\nYes, ok, they do not seem to make sense for git-rev-list, however if you\npass either to git-log, the output seems to make room for a diff, adding\none extra newline, but without appending any diff.\n\n-- \nJonas Fonseca\n"},{"id":"26173","messageId":"Pine.LNX.4.64.0608311611440.27779@g5.osdl.org","threadId":"5445","inReplyTo":"20060831230811.GE482@diku.dk","subject":"Re: [PATCH] git-rev-list(1): group options; reformat; document more options","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2006-08-31T23:15:39Z","receivedAt":"2006-08-31T23:15:39Z","isPatch":true,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Fri, 1 Sep 2006, Jonas Fonseca wrote:\n> Linus Torvalds <torvalds@osdl.org> wrote Thu, Aug 31, 2006:\n> > \n> > Umm? You should get a \"usage\" error, no?\n> \n> Yes, ok, they do not seem to make sense for git-rev-list, however if you\n> pass either to git-log, the output seems to make room for a diff, adding\n> one extra newline, but without appending any diff.\n\nAhh. I think that a \"-r\" without any other request for patches (or \n\"--name-status\" or similar) should probably imply \"--raw\". At least that \nwas how it historically worked..\n\nAnyway, _if_ it ever worked (and I think it did, but I'm way too lazy to \nbother checking), this may have been broken by the extensive diff option \ncleanups by Timo in June. Timo? Junio?\n\n\t\t\tLinus\n"},{"id":"26174","messageId":"7vsljc78m9.fsf@assigned-by-dhcp.cox.net","threadId":"5445","inReplyTo":"Pine.LNX.4.64.0608311611440.27779@g5.osdl.org","subject":"Re: [PATCH] git-rev-list(1): group options; reformat; document more options","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-09-01T00:06:54Z","receivedAt":"2006-09-01T00:06:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Torvalds <torvalds@osdl.org> writes:\n\n> On Fri, 1 Sep 2006, Jonas Fonseca wrote:\n>> Linus Torvalds <torvalds@osdl.org> wrote Thu, Aug 31, 2006:\n>> > \n>> > Umm? You should get a \"usage\" error, no?\n>> \n>> Yes, ok, they do not seem to make sense for git-rev-list, however if you\n>> pass either to git-log, the output seems to make room for a diff, adding\n>> one extra newline, but without appending any diff.\n>\n> Ahh. I think that a \"-r\" without any other request for patches (or \n> \"--name-status\" or similar) should probably imply \"--raw\". At least that \n> was how it historically worked..\n>\n> Anyway, _if_ it ever worked (and I think it did, but I'm way too lazy to \n> bother checking), this may have been broken by the extensive diff option \n> cleanups by Timo in June. Timo? Junio?\n\nI think it did too.  I am kind of surprised that nobody noticed\nand t4013 test (which was done specifically to catch potential\nbehaviour change by Timo's patch) did not check for this\nparticular case.\n"},{"id":"26195","messageId":"20060901203348.GA27515@diku.dk","threadId":"5445","inReplyTo":"7vsljc78m9.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] git-rev-list(1): group options; reformat; document more options","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2006-09-01T20:33:48Z","receivedAt":"2006-09-01T20:33:48Z","isPatch":true,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Junio C Hamano <junkio@cox.net> wrote Thu, Aug 31, 2006:\n> Linus Torvalds <torvalds@osdl.org> writes:\n> \n> > On Fri, 1 Sep 2006, Jonas Fonseca wrote:\n> >\n> >> [The \"-r\" and \"-t\" option] do not seem to make sense for\n> >> git-rev-list, however if you pass either to git-log, the output\n> >> seems to make room for a diff, adding one extra newline, but\n> >> without appending any diff.\n> >\n> > Ahh. I think that a \"-r\" without any other request for patches (or\n> > \"--name-status\" or similar) should probably imply \"--raw\". At least\n> > that was how it historically worked..\n\n:set paste\n\ncommit 17985627455901b6ae3a471b67d46239463cebb5\nAuthor: Timo Hirvonen <tihirvon@gmail.com>\nDate:   Tue Jun 27 16:27:51 2006 +0300\n\n    log --raw: Don't descend into subdirectories by default\n\n    Only do so when -r is given.\n\n> > Anyway, _if_ it ever worked (and I think it did, but I'm way too lazy to \n> > bother checking), this may have been broken by the extensive diff option \n> > cleanups by Timo in June. Timo? Junio?\n> \n> I think it did too.  I am kind of surprised that nobody noticed\n> and t4013 test (which was done specifically to catch potential\n> behaviour change by Timo's patch) did not check for this\n> particular case.\n\ncommit 0e677e1a6b0d1c0e848ed19d18dda1c3c797c75e\nAuthor: Timo Hirvonen <tihirvon@gmail.com>\nDate:   Sat Jun 24 20:25:08 2006 +0300\n\n    DIFF_FORMAT_RAW is not default anymore\n\n    diff_setup() used to initialize output_format to DIFF_FORMAT_RAW.  Now\n    the default is 0 (no output) so don't compare against DIFF_FORMAT_RAW to\n    see if any diff format command line flags were given.\n\n:set nopaste\n\nSo they are working as intended. I'll look into updating the patch.\n\nBTW, --author=timo made this very easy. ;)\n\n-- \nJonas Fonseca\n\n-- \nVGER BF report: U 0.5\n"}]}