From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 04 May 2010 17:31:11 GMT
Subject: Re: [PATCH v2] blame: add a range option to -L
Message-ID: <7vd3xbmv4w.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1272909995-3198-1-git-send-email-wfp5p@virginia.edu>

Bill Pemberton <wfp5p@virginia.edu> writes:

> In addition to <start>,<end> you can now use <center>%<radius>
> to specify how many lines around <center> that you want to see.
> For example: -L 20%5 would show lines 15 through 25
>
> Signed-off-by: Bill Pemberton <wfp5p@virginia.edu>
> ---

Please retitle, as (1) -L has always been about "range", and (2) what you
are adding now is a "radius" option ;-)

> +-L <center>%<radius>::
> +	This works like <start>,<end> with the annotated range
> +	centered on <center> and showing <radius> lines around it.

I am not sure how "like <start>,<end>" in this sentence helps the readers.
If you bring up the similarity, shouldn't you at least be saying that it
is an shorthand to give "<radius> lines before <center>" as <start>, and
"<radius> lines after <center>" as <end>, or somesuch?

> diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
> index a27f439..73f6b83 100644
> --- a/Documentation/git-blame.txt
> +++ b/Documentation/git-blame.txt
> @@ -110,6 +110,14 @@ line 40):
>  	git blame -L 40,60 foo
>  	git blame -L 40,+21 foo
>  
> +A range of lines around a particular line can be shown by using '%'
> +instead of ','.  If you wanted to see line 20 along with the 5
> +lines around it:
> +
> +       git blame -L 20%5 foo
> +
> +
> +

Why this many blank lines around the example?

I see this at the beginning of parse_loc() in builtin/blame.c:

	/* Allow "-L <something>,+20" to mean starting at <something>
	 * for 20 lines, or "-L <something>,-5" for 5 lines ending at
	 * <something>.
	 */

which means that it is not "-L <start>,<end>" to begin with.  I wonder if
it makes the interface more consistent to rewrite the above comment like
this:

	/*
	 * Allow "-L <something>,+20" to mean starting at <something>
	 * for 20 lines; "-L <something>,-5" for 5 lines ending at
	 * <something>; and "-L <something>,+-5" for 5 lines around
         * <something>.
	 */

and the match the code.