Re: [PATCH] blame: prevent error if range ends past end of file

On 30/5/18 6:45 pm, Eric Sunshine wrote:

quoted

diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt

@@ -152,6 +152,16 @@ Also you can use a regular expression to specify the line range:
 which limits the annotation to the body of the `hello` subroutine.

+A range that begins or ends outside the bounds of the file will
+blame the relevant lines. For example:
+
+       git blame -L 10,-20 foo
+       git blame -L 10,+20 foo
+
+will respectively blame the first 10 and last 11 lines of a
+20 line file. However, blaming a line range that is entirely
+outside the bounds of the file will fail.

This documentation seems misplaced. Rather than inserting it after the
discussion of -L/regex/, a more natural place would be just above
-L/regex/ where -L<begin>,<end> is discussed.

However, I am not at all convinced that this behavior should be
documented to this level of detail. Doing so assigns too much emphasis
to what should be intuitive, thus wastes readers' time wondering why
it is so heavily emphasized. At _most_, I would think you could say
merely:

    A range that begins or ends outside the bounds of the file
    will be clipped to the file's extent.

and drop the example and discussion of the example results altogether.

In fact, because this new behavior is what most users will intuitively
expect, it might be perfectly reasonable to not say anything about it
at all (that is, don't modify git-blame.txt)

Thanks for reviewing Eric. I've submitted a v6 patch in response to your
feedback.

I agree that given the behavior is intuitive it's not necessary to
document this change, so I've reverted the change to git-blame.txt
entirely.