Re: [PATCHv2 6/6] rev-list/log: document logic with several limiting options

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 13, 2012, 22:29 UTC
Message-ID: <7v7grx5zfq.fsf@alter.siamese.dyndns.org>
In-Reply-To: <49f89f65cd39306655a9b382a1244e34fb90fff1.1347544259.git.git@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

Show 30 quoted lines

> The current behavior is probably as useful as it is confusing. In any
> case it is going to stay. So, document it.
>
> This does not take into account the issue of 'log --all-match
> --author=me --grep=foo --grep=bar' not honoring '--all-match' because it
> is hopefully a corner case (and, even more hopefully, fixed some time
> soon).
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
>  Documentation/rev-list-options.txt | 15 ++++++++++++++-
>  1 file changed, 14 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 5436eba..b2dbfb5 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -6,6 +6,19 @@ special notations explained in the description, additional commit
>  limiting may be applied. Note that they are applied before commit
>  ordering and formatting options, such as '--reverse'.
>  
> +Different options are ANDed: '--author=bar --grep=foo'
> +limits to commits which match both conditions.
> +
> +Several occurences of the '--grep' option are ORed: '--grep=foo --grep=bar'
> +limits to commits matching any of these conditions.
> +(If '--all-match' is given, the conditions are ANDed.)
> +
> +Several occurences of the '--author' and '--committer' options are ORed
> +(because there can be only one each per commit).

As I would really want to eventually see the revision command option parser understand the full power of grep expressions in the future, I would really want to avoid a misleading explanation that calls what "--all-match" does as "ANDed".

With such a change, we could say something like

	git log --grep=commit --and --grep=count

to require the log message to have both "commit" and "count" on the same line (in any order). This obviously is different from

	git log --grep="commit.*count"

but more importantly, it is vastly different from

	git log --all-match --grep=commit --grep=count

that requires some line that has "commit", and some line (which may not be the same line) that has "count", in the log message.