{"thread":{"id":"46633","subject":"What does 'git blame --before -- ' supposed to mean?","startedAt":"2017-08-20T18:45:17Z","lastAt":"2017-08-24T16:35:12Z","messageCount":3,"participants":["Kaartic Sivaraam","Kevin Daudt","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"326826","messageId":"1503254759.3881.9.camel@gmail.com","threadId":"46633","inReplyTo":null,"subject":"What does 'git blame --before -- ' supposed to mean?","fromName":"Kaartic Sivaraam","fromEmail":"kaarticsivaraam91196@gmail.com","sentAt":"2017-08-20T18:45:59Z","receivedAt":"2017-08-20T18:45:17Z","isPatch":false,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Hello all,\n\nI tried to do a 'git blame' on a file and wanted to see the blame\nbefore a particular revision of that file. I initially didn't know that\nyou could achieve that with,\n\n    $ git blame \n\nI thought I need to pass the revision as a parameter so I tried (before\nlooking into the documentation) the command found in the subject. It\nworked but to my surprise it had the same result as,\n\n    $ git blame -- \n\nI was confused and came to know from the documentation that blame\ndoesn't have any '--before' option. That was even more surprising. Why\ndoes blame accept an option which it doesn't identify? Shouldn't it\nhave warned that it doesn't accept the '--before' option? I guess it\nshould not accept it because it confuses the user a lot as the could\nmake it hard time for him to identify the issue.\n\n'git blame' doesn't seem to be the only command that accepts options\nnot specified in the documentation there's 'git show' for it's company,\n\n    $ git show --grep 'regex'\n\nBut the good thing with the above command is it behaves as expected. I\nsuspect this should be documented, anyway.\n\nThoughts ?\n\n-- \nKaartic\n"},{"id":"327113","messageId":"20170824075848.GG3839@alpha.vpn.ikke.info","threadId":"46633","inReplyTo":"1503254759.3881.9.camel@gmail.com","subject":"Re: What does 'git blame --before -- ' supposed to mean?","fromName":"Kevin Daudt","fromEmail":"me@ikke.info","sentAt":"2017-08-24T07:58:48Z","receivedAt":"2017-08-24T08:01:58Z","isPatch":false,"sender":{"key":"me@ikke.info","avatar":"https://avatars.githubusercontent.com/u/135698?v=4"},"body":"On Mon, Aug 21, 2017 at 12:15:59AM +0530, Kaartic Sivaraam wrote:\n> Hello all,\n> \n> I tried to do a 'git blame' on a file and wanted to see the blame\n> before a particular revision of that file. I initially didn't know that\n> you could achieve that with,\n> \n>     $ git blame \n> \n> I thought I need to pass the revision as a parameter so I tried (before\n> looking into the documentation) the command found in the subject. It\n> worked but to my surprise it had the same result as,\n> \n>     $ git blame -- \n> \n> I was confused and came to know from the documentation that blame\n> doesn't have any '--before' option. That was even more surprising. Why\n> does blame accept an option which it doesn't identify? Shouldn't it\n> have warned that it doesn't accept the '--before' option? I guess it\n> should not accept it because it confuses the user a lot as the could\n> make it hard time for him to identify the issue.\n> \n> 'git blame' doesn't seem to be the only command that accepts options\n> not specified in the documentation there's 'git show' for it's company,\n> \n>     $ git show --grep 'regex'\n> \n> But the good thing with the above command is it behaves as expected. I\n> suspect this should be documented, anyway.\n> \n> Thoughts ?\n> \n> -- \n> Kaartic\n\nGit blame takes options that are fed to git rev-list, to limit the\ncommits being taken into account for blaming.\n\nThe man page shows \"[--since=]\", which is one such option, but\nbefore is valid as well.\n\ngit blame -h shows:\n\n are documented in git-rev-list(1) \n\nand man git-blame shows under specifying ranges (emphasis mine): \n\n When you are not interested in changes older than version v2.6.18,\n or changes older than 3 weeks, *you can use revision range\n specifiers similar to git rev-list*:\n\nSo these options are not documented under git blame, but git rev-list.\n\nPerhaps the synopsis of man git-blame could be expanded so that that\nit's clear it accepts rev-list options.\n\nKevin\n"},{"id":"327137","messageId":"xmqqy3q8x6tk.fsf@gitster.mtv.corp.google.com","threadId":"46633","inReplyTo":"20170824075848.GG3839@alpha.vpn.ikke.info","subject":"Re: What does 'git blame --before -- ' supposed to mean?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-08-24T16:35:03Z","receivedAt":"2017-08-24T16:35:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kevin Daudt writes:\n\n> Git blame takes options that are fed to git rev-list, to limit the\n> commits being taken into account for blaming.\n>\n> The man page shows \"[--since=]\", which is one such option, but\n> before is valid as well.\n>\n> git blame -h shows:\n>\n> are documented in git-rev-list(1) \n>\n> and man git-blame shows under specifying ranges (emphasis mine): \n>\n> When you are not interested in changes older than version v2.6.18,\n> or changes older than 3 weeks, *you can use revision range\n> specifiers similar to git rev-list*:\n>\n> So these options are not documented under git blame, but git rev-list.\n>\n> Perhaps the synopsis of man git-blame could be expanded so that that\n> it's clear it accepts rev-list options.\n\nWhile nothing in what you said is incorrect per-se, many options\nthat rev-list takes are parsed but then ignored by blame, simply\nbecause they do not make much sense in the context of the command,\nand \"--before\" is one of them. \n\nIt is interesting to realize that \"--since\" (and its synonym\n\"--after\") does make sense, unlike \"--before\" (and its synonym\n\"--until\") which does not.\n\nLet's imagine a history like this (time flows from left to right):\n\n --c1--c2--c4--c6--c8--c9\n \\ /\n c3--c5--c7\n\nwhere the tip of the history is at commit \"c9\", and the number in\nthe name of each commit denotes its timestamp.\n\n - \"git rev-list c9\" starts from \"c9\", and follows the chain of\n parents and would produce c9, c8, c7, c6, ..., c1, ....\n\n - If you add \"--after 2\", i.e. \"git rev-list --after 2 c9\" does\n exactly the same traversal as the above, but stops following the\n chain of parents for commits that is earlier than the specified\n time.\n\n - If you add \"--before 6\", i.e. \"git rev-list --before 6 c9\" does\n exactly the same traversal as the first one, but does not show\n the commit whose timestamp is later than the specified time. It\n would be like saying \"git rev-list c5 c6\" in the above topology;\n the traversal from c9 down to c5 and c6 is done only to find c5\n and c6 to start the \"real\" traversal from. \n\nNow, \"--after 2\" will still show \"c9\", the tip you start your\ntraversal from, and this is important in the context of \"blame\".\n\nUnlike \"git rev-list\" (and \"git log\" family of commands), which can\ntake more than one positive endpoints in the history (e.g. it is\nperfectly sensible to ask \"git log -p ^c1 c5 c6 -- myfile\" in the\nexample topology above), \"git blame\" must be given exactly one\npositive endpoint, as \"git blame ^c1 c5 c6 -- myfile\" would not make\nany sense (ask: \"do we want to know about myfile in c5? or myfile\nin c6?\").\n\nI think we also ignore \"-n 4\" in \"blame -n 4 c9 -- myfile\" (I didn't\ncheck), but that is not because the operation fundamentally does not\nmake sense (like \"--until\") but because whoever wrote \"blame\" did\nnot think of the need to support it---in other words, if somebody\nwants to add support for that option, I offhand do not see a\nfundamental reason to reject it.\n\nI do think appearing to take and understand and then silently\nignoring an option is bad, and it will help users if we tighten the\nerror checking while parsing the command line.\n\n"}]}