Re: [PATCH] blame: document actual range specifier behavior

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 9, 2019, 16:58 UTC
Message-ID: <xmqqblwye0nn.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <xmqqsgqbfucj.fsf@gitster-ct.c.googlers.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 5 quoted lines

> ...  If anything,
> perhaps such a description should go to "git help revisions", as it
> is not just "blame" but "log". "The dots notation is not about
> date-based cutoff, unlike the --since/--until options" is shared by
> all history traversal tools.

By this, I do not necessarily mean "hence such a piece of info should not be added to the documentation of blame". Rather, an explanation like "'^A' limits an operation to commits that are topologically newer than A, while '--since=A' limits to commits that are chronologically newer than A" is shared among "log", "blame" and friends, and would be better to be clarified in documentation for all of them. Especially ...

Show 6 quoted lines

>> +  git blame v2.6.18.. -- foo
>> +
>> +... If changes from branch `fix` were merged in after
>> +v2.6.18, the commits on `fix` which introduced those changes will appear
>> +in the output of 'git blame', even if those commits took place at an
>> +earlier time than v2.6.18.

... is a brilliant way to illustrate how "A.., i.e. topologically newer than A" is different from "--since=A, i.e. chronologically newer than A", whose understanding would help readers to understand not just "blame" but "log".

Thanks.