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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 12, 2012, 17:25 UTC
Message-ID: <7vbohbdufz.fsf@alter.siamese.dyndns.org>
In-Reply-To: <50509171.9060604@drmicha.warpmail.net>

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

Show 15 quoted lines

> It was introduced in 0ab7befa with a clear meaning (AND everything),
> then the general logic (without --all-match) was modified in 80235ba7
> (to take headermatch AND (all greps ORed)), and 5aaeb733 finally made
> multiple authors resp. committers get ORed among each other. All of this
> in an attempt to make the standard usage most useful, of course. As a
> consequence, --all-match does not influence multiple --author options at
> all (contrary to the doc), e.g.
>
> I don't see any of this reflected in the doc, though. I noticed only by
> reading t/t7810-grep.sh. Before that, I had only gone by my own testing
> which didn't reveal the multiple author multiple special casing effect.
>
> I guess I'll have to wrap my head around the current implementation a
> few more times before trying to describe the status quo in the
> documentation...

This is what I used to use when adding these generalized grep boolean expressions.

With this applied, you can try things like these:

    $ git log --grep=regexp --grep=nosuch --all-match >/dev/null
    $ git log --grep=regexp --grep=nosuch --author=Michael >/dev/null

For example, "--all-match --grep=regexp --author=Michael --author=Linus" turns into

    [all-match]
    (or
     pattern_body<body>regexp
     (or
      (or
       pattern_head<head 0>Linus
       pattern_head<head 0>Michael
      )
      true
     )
    )

that says "body must have 'regexp' in it, and authored by either Linus or Michael".

The semantics of "--all-match" is different from "--and" (which, together with "--or", ")", and "(", is not availble to rev-list command line parser primarily because "--not" is not available). After applying all the "or"-ed terms, it checks the top-level nodes that are "or"-ed and makes sure all of them fired (possibly and usually on different lines).