Re: [PATCH v2 6/7] Documentation: put blame/log -L in sticked form

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 30, 2013, 01:11 UTC
Message-ID: <xmqqvc0fd0la.fsf@gitster.dls.corp.google.com>
In-Reply-To: <c41aef218951f8b0ec6a20e1dbc39712ad13afce.1383031141.git.tr@thomasrast.ch>

Thomas Rast <tr@thomasrast.ch> writes:

> The next patch will document gitk -L, but gitk does not understand the
> separated form ('gitk -L :foo:bar' results in an error).  Spell
> git-blame and git-log -L, which are supposed to be "the same" option,
> without the spaces to prevent confusion.

I agree that this patch may reduce confusion locally, but if we were to go in this direction, we should be consistent and enforce "stuck" form everywhere, not just the options you happened to have passed thru to gitk, but other options such as "-S <revs-file>", and also other commands that do not have anything to do with gitk (e.g. "git commit -C<commit>", not "git commit -C <commit>". Otherwise you will give a wrong impression to readers as if they have to remember which ones need to use the stuck form and which ones do not.

Show 82 quoted lines

> Signed-off-by: Thomas Rast <tr@thomasrast.ch>
> ---
>  Documentation/blame-options.txt | 8 ++++----
>  Documentation/git-blame.txt     | 8 ++++----
>  Documentation/git-log.txt       | 6 +++---
>  3 files changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
> index 0cebc4f..28ca95e 100644
> --- a/Documentation/blame-options.txt
> +++ b/Documentation/blame-options.txt
> @@ -9,13 +9,13 @@
>  --show-stats::
>  	Include additional statistics at the end of blame output.
>  
> --L <start>,<end>::
> --L :<regex>::
> +-L<start>,<end>::
> +-L:<regex>::
>  	Annotate only the given line range. May be specified multiple times.
>  	Overlapping ranges are allowed.
>  +
> -<start> and <end> are optional. ``-L <start>'' or ``-L <start>,'' spans from
> -<start> to end of file. ``-L ,<end>'' spans from start of file to <end>.
> +<start> and <end> are optional. ``-L<start>'' or ``-L<start>,'' spans from
> +<start> to end of file. ``-L,<end>'' spans from start of file to <end>.
>  +
>  include::line-range-format.txt[]
>  
> diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
> index f2c85cc..085dba1 100644
> --- a/Documentation/git-blame.txt
> +++ b/Documentation/git-blame.txt
> @@ -9,7 +9,7 @@ SYNOPSIS
>  --------
>  [verse]
>  'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
> -	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
> +	    [-L<range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
>  	    [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file>
>  
>  DESCRIPTION
> @@ -139,12 +139,12 @@ lines 40-60 for file `foo`, you can use the `-L` option like so
>  (they mean the same thing -- both ask for 21 lines starting at
>  line 40):
>  
> -	git blame -L 40,60 foo
> -	git blame -L 40,+21 foo
> +	git blame -L40,60 foo
> +	git blame -L40,+21 foo
>  
>  Also you can use a regular expression to specify the line range:
>  
> -	git blame -L '/^sub hello {/,/^}$/' foo
> +	git blame -L'/^sub hello {/,/^}$/' foo
>  
>  which limits the annotation to the body of the `hello` subroutine.
>  
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index 34097ef..87c10fa 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -62,8 +62,8 @@ produced by --stat etc.
>  	Note that only message is considered, if also a diff is shown
>  	its size is not included.
>  
> --L <start>,<end>:<file>::
> --L :<regex>:<file>::
> +-L<start>,<end>:<file>::
> +-L:<regex>:<file>::
>  
>  	Trace the evolution of the line range given by "<start>,<end>"
>  	(or the funcname regex <regex>) within the <file>.  You may
> @@ -152,7 +152,7 @@ EXAMPLES
>  	This makes sense only when following a strict policy of merging all
>  	topic branches when staying on a single integration branch.
>  
> -`git log -L '/int main/',/^}/:main.c`::
> +`git log -L'/int main/',/^}/:main.c`::
>  
>  	Shows how the function `main()` in the file 'main.c' evolved
>  	over time.