Allow sending emails only for a subset of refs

Many projects use a pull-request model with a central repository, where
new changes are pushed to branches named e.g. feature/whizbang.  However,
users really don't view these branches as "part of the repository" until
they are merged into a 'real' branch, such as master.  And lots of users
are very annoyed at getting email notifications for pushes to these
branches; they only want to be notified when some subset of branches are
updated.

There's a slight complication, though: traditionally git-multimail has
only sent out commit emails for commits that are entirely new to the
repository, but this doesn't play well with this filtering feature.  So,
we need to instead have git-multimail only send out commit emails for
commits that are entirely new to the *relevant subset of the* repository.

Add multimailhook.refFilterInclusionRegex and
multimailhook.refFilterExclusionRegex configuration options, with related
--ref-filter-inclusion-regex and --ref-filter-exclusion-regex command
line options, which can be used to configure which refs are considered
relevant.  Mark ^refs/notes/ as irrelevant by default as git-multimail
emails make no sense for git notes.

Signed-off-by: Elijah Newren <newren@palantir.com>
testing: Pass additional arguments through test functions to multimail

Signed-off-by: Elijah Newren <newren@palantir.com>
Test restricting emails to a subset of refs defined by exclusion

Signed-off-by: Elijah Newren <newren@palantir.com>
Test restricting emails to a subset of refs defined by inclusion

Signed-off-by: Elijah Newren <newren@palantir.com>
StashEnvironment: New environment for being called from Atlassian Stash

Atlassian Stash can utilize a standard post-receive hook, and thus we
could use git_multimail as-is.  However, that is slightly suboptimal
because: (a) when pull requests are merged in stash, they are done on the
server and thus the normal post-receive hook is not triggered, (b)
everything runs as a single user similar to gitolite, but without a
GL_USER environment variable to rely on, and (c) although stash has
reasonable clone urls that having meaningful names for repositories, the
actual on-disk directories in which the repositories are stored are given
positive integers for names -- that results in a rather meaningless email
subject for the users ("[2093] branch master updated..." rather than
"[PROJ/REPO] branch master updated..."), since they will have no idea what
magic integer happened to be selected for their repository.

We can avoid these problems by making use of Stash's
AsyncPostReceiveRepositoryHook instead of a standard post-receive hook,
since it is triggered in all the right cases and has access to the
appropriate user and repo name.  Add a StashEnvironment for holding this
passed information, and add command line flags that can be passed with
the user and repo name.

Signed-off-by: Elijah Newren <newren@palantir.com>
GerritEnvironment: Make git_multimail callable as Gerrit ref-updated hook

git_multimail has the ability to be directly called as either a git update
or git post-receive hook.  Add the ability for git_multimail to be called
as a Gerrit ref-updated hook (Gerrit does not implement the standard git
hooks), and provide a GerritEnvironment (similar to GitoliteEnvironment
or GenericEnvironment) with relevant defaults.

Gerrit users are probably slightly less likely to use git_multimail since
gerrit already has a built-in email capability.  However:
  * Gerrit's emails appear to only trigger for references submitted as CRs
    (e.g. pushed to the magic refspec refs/for/), not for commits directly
    pushed to the relevant branch.
  * Some sites may have multiple git servers installed (e.g. Gitolite,
    Gerrit, Atlassian Stash) and want similar email styles used regardless
    of which system the repository is hosted under.

Signed-off-by: Elijah Newren <newren@palantir.com>
GerritEnvironment: Skip merge commits created internally by Gerrit

Gerrit often creates a merge behind the scenes for an approved code
review.  Since it's a behind the scenes implementational detail, users
aren't necessarily interested in getting an individual email for each of
these.  Filter them out.

Signed-off-by: Elijah Newren <newren@palantir.com>
GerritEnvironment: Commits can enter repositories multiple ways

Since commits can both be directly 'pushed' to the repository, or first
be created as a patchset and then 'submitted' from the web UI (with the
latter far more common), claiming that all gerrit commits were 'pushed'
will confuse users.  Make an "update_method" value available for
templates so that emails can use the correct verb.

This would also apply to Stash, if it provided a way to differentiate
in its (Async)?PostReceiveRepositoryHook classes between being
triggered by a direct push and by the merge of a pull request.

Signed-off-by: Elijah Newren <newren@palantir.com>
GerritEnvironment: Work around rude discarding of submitter identity

We want to know who pushes/submits code to the repository, because that
information is included in the emails.  However, Gerrit often rudely
discards this information upon calling its ref-updated hook.  When Gerrit
doesn't provide this information directly, try to grab it indirectly.

Signed-off-by: Elijah Newren <newren@palantir.com>