What does 'git blame --before <rev> -- <file>' supposed to mean?

Hello all,

I tried to do a 'git blame' on a file and wanted to see the blame before a particular revision of that file. I initially didn't know that you could achieve that with,

    $ git blame <rev> <file>

I thought I need to pass the revision as a parameter so I tried (before looking into the documentation) the command found in the subject. It worked but to my surprise it had the same result as,

    $ git blame -- <file>

I was confused and came to know from the documentation that blame doesn't have any '--before' option. That was even more surprising. Why does blame accept an option which it doesn't identify? Shouldn't it have warned that it doesn't accept the '--before' option? I guess it should not accept it because it confuses the user a lot as the could make it hard time for him to identify the issue.

'git blame' doesn't seem to be the only command that accepts options not specified in the documentation there's 'git show' for it's company,

    $ git show --grep 'regex'

But the good thing with the above command is it behaves as expected. I suspect this should be documented, anyway.

Thoughts ?

--  Kaartic

On Mon, Aug 21, 2017 at 12:15:59AM +0530, Kaartic Sivaraam wrote:

Git blame takes options that are fed to git rev-list, to limit the commits being taken into account for blaming.

The man page shows "[--since=<date>]", which is one such option, but before is valid as well.

git blame -h shows:

    <rev-opts> are documented in git-rev-list(1) 

and man git-blame shows under specifying ranges (emphasis mine): 

     When you are not interested in changes older than version v2.6.18,
     or changes older than 3 weeks, *you can use revision range
     specifiers similar to git rev-list*:

So these options are not documented under git blame, but git rev-list.

Perhaps the synopsis of man git-blame could be expanded so that that it's clear it accepts rev-list options.

Kevin

Kevin Daudt <me@ikke.info> writes:

While nothing in what you said is incorrect per-se, many options that rev-list takes are parsed but then ignored by blame, simply because they do not make much sense in the context of the command, and "--before" is one of them.

It is interesting to realize that "--since" (and its synonym "--after") does make sense, unlike "--before" (and its synonym "--until") which does not.

Let's imagine a history like this (time flows from left to right):

     --c1--c2--c4--c6--c8--c9
             \         /
             c3--c5--c7

where the tip of the history is at commit "c9", and the number in the name of each commit denotes its timestamp.

 - "git rev-list c9" starts from "c9", and follows the chain of
   parents and would produce c9, c8, c7, c6, ..., c1, ....

 - If you add "--after 2", i.e. "git rev-list --after 2 c9" does
   exactly the same traversal as the above, but stops following the
   chain of parents for commits that is earlier than the specified
   time.

 - If you add "--before 6", i.e. "git rev-list --before 6 c9" does
   exactly the same traversal as the first one, but does not show
   the commit whose timestamp is later than the specified time.  It
   would be like saying "git rev-list c5 c6" in the above topology;
   the traversal from c9 down to c5 and c6 is done only to find c5
   and c6 to start the "real" traversal from. 

Now, "--after 2" will still show "c9", the tip you start your traversal from, and this is important in the context of "blame".

Unlike "git rev-list" (and "git log" family of commands), which can take more than one positive endpoints in the history (e.g. it is perfectly sensible to ask "git log -p ^c1 c5 c6 -- myfile" in the example topology above), "git blame" must be given exactly one positive endpoint, as "git blame ^c1 c5 c6 -- myfile" would not make any sense (ask: "do we want to know about myfile in c5? or myfile in c6?").

I think we also ignore "-n 4" in "blame -n 4 c9 -- myfile" (I didn't check), but that is not because the operation fundamentally does not make sense (like "--until") but because whoever wrote "blame" did not think of the need to support it---in other words, if somebody wants to add support for that option, I offhand do not see a fundamental reason to reject it.

I do think appearing to take and understand and then silently ignoring an option is bad, and it will help users if we tighten the error checking while parsing the command line.