From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 14 May 2013 17:41:52 GMT
Subject: Re: [PATCH] diffcore-pickaxe doc: document -S and -G properly
Message-ID: <7vwqr1jw67.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1368540759-25598-1-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

>  -S<string>::
> -	Look for differences that introduce or remove an instance of
> -	<string>. Note that this is different than the string simply
> -	appearing in diff output; see the 'pickaxe' entry in
> -	linkgit:gitdiffcore[7] for more details.
> +	Look for commits where the specified string was added or
> +	removed.  More precisely, find commits that change the number
> +	of occurrences of the specified string.

Any time you say "This means that", "More precisely", etc. please
check if you can rewrite it to lose everything before them (i.e. a
vague sentence that needs to be clarified may not have to be there
at all).

> ++
> +It is often useful when you're looking for an exact string (like a
> +function prototype), and want to know the history of that string since
> +it first came into being.

I think you should remind that the most useful case (and indeed the
intended one) is for "an exact string" to be a multi-line "block of
text".  People often get a (wrong) impression from the word "string"
that it is meant to be used with a single-liner.