contrib / hooks / multimail / git_multimail.pyon commit Merge branch 'jk/index-pack-reduce-recheck' (712b351)
   1#! /usr/bin/env python2
   2
   3# Copyright (c) 2015 Matthieu Moy and others
   4# Copyright (c) 2012-2014 Michael Haggerty and others
   5# Derived from contrib/hooks/post-receive-email, which is
   6# Copyright (c) 2007 Andy Parkins
   7# and also includes contributions by other authors.
   8#
   9# This file is part of git-multimail.
  10#
  11# git-multimail is free software: you can redistribute it and/or
  12# modify it under the terms of the GNU General Public License version
  13# 2 as published by the Free Software Foundation.
  14#
  15# This program is distributed in the hope that it will be useful, but
  16# WITHOUT ANY WARRANTY; without even the implied warranty of
  17# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18# General Public License for more details.
  19#
  20# You should have received a copy of the GNU General Public License
  21# along with this program.  If not, see
  22# <http://www.gnu.org/licenses/>.
  23
  24"""Generate notification emails for pushes to a git repository.
  25
  26This hook sends emails describing changes introduced by pushes to a
  27git repository.  For each reference that was changed, it emits one
  28ReferenceChange email summarizing how the reference was changed,
  29followed by one Revision email for each new commit that was introduced
  30by the reference change.
  31
  32Each commit is announced in exactly one Revision email.  If the same
  33commit is merged into another branch in the same or a later push, then
  34the ReferenceChange email will list the commit's SHA1 and its one-line
  35summary, but no new Revision email will be generated.
  36
  37This script is designed to be used as a "post-receive" hook in a git
  38repository (see githooks(5)).  It can also be used as an "update"
  39script, but this usage is not completely reliable and is deprecated.
  40
  41To help with debugging, this script accepts a --stdout option, which
  42causes the emails to be written to standard output rather than sent
  43using sendmail.
  44
  45See the accompanying README file for the complete documentation.
  46
  47"""
  48
  49import sys
  50import os
  51import re
  52import bisect
  53import socket
  54import subprocess
  55import shlex
  56import optparse
  57import smtplib
  58import time
  59
  60try:
  61    from email.utils import make_msgid
  62    from email.utils import getaddresses
  63    from email.utils import formataddr
  64    from email.utils import formatdate
  65    from email.header import Header
  66except ImportError:
  67    # Prior to Python 2.5, the email module used different names:
  68    from email.Utils import make_msgid
  69    from email.Utils import getaddresses
  70    from email.Utils import formataddr
  71    from email.Utils import formatdate
  72    from email.Header import Header
  73
  74
  75DEBUG = False
  76
  77ZEROS = '0' * 40
  78LOGBEGIN = '- Log -----------------------------------------------------------------\n'
  79LOGEND = '-----------------------------------------------------------------------\n'
  80
  81ADDR_HEADERS = set(['from', 'to', 'cc', 'bcc', 'reply-to', 'sender'])
  82
  83# It is assumed in many places that the encoding is uniformly UTF-8,
  84# so changing these constants is unsupported.  But define them here
  85# anyway, to make it easier to find (at least most of) the places
  86# where the encoding is important.
  87(ENCODING, CHARSET) = ('UTF-8', 'utf-8')
  88
  89
  90REF_CREATED_SUBJECT_TEMPLATE = (
  91    '%(emailprefix)s%(refname_type)s %(short_refname)s created'
  92    ' (now %(newrev_short)s)'
  93    )
  94REF_UPDATED_SUBJECT_TEMPLATE = (
  95    '%(emailprefix)s%(refname_type)s %(short_refname)s updated'
  96    ' (%(oldrev_short)s -> %(newrev_short)s)'
  97    )
  98REF_DELETED_SUBJECT_TEMPLATE = (
  99    '%(emailprefix)s%(refname_type)s %(short_refname)s deleted'
 100    ' (was %(oldrev_short)s)'
 101    )
 102
 103COMBINED_REFCHANGE_REVISION_SUBJECT_TEMPLATE = (
 104    '%(emailprefix)s%(refname_type)s %(short_refname)s updated: %(oneline)s'
 105    )
 106
 107REFCHANGE_HEADER_TEMPLATE = """\
 108Date: %(send_date)s
 109To: %(recipients)s
 110Subject: %(subject)s
 111MIME-Version: 1.0
 112Content-Type: text/plain; charset=%(charset)s
 113Content-Transfer-Encoding: 8bit
 114Message-ID: %(msgid)s
 115From: %(fromaddr)s
 116Reply-To: %(reply_to)s
 117X-Git-Host: %(fqdn)s
 118X-Git-Repo: %(repo_shortname)s
 119X-Git-Refname: %(refname)s
 120X-Git-Reftype: %(refname_type)s
 121X-Git-Oldrev: %(oldrev)s
 122X-Git-Newrev: %(newrev)s
 123Auto-Submitted: auto-generated
 124"""
 125
 126REFCHANGE_INTRO_TEMPLATE = """\
 127This is an automated email from the git hooks/post-receive script.
 128
 129%(pusher)s pushed a change to %(refname_type)s %(short_refname)s
 130in repository %(repo_shortname)s.
 131
 132"""
 133
 134
 135FOOTER_TEMPLATE = """\
 136
 137-- \n\
 138To stop receiving notification emails like this one, please contact
 139%(administrator)s.
 140"""
 141
 142
 143REWIND_ONLY_TEMPLATE = """\
 144This update removed existing revisions from the reference, leaving the
 145reference pointing at a previous point in the repository history.
 146
 147 * -- * -- N   %(refname)s (%(newrev_short)s)
 148            \\
 149             O -- O -- O   (%(oldrev_short)s)
 150
 151Any revisions marked "omits" are not gone; other references still
 152refer to them.  Any revisions marked "discards" are gone forever.
 153"""
 154
 155
 156NON_FF_TEMPLATE = """\
 157This update added new revisions after undoing existing revisions.
 158That is to say, some revisions that were in the old version of the
 159%(refname_type)s are not in the new version.  This situation occurs
 160when a user --force pushes a change and generates a repository
 161containing something like this:
 162
 163 * -- * -- B -- O -- O -- O   (%(oldrev_short)s)
 164            \\
 165             N -- N -- N   %(refname)s (%(newrev_short)s)
 166
 167You should already have received notification emails for all of the O
 168revisions, and so the following emails describe only the N revisions
 169from the common base, B.
 170
 171Any revisions marked "omits" are not gone; other references still
 172refer to them.  Any revisions marked "discards" are gone forever.
 173"""
 174
 175
 176NO_NEW_REVISIONS_TEMPLATE = """\
 177No new revisions were added by this update.
 178"""
 179
 180
 181DISCARDED_REVISIONS_TEMPLATE = """\
 182This change permanently discards the following revisions:
 183"""
 184
 185
 186NO_DISCARDED_REVISIONS_TEMPLATE = """\
 187The revisions that were on this %(refname_type)s are still contained in
 188other references; therefore, this change does not discard any commits
 189from the repository.
 190"""
 191
 192
 193NEW_REVISIONS_TEMPLATE = """\
 194The %(tot)s revisions listed above as "new" are entirely new to this
 195repository and will be described in separate emails.  The revisions
 196listed as "adds" were already present in the repository and have only
 197been added to this reference.
 198
 199"""
 200
 201
 202TAG_CREATED_TEMPLATE = """\
 203        at  %(newrev_short)-9s (%(newrev_type)s)
 204"""
 205
 206
 207TAG_UPDATED_TEMPLATE = """\
 208*** WARNING: tag %(short_refname)s was modified! ***
 209
 210      from  %(oldrev_short)-9s (%(oldrev_type)s)
 211        to  %(newrev_short)-9s (%(newrev_type)s)
 212"""
 213
 214
 215TAG_DELETED_TEMPLATE = """\
 216*** WARNING: tag %(short_refname)s was deleted! ***
 217
 218"""
 219
 220
 221# The template used in summary tables.  It looks best if this uses the
 222# same alignment as TAG_CREATED_TEMPLATE and TAG_UPDATED_TEMPLATE.
 223BRIEF_SUMMARY_TEMPLATE = """\
 224%(action)10s  %(rev_short)-9s %(text)s
 225"""
 226
 227
 228NON_COMMIT_UPDATE_TEMPLATE = """\
 229This is an unusual reference change because the reference did not
 230refer to a commit either before or after the change.  We do not know
 231how to provide full information about this reference change.
 232"""
 233
 234
 235REVISION_HEADER_TEMPLATE = """\
 236Date: %(send_date)s
 237To: %(recipients)s
 238Cc: %(cc_recipients)s
 239Subject: %(emailprefix)s%(num)02d/%(tot)02d: %(oneline)s
 240MIME-Version: 1.0
 241Content-Type: text/plain; charset=%(charset)s
 242Content-Transfer-Encoding: 8bit
 243From: %(fromaddr)s
 244Reply-To: %(reply_to)s
 245In-Reply-To: %(reply_to_msgid)s
 246References: %(reply_to_msgid)s
 247X-Git-Host: %(fqdn)s
 248X-Git-Repo: %(repo_shortname)s
 249X-Git-Refname: %(refname)s
 250X-Git-Reftype: %(refname_type)s
 251X-Git-Rev: %(rev)s
 252Auto-Submitted: auto-generated
 253"""
 254
 255REVISION_INTRO_TEMPLATE = """\
 256This is an automated email from the git hooks/post-receive script.
 257
 258%(pusher)s pushed a commit to %(refname_type)s %(short_refname)s
 259in repository %(repo_shortname)s.
 260
 261"""
 262
 263
 264REVISION_FOOTER_TEMPLATE = FOOTER_TEMPLATE
 265
 266
 267# Combined, meaning refchange+revision email (for single-commit additions)
 268COMBINED_HEADER_TEMPLATE = """\
 269Date: %(send_date)s
 270To: %(recipients)s
 271Subject: %(subject)s
 272MIME-Version: 1.0
 273Content-Type: text/plain; charset=%(charset)s
 274Content-Transfer-Encoding: 8bit
 275Message-ID: %(msgid)s
 276From: %(fromaddr)s
 277Reply-To: %(reply_to)s
 278X-Git-Host: %(fqdn)s
 279X-Git-Repo: %(repo_shortname)s
 280X-Git-Refname: %(refname)s
 281X-Git-Reftype: %(refname_type)s
 282X-Git-Oldrev: %(oldrev)s
 283X-Git-Newrev: %(newrev)s
 284X-Git-Rev: %(rev)s
 285Auto-Submitted: auto-generated
 286"""
 287
 288COMBINED_INTRO_TEMPLATE = """\
 289This is an automated email from the git hooks/post-receive script.
 290
 291%(pusher)s pushed a commit to %(refname_type)s %(short_refname)s
 292in repository %(repo_shortname)s.
 293
 294"""
 295
 296COMBINED_FOOTER_TEMPLATE = FOOTER_TEMPLATE
 297
 298
 299class CommandError(Exception):
 300    def __init__(self, cmd, retcode):
 301        self.cmd = cmd
 302        self.retcode = retcode
 303        Exception.__init__(
 304            self,
 305            'Command "%s" failed with retcode %s' % (' '.join(cmd), retcode,)
 306            )
 307
 308
 309class ConfigurationException(Exception):
 310    pass
 311
 312
 313# The "git" program (this could be changed to include a full path):
 314GIT_EXECUTABLE = 'git'
 315
 316
 317# How "git" should be invoked (including global arguments), as a list
 318# of words.  This variable is usually initialized automatically by
 319# read_git_output() via choose_git_command(), but if a value is set
 320# here then it will be used unconditionally.
 321GIT_CMD = None
 322
 323
 324def choose_git_command():
 325    """Decide how to invoke git, and record the choice in GIT_CMD."""
 326
 327    global GIT_CMD
 328
 329    if GIT_CMD is None:
 330        try:
 331            # Check to see whether the "-c" option is accepted (it was
 332            # only added in Git 1.7.2).  We don't actually use the
 333            # output of "git --version", though if we needed more
 334            # specific version information this would be the place to
 335            # do it.
 336            cmd = [GIT_EXECUTABLE, '-c', 'foo.bar=baz', '--version']
 337            read_output(cmd)
 338            GIT_CMD = [GIT_EXECUTABLE, '-c', 'i18n.logoutputencoding=%s' % (ENCODING,)]
 339        except CommandError:
 340            GIT_CMD = [GIT_EXECUTABLE]
 341
 342
 343def read_git_output(args, input=None, keepends=False, **kw):
 344    """Read the output of a Git command."""
 345
 346    if GIT_CMD is None:
 347        choose_git_command()
 348
 349    return read_output(GIT_CMD + args, input=input, keepends=keepends, **kw)
 350
 351
 352def read_output(cmd, input=None, keepends=False, **kw):
 353    if input:
 354        stdin = subprocess.PIPE
 355    else:
 356        stdin = None
 357    p = subprocess.Popen(
 358        cmd, stdin=stdin, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kw
 359        )
 360    (out, err) = p.communicate(input)
 361    retcode = p.wait()
 362    if retcode:
 363        raise CommandError(cmd, retcode)
 364    if not keepends:
 365        out = out.rstrip('\n\r')
 366    return out
 367
 368
 369def read_git_lines(args, keepends=False, **kw):
 370    """Return the lines output by Git command.
 371
 372    Return as single lines, with newlines stripped off."""
 373
 374    return read_git_output(args, keepends=True, **kw).splitlines(keepends)
 375
 376
 377def git_rev_list_ish(cmd, spec, args=None, **kw):
 378    """Common functionality for invoking a 'git rev-list'-like command.
 379
 380    Parameters:
 381      * cmd is the Git command to run, e.g., 'rev-list' or 'log'.
 382      * spec is a list of revision arguments to pass to the named
 383        command.  If None, this function returns an empty list.
 384      * args is a list of extra arguments passed to the named command.
 385      * All other keyword arguments (if any) are passed to the
 386        underlying read_git_lines() function.
 387
 388    Return the output of the Git command in the form of a list, one
 389    entry per output line.
 390    """
 391    if spec is None:
 392        return []
 393    if args is None:
 394        args = []
 395    args = [cmd, '--stdin'] + args
 396    spec_stdin = ''.join(s + '\n' for s in spec)
 397    return read_git_lines(args, input=spec_stdin, **kw)
 398
 399
 400def git_rev_list(spec, **kw):
 401    """Run 'git rev-list' with the given list of revision arguments.
 402
 403    See git_rev_list_ish() for parameter and return value
 404    documentation.
 405    """
 406    return git_rev_list_ish('rev-list', spec, **kw)
 407
 408
 409def git_log(spec, **kw):
 410    """Run 'git log' with the given list of revision arguments.
 411
 412    See git_rev_list_ish() for parameter and return value
 413    documentation.
 414    """
 415    return git_rev_list_ish('log', spec, **kw)
 416
 417
 418def header_encode(text, header_name=None):
 419    """Encode and line-wrap the value of an email header field."""
 420
 421    try:
 422        if isinstance(text, str):
 423            text = text.decode(ENCODING, 'replace')
 424        return Header(text, header_name=header_name).encode()
 425    except UnicodeEncodeError:
 426        return Header(text, header_name=header_name, charset=CHARSET,
 427                      errors='replace').encode()
 428
 429
 430def addr_header_encode(text, header_name=None):
 431    """Encode and line-wrap the value of an email header field containing
 432    email addresses."""
 433
 434    return Header(
 435        ', '.join(
 436            formataddr((header_encode(name), emailaddr))
 437            for name, emailaddr in getaddresses([text])
 438            ),
 439        header_name=header_name
 440        ).encode()
 441
 442
 443class Config(object):
 444    def __init__(self, section, git_config=None):
 445        """Represent a section of the git configuration.
 446
 447        If git_config is specified, it is passed to "git config" in
 448        the GIT_CONFIG environment variable, meaning that "git config"
 449        will read the specified path rather than the Git default
 450        config paths."""
 451
 452        self.section = section
 453        if git_config:
 454            self.env = os.environ.copy()
 455            self.env['GIT_CONFIG'] = git_config
 456        else:
 457            self.env = None
 458
 459    @staticmethod
 460    def _split(s):
 461        """Split NUL-terminated values."""
 462
 463        words = s.split('\0')
 464        assert words[-1] == ''
 465        return words[:-1]
 466
 467    def get(self, name, default=None):
 468        try:
 469            values = self._split(read_git_output(
 470                ['config', '--get', '--null', '%s.%s' % (self.section, name)],
 471                env=self.env, keepends=True,
 472                ))
 473            assert len(values) == 1
 474            return values[0]
 475        except CommandError:
 476            return default
 477
 478    def get_bool(self, name, default=None):
 479        try:
 480            value = read_git_output(
 481                ['config', '--get', '--bool', '%s.%s' % (self.section, name)],
 482                env=self.env,
 483                )
 484        except CommandError:
 485            return default
 486        return value == 'true'
 487
 488    def get_all(self, name, default=None):
 489        """Read a (possibly multivalued) setting from the configuration.
 490
 491        Return the result as a list of values, or default if the name
 492        is unset."""
 493
 494        try:
 495            return self._split(read_git_output(
 496                ['config', '--get-all', '--null', '%s.%s' % (self.section, name)],
 497                env=self.env, keepends=True,
 498                ))
 499        except CommandError, e:
 500            if e.retcode == 1:
 501                # "the section or key is invalid"; i.e., there is no
 502                # value for the specified key.
 503                return default
 504            else:
 505                raise
 506
 507    def get_recipients(self, name, default=None):
 508        """Read a recipients list from the configuration.
 509
 510        Return the result as a comma-separated list of email
 511        addresses, or default if the option is unset.  If the setting
 512        has multiple values, concatenate them with comma separators."""
 513
 514        lines = self.get_all(name, default=None)
 515        if lines is None:
 516            return default
 517        return ', '.join(line.strip() for line in lines)
 518
 519    def set(self, name, value):
 520        read_git_output(
 521            ['config', '%s.%s' % (self.section, name), value],
 522            env=self.env,
 523            )
 524
 525    def add(self, name, value):
 526        read_git_output(
 527            ['config', '--add', '%s.%s' % (self.section, name), value],
 528            env=self.env,
 529            )
 530
 531    def __contains__(self, name):
 532        return self.get_all(name, default=None) is not None
 533
 534    # We don't use this method anymore internally, but keep it here in
 535    # case somebody is calling it from their own code:
 536    def has_key(self, name):
 537        return name in self
 538
 539    def unset_all(self, name):
 540        try:
 541            read_git_output(
 542                ['config', '--unset-all', '%s.%s' % (self.section, name)],
 543                env=self.env,
 544                )
 545        except CommandError, e:
 546            if e.retcode == 5:
 547                # The name doesn't exist, which is what we wanted anyway...
 548                pass
 549            else:
 550                raise
 551
 552    def set_recipients(self, name, value):
 553        self.unset_all(name)
 554        for pair in getaddresses([value]):
 555            self.add(name, formataddr(pair))
 556
 557
 558def generate_summaries(*log_args):
 559    """Generate a brief summary for each revision requested.
 560
 561    log_args are strings that will be passed directly to "git log" as
 562    revision selectors.  Iterate over (sha1_short, subject) for each
 563    commit specified by log_args (subject is the first line of the
 564    commit message as a string without EOLs)."""
 565
 566    cmd = [
 567        'log', '--abbrev', '--format=%h %s',
 568        ] + list(log_args) + ['--']
 569    for line in read_git_lines(cmd):
 570        yield tuple(line.split(' ', 1))
 571
 572
 573def limit_lines(lines, max_lines):
 574    for (index, line) in enumerate(lines):
 575        if index < max_lines:
 576            yield line
 577
 578    if index >= max_lines:
 579        yield '... %d lines suppressed ...\n' % (index + 1 - max_lines,)
 580
 581
 582def limit_linelength(lines, max_linelength):
 583    for line in lines:
 584        # Don't forget that lines always include a trailing newline.
 585        if len(line) > max_linelength + 1:
 586            line = line[:max_linelength - 7] + ' [...]\n'
 587        yield line
 588
 589
 590class CommitSet(object):
 591    """A (constant) set of object names.
 592
 593    The set should be initialized with full SHA1 object names.  The
 594    __contains__() method returns True iff its argument is an
 595    abbreviation of any the names in the set."""
 596
 597    def __init__(self, names):
 598        self._names = sorted(names)
 599
 600    def __len__(self):
 601        return len(self._names)
 602
 603    def __contains__(self, sha1_abbrev):
 604        """Return True iff this set contains sha1_abbrev (which might be abbreviated)."""
 605
 606        i = bisect.bisect_left(self._names, sha1_abbrev)
 607        return i < len(self) and self._names[i].startswith(sha1_abbrev)
 608
 609
 610class GitObject(object):
 611    def __init__(self, sha1, type=None):
 612        if sha1 == ZEROS:
 613            self.sha1 = self.type = self.commit_sha1 = None
 614        else:
 615            self.sha1 = sha1
 616            self.type = type or read_git_output(['cat-file', '-t', self.sha1])
 617
 618            if self.type == 'commit':
 619                self.commit_sha1 = self.sha1
 620            elif self.type == 'tag':
 621                try:
 622                    self.commit_sha1 = read_git_output(
 623                        ['rev-parse', '--verify', '%s^0' % (self.sha1,)]
 624                        )
 625                except CommandError:
 626                    # Cannot deref tag to determine commit_sha1
 627                    self.commit_sha1 = None
 628            else:
 629                self.commit_sha1 = None
 630
 631        self.short = read_git_output(['rev-parse', '--short', sha1])
 632
 633    def get_summary(self):
 634        """Return (sha1_short, subject) for this commit."""
 635
 636        if not self.sha1:
 637            raise ValueError('Empty commit has no summary')
 638
 639        return iter(generate_summaries('--no-walk', self.sha1)).next()
 640
 641    def __eq__(self, other):
 642        return isinstance(other, GitObject) and self.sha1 == other.sha1
 643
 644    def __hash__(self):
 645        return hash(self.sha1)
 646
 647    def __nonzero__(self):
 648        return bool(self.sha1)
 649
 650    def __str__(self):
 651        return self.sha1 or ZEROS
 652
 653
 654class Change(object):
 655    """A Change that has been made to the Git repository.
 656
 657    Abstract class from which both Revisions and ReferenceChanges are
 658    derived.  A Change knows how to generate a notification email
 659    describing itself."""
 660
 661    def __init__(self, environment):
 662        self.environment = environment
 663        self._values = None
 664
 665    def _compute_values(self):
 666        """Return a dictionary {keyword: expansion} for this Change.
 667
 668        Derived classes overload this method to add more entries to
 669        the return value.  This method is used internally by
 670        get_values().  The return value should always be a new
 671        dictionary."""
 672
 673        return self.environment.get_values()
 674
 675    def get_values(self, **extra_values):
 676        """Return a dictionary {keyword: expansion} for this Change.
 677
 678        Return a dictionary mapping keywords to the values that they
 679        should be expanded to for this Change (used when interpolating
 680        template strings).  If any keyword arguments are supplied, add
 681        those to the return value as well.  The return value is always
 682        a new dictionary."""
 683
 684        if self._values is None:
 685            self._values = self._compute_values()
 686
 687        values = self._values.copy()
 688        if extra_values:
 689            values.update(extra_values)
 690        return values
 691
 692    def expand(self, template, **extra_values):
 693        """Expand template.
 694
 695        Expand the template (which should be a string) using string
 696        interpolation of the values for this Change.  If any keyword
 697        arguments are provided, also include those in the keywords
 698        available for interpolation."""
 699
 700        return template % self.get_values(**extra_values)
 701
 702    def expand_lines(self, template, **extra_values):
 703        """Break template into lines and expand each line."""
 704
 705        values = self.get_values(**extra_values)
 706        for line in template.splitlines(True):
 707            yield line % values
 708
 709    def expand_header_lines(self, template, **extra_values):
 710        """Break template into lines and expand each line as an RFC 2822 header.
 711
 712        Encode values and split up lines that are too long.  Silently
 713        skip lines that contain references to unknown variables."""
 714
 715        values = self.get_values(**extra_values)
 716        for line in template.splitlines():
 717            (name, value) = line.split(':', 1)
 718
 719            try:
 720                value = value % values
 721            except KeyError, e:
 722                if DEBUG:
 723                    self.environment.log_warning(
 724                        'Warning: unknown variable %r in the following line; line skipped:\n'
 725                        '    %s\n'
 726                        % (e.args[0], line,)
 727                        )
 728            else:
 729                if name.lower() in ADDR_HEADERS:
 730                    value = addr_header_encode(value, name)
 731                else:
 732                    value = header_encode(value, name)
 733                for splitline in ('%s: %s\n' % (name, value)).splitlines(True):
 734                    yield splitline
 735
 736    def generate_email_header(self):
 737        """Generate the RFC 2822 email headers for this Change, a line at a time.
 738
 739        The output should not include the trailing blank line."""
 740
 741        raise NotImplementedError()
 742
 743    def generate_email_intro(self):
 744        """Generate the email intro for this Change, a line at a time.
 745
 746        The output will be used as the standard boilerplate at the top
 747        of the email body."""
 748
 749        raise NotImplementedError()
 750
 751    def generate_email_body(self):
 752        """Generate the main part of the email body, a line at a time.
 753
 754        The text in the body might be truncated after a specified
 755        number of lines (see multimailhook.emailmaxlines)."""
 756
 757        raise NotImplementedError()
 758
 759    def generate_email_footer(self):
 760        """Generate the footer of the email, a line at a time.
 761
 762        The footer is always included, irrespective of
 763        multimailhook.emailmaxlines."""
 764
 765        raise NotImplementedError()
 766
 767    def generate_email(self, push, body_filter=None, extra_header_values={}):
 768        """Generate an email describing this change.
 769
 770        Iterate over the lines (including the header lines) of an
 771        email describing this change.  If body_filter is not None,
 772        then use it to filter the lines that are intended for the
 773        email body.
 774
 775        The extra_header_values field is received as a dict and not as
 776        **kwargs, to allow passing other keyword arguments in the
 777        future (e.g. passing extra values to generate_email_intro()"""
 778
 779        for line in self.generate_email_header(**extra_header_values):
 780            yield line
 781        yield '\n'
 782        for line in self.generate_email_intro():
 783            yield line
 784
 785        body = self.generate_email_body(push)
 786        if body_filter is not None:
 787            body = body_filter(body)
 788        for line in body:
 789            yield line
 790
 791        for line in self.generate_email_footer():
 792            yield line
 793
 794
 795class Revision(Change):
 796    """A Change consisting of a single git commit."""
 797
 798    CC_RE = re.compile(r'^\s*C[Cc]:\s*(?P<to>[^#]+@[^\s#]*)\s*(#.*)?$')
 799
 800    def __init__(self, reference_change, rev, num, tot):
 801        Change.__init__(self, reference_change.environment)
 802        self.reference_change = reference_change
 803        self.rev = rev
 804        self.change_type = self.reference_change.change_type
 805        self.refname = self.reference_change.refname
 806        self.num = num
 807        self.tot = tot
 808        self.author = read_git_output(['log', '--no-walk', '--format=%aN <%aE>', self.rev.sha1])
 809        self.recipients = self.environment.get_revision_recipients(self)
 810
 811        self.cc_recipients = ''
 812        if self.environment.get_scancommitforcc():
 813            self.cc_recipients = ', '.join(to.strip() for to in self._cc_recipients())
 814            if self.cc_recipients:
 815                self.environment.log_msg(
 816                    'Add %s to CC for %s\n' % (self.cc_recipients, self.rev.sha1))
 817
 818    def _cc_recipients(self):
 819        cc_recipients = []
 820        message = read_git_output(['log', '--no-walk', '--format=%b', self.rev.sha1])
 821        lines = message.strip().split('\n')
 822        for line in lines:
 823            m = re.match(self.CC_RE, line)
 824            if m:
 825                cc_recipients.append(m.group('to'))
 826
 827        return cc_recipients
 828
 829    def _compute_values(self):
 830        values = Change._compute_values(self)
 831
 832        oneline = read_git_output(
 833            ['log', '--format=%s', '--no-walk', self.rev.sha1]
 834            )
 835
 836        values['rev'] = self.rev.sha1
 837        values['rev_short'] = self.rev.short
 838        values['change_type'] = self.change_type
 839        values['refname'] = self.refname
 840        values['short_refname'] = self.reference_change.short_refname
 841        values['refname_type'] = self.reference_change.refname_type
 842        values['reply_to_msgid'] = self.reference_change.msgid
 843        values['num'] = self.num
 844        values['tot'] = self.tot
 845        values['recipients'] = self.recipients
 846        if self.cc_recipients:
 847            values['cc_recipients'] = self.cc_recipients
 848        values['oneline'] = oneline
 849        values['author'] = self.author
 850
 851        reply_to = self.environment.get_reply_to_commit(self)
 852        if reply_to:
 853            values['reply_to'] = reply_to
 854
 855        return values
 856
 857    def generate_email_header(self, **extra_values):
 858        for line in self.expand_header_lines(
 859                REVISION_HEADER_TEMPLATE, **extra_values
 860                ):
 861            yield line
 862
 863    def generate_email_intro(self):
 864        for line in self.expand_lines(REVISION_INTRO_TEMPLATE):
 865            yield line
 866
 867    def generate_email_body(self, push):
 868        """Show this revision."""
 869
 870        return read_git_lines(
 871            ['log'] + self.environment.commitlogopts + ['-1', self.rev.sha1],
 872            keepends=True,
 873            )
 874
 875    def generate_email_footer(self):
 876        return self.expand_lines(REVISION_FOOTER_TEMPLATE)
 877
 878
 879class ReferenceChange(Change):
 880    """A Change to a Git reference.
 881
 882    An abstract class representing a create, update, or delete of a
 883    Git reference.  Derived classes handle specific types of reference
 884    (e.g., tags vs. branches).  These classes generate the main
 885    reference change email summarizing the reference change and
 886    whether it caused any any commits to be added or removed.
 887
 888    ReferenceChange objects are usually created using the static
 889    create() method, which has the logic to decide which derived class
 890    to instantiate."""
 891
 892    REF_RE = re.compile(r'^refs\/(?P<area>[^\/]+)\/(?P<shortname>.*)$')
 893
 894    @staticmethod
 895    def create(environment, oldrev, newrev, refname):
 896        """Return a ReferenceChange object representing the change.
 897
 898        Return an object that represents the type of change that is being
 899        made. oldrev and newrev should be SHA1s or ZEROS."""
 900
 901        old = GitObject(oldrev)
 902        new = GitObject(newrev)
 903        rev = new or old
 904
 905        # The revision type tells us what type the commit is, combined with
 906        # the location of the ref we can decide between
 907        #  - working branch
 908        #  - tracking branch
 909        #  - unannotated tag
 910        #  - annotated tag
 911        m = ReferenceChange.REF_RE.match(refname)
 912        if m:
 913            area = m.group('area')
 914            short_refname = m.group('shortname')
 915        else:
 916            area = ''
 917            short_refname = refname
 918
 919        if rev.type == 'tag':
 920            # Annotated tag:
 921            klass = AnnotatedTagChange
 922        elif rev.type == 'commit':
 923            if area == 'tags':
 924                # Non-annotated tag:
 925                klass = NonAnnotatedTagChange
 926            elif area == 'heads':
 927                # Branch:
 928                klass = BranchChange
 929            elif area == 'remotes':
 930                # Tracking branch:
 931                environment.log_warning(
 932                    '*** Push-update of tracking branch %r\n'
 933                    '***  - incomplete email generated.\n'
 934                    % (refname,)
 935                    )
 936                klass = OtherReferenceChange
 937            else:
 938                # Some other reference namespace:
 939                environment.log_warning(
 940                    '*** Push-update of strange reference %r\n'
 941                    '***  - incomplete email generated.\n'
 942                    % (refname,)
 943                    )
 944                klass = OtherReferenceChange
 945        else:
 946            # Anything else (is there anything else?)
 947            environment.log_warning(
 948                '*** Unknown type of update to %r (%s)\n'
 949                '***  - incomplete email generated.\n'
 950                % (refname, rev.type,)
 951                )
 952            klass = OtherReferenceChange
 953
 954        return klass(
 955            environment,
 956            refname=refname, short_refname=short_refname,
 957            old=old, new=new, rev=rev,
 958            )
 959
 960    def __init__(self, environment, refname, short_refname, old, new, rev):
 961        Change.__init__(self, environment)
 962        self.change_type = {
 963            (False, True): 'create',
 964            (True, True): 'update',
 965            (True, False): 'delete',
 966            }[bool(old), bool(new)]
 967        self.refname = refname
 968        self.short_refname = short_refname
 969        self.old = old
 970        self.new = new
 971        self.rev = rev
 972        self.msgid = make_msgid()
 973        self.diffopts = environment.diffopts
 974        self.graphopts = environment.graphopts
 975        self.logopts = environment.logopts
 976        self.commitlogopts = environment.commitlogopts
 977        self.showgraph = environment.refchange_showgraph
 978        self.showlog = environment.refchange_showlog
 979
 980        self.header_template = REFCHANGE_HEADER_TEMPLATE
 981        self.intro_template = REFCHANGE_INTRO_TEMPLATE
 982        self.footer_template = FOOTER_TEMPLATE
 983
 984    def _compute_values(self):
 985        values = Change._compute_values(self)
 986
 987        values['change_type'] = self.change_type
 988        values['refname_type'] = self.refname_type
 989        values['refname'] = self.refname
 990        values['short_refname'] = self.short_refname
 991        values['msgid'] = self.msgid
 992        values['recipients'] = self.recipients
 993        values['oldrev'] = str(self.old)
 994        values['oldrev_short'] = self.old.short
 995        values['newrev'] = str(self.new)
 996        values['newrev_short'] = self.new.short
 997
 998        if self.old:
 999            values['oldrev_type'] = self.old.type
1000        if self.new:
1001            values['newrev_type'] = self.new.type
1002
1003        reply_to = self.environment.get_reply_to_refchange(self)
1004        if reply_to:
1005            values['reply_to'] = reply_to
1006
1007        return values
1008
1009    def send_single_combined_email(self, known_added_sha1s):
1010        """Determine if a combined refchange/revision email should be sent
1011
1012        If there is only a single new (non-merge) commit added by a
1013        change, it is useful to combine the ReferenceChange and
1014        Revision emails into one.  In such a case, return the single
1015        revision; otherwise, return None.
1016
1017        This method is overridden in BranchChange."""
1018
1019        return None
1020
1021    def generate_combined_email(self, push, revision, body_filter=None, extra_header_values={}):
1022        """Generate an email describing this change AND specified revision.
1023
1024        Iterate over the lines (including the header lines) of an
1025        email describing this change.  If body_filter is not None,
1026        then use it to filter the lines that are intended for the
1027        email body.
1028
1029        The extra_header_values field is received as a dict and not as
1030        **kwargs, to allow passing other keyword arguments in the
1031        future (e.g. passing extra values to generate_email_intro()
1032
1033        This method is overridden in BranchChange."""
1034
1035        raise NotImplementedError
1036
1037    def get_subject(self):
1038        template = {
1039            'create': REF_CREATED_SUBJECT_TEMPLATE,
1040            'update': REF_UPDATED_SUBJECT_TEMPLATE,
1041            'delete': REF_DELETED_SUBJECT_TEMPLATE,
1042            }[self.change_type]
1043        return self.expand(template)
1044
1045    def generate_email_header(self, **extra_values):
1046        if 'subject' not in extra_values:
1047            extra_values['subject'] = self.get_subject()
1048
1049        for line in self.expand_header_lines(
1050                self.header_template, **extra_values
1051                ):
1052            yield line
1053
1054    def generate_email_intro(self):
1055        for line in self.expand_lines(self.intro_template):
1056            yield line
1057
1058    def generate_email_body(self, push):
1059        """Call the appropriate body-generation routine.
1060
1061        Call one of generate_create_summary() /
1062        generate_update_summary() / generate_delete_summary()."""
1063
1064        change_summary = {
1065            'create': self.generate_create_summary,
1066            'delete': self.generate_delete_summary,
1067            'update': self.generate_update_summary,
1068            }[self.change_type](push)
1069        for line in change_summary:
1070            yield line
1071
1072        for line in self.generate_revision_change_summary(push):
1073            yield line
1074
1075    def generate_email_footer(self):
1076        return self.expand_lines(self.footer_template)
1077
1078    def generate_revision_change_graph(self, push):
1079        if self.showgraph:
1080            args = ['--graph'] + self.graphopts
1081            for newold in ('new', 'old'):
1082                has_newold = False
1083                spec = push.get_commits_spec(newold, self)
1084                for line in git_log(spec, args=args, keepends=True):
1085                    if not has_newold:
1086                        has_newold = True
1087                        yield '\n'
1088                        yield 'Graph of %s commits:\n\n' % (
1089                            {'new': 'new', 'old': 'discarded'}[newold],)
1090                    yield '  ' + line
1091                if has_newold:
1092                    yield '\n'
1093
1094    def generate_revision_change_log(self, new_commits_list):
1095        if self.showlog:
1096            yield '\n'
1097            yield 'Detailed log of new commits:\n\n'
1098            for line in read_git_lines(
1099                    ['log', '--no-walk']
1100                    + self.logopts
1101                    + new_commits_list
1102                    + ['--'],
1103                    keepends=True,
1104                    ):
1105                yield line
1106
1107    def generate_new_revision_summary(self, tot, new_commits_list, push):
1108        for line in self.expand_lines(NEW_REVISIONS_TEMPLATE, tot=tot):
1109            yield line
1110        for line in self.generate_revision_change_graph(push):
1111            yield line
1112        for line in self.generate_revision_change_log(new_commits_list):
1113            yield line
1114
1115    def generate_revision_change_summary(self, push):
1116        """Generate a summary of the revisions added/removed by this change."""
1117
1118        if self.new.commit_sha1 and not self.old.commit_sha1:
1119            # A new reference was created.  List the new revisions
1120            # brought by the new reference (i.e., those revisions that
1121            # were not in the repository before this reference
1122            # change).
1123            sha1s = list(push.get_new_commits(self))
1124            sha1s.reverse()
1125            tot = len(sha1s)
1126            new_revisions = [
1127                Revision(self, GitObject(sha1), num=i + 1, tot=tot)
1128                for (i, sha1) in enumerate(sha1s)
1129                ]
1130
1131            if new_revisions:
1132                yield self.expand('This %(refname_type)s includes the following new commits:\n')
1133                yield '\n'
1134                for r in new_revisions:
1135                    (sha1, subject) = r.rev.get_summary()
1136                    yield r.expand(
1137                        BRIEF_SUMMARY_TEMPLATE, action='new', text=subject,
1138                        )
1139                yield '\n'
1140                for line in self.generate_new_revision_summary(
1141                        tot, [r.rev.sha1 for r in new_revisions], push):
1142                    yield line
1143            else:
1144                for line in self.expand_lines(NO_NEW_REVISIONS_TEMPLATE):
1145                    yield line
1146
1147        elif self.new.commit_sha1 and self.old.commit_sha1:
1148            # A reference was changed to point at a different commit.
1149            # List the revisions that were removed and/or added *from
1150            # that reference* by this reference change, along with a
1151            # diff between the trees for its old and new values.
1152
1153            # List of the revisions that were added to the branch by
1154            # this update.  Note this list can include revisions that
1155            # have already had notification emails; we want such
1156            # revisions in the summary even though we will not send
1157            # new notification emails for them.
1158            adds = list(generate_summaries(
1159                '--topo-order', '--reverse', '%s..%s'
1160                % (self.old.commit_sha1, self.new.commit_sha1,)
1161                ))
1162
1163            # List of the revisions that were removed from the branch
1164            # by this update.  This will be empty except for
1165            # non-fast-forward updates.
1166            discards = list(generate_summaries(
1167                '%s..%s' % (self.new.commit_sha1, self.old.commit_sha1,)
1168                ))
1169
1170            if adds:
1171                new_commits_list = push.get_new_commits(self)
1172            else:
1173                new_commits_list = []
1174            new_commits = CommitSet(new_commits_list)
1175
1176            if discards:
1177                discarded_commits = CommitSet(push.get_discarded_commits(self))
1178            else:
1179                discarded_commits = CommitSet([])
1180
1181            if discards and adds:
1182                for (sha1, subject) in discards:
1183                    if sha1 in discarded_commits:
1184                        action = 'discards'
1185                    else:
1186                        action = 'omits'
1187                    yield self.expand(
1188                        BRIEF_SUMMARY_TEMPLATE, action=action,
1189                        rev_short=sha1, text=subject,
1190                        )
1191                for (sha1, subject) in adds:
1192                    if sha1 in new_commits:
1193                        action = 'new'
1194                    else:
1195                        action = 'adds'
1196                    yield self.expand(
1197                        BRIEF_SUMMARY_TEMPLATE, action=action,
1198                        rev_short=sha1, text=subject,
1199                        )
1200                yield '\n'
1201                for line in self.expand_lines(NON_FF_TEMPLATE):
1202                    yield line
1203
1204            elif discards:
1205                for (sha1, subject) in discards:
1206                    if sha1 in discarded_commits:
1207                        action = 'discards'
1208                    else:
1209                        action = 'omits'
1210                    yield self.expand(
1211                        BRIEF_SUMMARY_TEMPLATE, action=action,
1212                        rev_short=sha1, text=subject,
1213                        )
1214                yield '\n'
1215                for line in self.expand_lines(REWIND_ONLY_TEMPLATE):
1216                    yield line
1217
1218            elif adds:
1219                (sha1, subject) = self.old.get_summary()
1220                yield self.expand(
1221                    BRIEF_SUMMARY_TEMPLATE, action='from',
1222                    rev_short=sha1, text=subject,
1223                    )
1224                for (sha1, subject) in adds:
1225                    if sha1 in new_commits:
1226                        action = 'new'
1227                    else:
1228                        action = 'adds'
1229                    yield self.expand(
1230                        BRIEF_SUMMARY_TEMPLATE, action=action,
1231                        rev_short=sha1, text=subject,
1232                        )
1233
1234            yield '\n'
1235
1236            if new_commits:
1237                for line in self.generate_new_revision_summary(
1238                        len(new_commits), new_commits_list, push):
1239                    yield line
1240            else:
1241                for line in self.expand_lines(NO_NEW_REVISIONS_TEMPLATE):
1242                    yield line
1243                for line in self.generate_revision_change_graph(push):
1244                    yield line
1245
1246            # The diffstat is shown from the old revision to the new
1247            # revision.  This is to show the truth of what happened in
1248            # this change.  There's no point showing the stat from the
1249            # base to the new revision because the base is effectively a
1250            # random revision at this point - the user will be interested
1251            # in what this revision changed - including the undoing of
1252            # previous revisions in the case of non-fast-forward updates.
1253            yield '\n'
1254            yield 'Summary of changes:\n'
1255            for line in read_git_lines(
1256                    ['diff-tree']
1257                    + self.diffopts
1258                    + ['%s..%s' % (self.old.commit_sha1, self.new.commit_sha1,)],
1259                    keepends=True,
1260                    ):
1261                yield line
1262
1263        elif self.old.commit_sha1 and not self.new.commit_sha1:
1264            # A reference was deleted.  List the revisions that were
1265            # removed from the repository by this reference change.
1266
1267            sha1s = list(push.get_discarded_commits(self))
1268            tot = len(sha1s)
1269            discarded_revisions = [
1270                Revision(self, GitObject(sha1), num=i + 1, tot=tot)
1271                for (i, sha1) in enumerate(sha1s)
1272                ]
1273
1274            if discarded_revisions:
1275                for line in self.expand_lines(DISCARDED_REVISIONS_TEMPLATE):
1276                    yield line
1277                yield '\n'
1278                for r in discarded_revisions:
1279                    (sha1, subject) = r.rev.get_summary()
1280                    yield r.expand(
1281                        BRIEF_SUMMARY_TEMPLATE, action='discards', text=subject,
1282                        )
1283                for line in self.generate_revision_change_graph(push):
1284                    yield line
1285            else:
1286                for line in self.expand_lines(NO_DISCARDED_REVISIONS_TEMPLATE):
1287                    yield line
1288
1289        elif not self.old.commit_sha1 and not self.new.commit_sha1:
1290            for line in self.expand_lines(NON_COMMIT_UPDATE_TEMPLATE):
1291                yield line
1292
1293    def generate_create_summary(self, push):
1294        """Called for the creation of a reference."""
1295
1296        # This is a new reference and so oldrev is not valid
1297        (sha1, subject) = self.new.get_summary()
1298        yield self.expand(
1299            BRIEF_SUMMARY_TEMPLATE, action='at',
1300            rev_short=sha1, text=subject,
1301            )
1302        yield '\n'
1303
1304    def generate_update_summary(self, push):
1305        """Called for the change of a pre-existing branch."""
1306
1307        return iter([])
1308
1309    def generate_delete_summary(self, push):
1310        """Called for the deletion of any type of reference."""
1311
1312        (sha1, subject) = self.old.get_summary()
1313        yield self.expand(
1314            BRIEF_SUMMARY_TEMPLATE, action='was',
1315            rev_short=sha1, text=subject,
1316            )
1317        yield '\n'
1318
1319
1320class BranchChange(ReferenceChange):
1321    refname_type = 'branch'
1322
1323    def __init__(self, environment, refname, short_refname, old, new, rev):
1324        ReferenceChange.__init__(
1325            self, environment,
1326            refname=refname, short_refname=short_refname,
1327            old=old, new=new, rev=rev,
1328            )
1329        self.recipients = environment.get_refchange_recipients(self)
1330        self._single_revision = None
1331
1332    def send_single_combined_email(self, known_added_sha1s):
1333        if not self.environment.combine_when_single_commit:
1334            return None
1335
1336        # In the sadly-all-too-frequent usecase of people pushing only
1337        # one of their commits at a time to a repository, users feel
1338        # the reference change summary emails are noise rather than
1339        # important signal.  This is because, in this particular
1340        # usecase, there is a reference change summary email for each
1341        # new commit, and all these summaries do is point out that
1342        # there is one new commit (which can readily be inferred by
1343        # the existence of the individual revision email that is also
1344        # sent).  In such cases, our users prefer there to be a combined
1345        # reference change summary/new revision email.
1346        #
1347        # So, if the change is an update and it doesn't discard any
1348        # commits, and it adds exactly one non-merge commit (gerrit
1349        # forces a workflow where every commit is individually merged
1350        # and the git-multimail hook fired off for just this one
1351        # change), then we send a combined refchange/revision email.
1352        try:
1353            # If this change is a reference update that doesn't discard
1354            # any commits...
1355            if self.change_type != 'update':
1356                return None
1357
1358            if read_git_lines(
1359                    ['merge-base', self.old.sha1, self.new.sha1]
1360                    ) != [self.old.sha1]:
1361                return None
1362
1363            # Check if this update introduced exactly one non-merge
1364            # commit:
1365
1366            def split_line(line):
1367                """Split line into (sha1, [parent,...])."""
1368
1369                words = line.split()
1370                return (words[0], words[1:])
1371
1372            # Get the new commits introduced by the push as a list of
1373            # (sha1, [parent,...])
1374            new_commits = [
1375                split_line(line)
1376                for line in read_git_lines(
1377                    [
1378                        'log', '-3', '--format=%H %P',
1379                        '%s..%s' % (self.old.sha1, self.new.sha1),
1380                        ]
1381                    )
1382                ]
1383
1384            if not new_commits:
1385                return None
1386
1387            # If the newest commit is a merge, save it for a later check
1388            # but otherwise ignore it
1389            merge = None
1390            tot = len(new_commits)
1391            if len(new_commits[0][1]) > 1:
1392                merge = new_commits[0][0]
1393                del new_commits[0]
1394
1395            # Our primary check: we can't combine if more than one commit
1396            # is introduced.  We also currently only combine if the new
1397            # commit is a non-merge commit, though it may make sense to
1398            # combine if it is a merge as well.
1399            if not (
1400                    len(new_commits) == 1
1401                    and len(new_commits[0][1]) == 1
1402                    and new_commits[0][0] in known_added_sha1s
1403                    ):
1404                return None
1405
1406            # We do not want to combine revision and refchange emails if
1407            # those go to separate locations.
1408            rev = Revision(self, GitObject(new_commits[0][0]), 1, tot)
1409            if rev.recipients != self.recipients:
1410                return None
1411
1412            # We ignored the newest commit if it was just a merge of the one
1413            # commit being introduced.  But we don't want to ignore that
1414            # merge commit it it involved conflict resolutions.  Check that.
1415            if merge and merge != read_git_output(['diff-tree', '--cc', merge]):
1416                return None
1417
1418            # We can combine the refchange and one new revision emails
1419            # into one.  Return the Revision that a combined email should
1420            # be sent about.
1421            return rev
1422        except CommandError:
1423            # Cannot determine number of commits in old..new or new..old;
1424            # don't combine reference/revision emails:
1425            return None
1426
1427    def generate_combined_email(self, push, revision, body_filter=None, extra_header_values={}):
1428        values = revision.get_values()
1429        if extra_header_values:
1430            values.update(extra_header_values)
1431        if 'subject' not in extra_header_values:
1432            values['subject'] = self.expand(COMBINED_REFCHANGE_REVISION_SUBJECT_TEMPLATE, **values)
1433
1434        self._single_revision = revision
1435        self.header_template = COMBINED_HEADER_TEMPLATE
1436        self.intro_template = COMBINED_INTRO_TEMPLATE
1437        self.footer_template = COMBINED_FOOTER_TEMPLATE
1438        for line in self.generate_email(push, body_filter, values):
1439            yield line
1440
1441    def generate_email_body(self, push):
1442        '''Call the appropriate body generation routine.
1443
1444        If this is a combined refchange/revision email, the special logic
1445        for handling this combined email comes from this function.  For
1446        other cases, we just use the normal handling.'''
1447
1448        # If self._single_revision isn't set; don't override
1449        if not self._single_revision:
1450            for line in super(BranchChange, self).generate_email_body(push):
1451                yield line
1452            return
1453
1454        # This is a combined refchange/revision email; we first provide
1455        # some info from the refchange portion, and then call the revision
1456        # generate_email_body function to handle the revision portion.
1457        adds = list(generate_summaries(
1458            '--topo-order', '--reverse', '%s..%s'
1459            % (self.old.commit_sha1, self.new.commit_sha1,)
1460            ))
1461
1462        yield self.expand("The following commit(s) were added to %(refname)s by this push:\n")
1463        for (sha1, subject) in adds:
1464            yield self.expand(
1465                BRIEF_SUMMARY_TEMPLATE, action='new',
1466                rev_short=sha1, text=subject,
1467                )
1468
1469        yield self._single_revision.rev.short + " is described below\n"
1470        yield '\n'
1471
1472        for line in self._single_revision.generate_email_body(push):
1473            yield line
1474
1475
1476class AnnotatedTagChange(ReferenceChange):
1477    refname_type = 'annotated tag'
1478
1479    def __init__(self, environment, refname, short_refname, old, new, rev):
1480        ReferenceChange.__init__(
1481            self, environment,
1482            refname=refname, short_refname=short_refname,
1483            old=old, new=new, rev=rev,
1484            )
1485        self.recipients = environment.get_announce_recipients(self)
1486        self.show_shortlog = environment.announce_show_shortlog
1487
1488    ANNOTATED_TAG_FORMAT = (
1489        '%(*objectname)\n'
1490        '%(*objecttype)\n'
1491        '%(taggername)\n'
1492        '%(taggerdate)'
1493        )
1494
1495    def describe_tag(self, push):
1496        """Describe the new value of an annotated tag."""
1497
1498        # Use git for-each-ref to pull out the individual fields from
1499        # the tag
1500        [tagobject, tagtype, tagger, tagged] = read_git_lines(
1501            ['for-each-ref', '--format=%s' % (self.ANNOTATED_TAG_FORMAT,), self.refname],
1502            )
1503
1504        yield self.expand(
1505            BRIEF_SUMMARY_TEMPLATE, action='tagging',
1506            rev_short=tagobject, text='(%s)' % (tagtype,),
1507            )
1508        if tagtype == 'commit':
1509            # If the tagged object is a commit, then we assume this is a
1510            # release, and so we calculate which tag this tag is
1511            # replacing
1512            try:
1513                prevtag = read_git_output(['describe', '--abbrev=0', '%s^' % (self.new,)])
1514            except CommandError:
1515                prevtag = None
1516            if prevtag:
1517                yield '  replaces  %s\n' % (prevtag,)
1518        else:
1519            prevtag = None
1520            yield '    length  %s bytes\n' % (read_git_output(['cat-file', '-s', tagobject]),)
1521
1522        yield ' tagged by  %s\n' % (tagger,)
1523        yield '        on  %s\n' % (tagged,)
1524        yield '\n'
1525
1526        # Show the content of the tag message; this might contain a
1527        # change log or release notes so is worth displaying.
1528        yield LOGBEGIN
1529        contents = list(read_git_lines(['cat-file', 'tag', self.new.sha1], keepends=True))
1530        contents = contents[contents.index('\n') + 1:]
1531        if contents and contents[-1][-1:] != '\n':
1532            contents.append('\n')
1533        for line in contents:
1534            yield line
1535
1536        if self.show_shortlog and tagtype == 'commit':
1537            # Only commit tags make sense to have rev-list operations
1538            # performed on them
1539            yield '\n'
1540            if prevtag:
1541                # Show changes since the previous release
1542                revlist = read_git_output(
1543                    ['rev-list', '--pretty=short', '%s..%s' % (prevtag, self.new,)],
1544                    keepends=True,
1545                    )
1546            else:
1547                # No previous tag, show all the changes since time
1548                # began
1549                revlist = read_git_output(
1550                    ['rev-list', '--pretty=short', '%s' % (self.new,)],
1551                    keepends=True,
1552                    )
1553            for line in read_git_lines(['shortlog'], input=revlist, keepends=True):
1554                yield line
1555
1556        yield LOGEND
1557        yield '\n'
1558
1559    def generate_create_summary(self, push):
1560        """Called for the creation of an annotated tag."""
1561
1562        for line in self.expand_lines(TAG_CREATED_TEMPLATE):
1563            yield line
1564
1565        for line in self.describe_tag(push):
1566            yield line
1567
1568    def generate_update_summary(self, push):
1569        """Called for the update of an annotated tag.
1570
1571        This is probably a rare event and may not even be allowed."""
1572
1573        for line in self.expand_lines(TAG_UPDATED_TEMPLATE):
1574            yield line
1575
1576        for line in self.describe_tag(push):
1577            yield line
1578
1579    def generate_delete_summary(self, push):
1580        """Called when a non-annotated reference is updated."""
1581
1582        for line in self.expand_lines(TAG_DELETED_TEMPLATE):
1583            yield line
1584
1585        yield self.expand('   tag was  %(oldrev_short)s\n')
1586        yield '\n'
1587
1588
1589class NonAnnotatedTagChange(ReferenceChange):
1590    refname_type = 'tag'
1591
1592    def __init__(self, environment, refname, short_refname, old, new, rev):
1593        ReferenceChange.__init__(
1594            self, environment,
1595            refname=refname, short_refname=short_refname,
1596            old=old, new=new, rev=rev,
1597            )
1598        self.recipients = environment.get_refchange_recipients(self)
1599
1600    def generate_create_summary(self, push):
1601        """Called for the creation of an annotated tag."""
1602
1603        for line in self.expand_lines(TAG_CREATED_TEMPLATE):
1604            yield line
1605
1606    def generate_update_summary(self, push):
1607        """Called when a non-annotated reference is updated."""
1608
1609        for line in self.expand_lines(TAG_UPDATED_TEMPLATE):
1610            yield line
1611
1612    def generate_delete_summary(self, push):
1613        """Called when a non-annotated reference is updated."""
1614
1615        for line in self.expand_lines(TAG_DELETED_TEMPLATE):
1616            yield line
1617
1618        for line in ReferenceChange.generate_delete_summary(self, push):
1619            yield line
1620
1621
1622class OtherReferenceChange(ReferenceChange):
1623    refname_type = 'reference'
1624
1625    def __init__(self, environment, refname, short_refname, old, new, rev):
1626        # We use the full refname as short_refname, because otherwise
1627        # the full name of the reference would not be obvious from the
1628        # text of the email.
1629        ReferenceChange.__init__(
1630            self, environment,
1631            refname=refname, short_refname=refname,
1632            old=old, new=new, rev=rev,
1633            )
1634        self.recipients = environment.get_refchange_recipients(self)
1635
1636
1637class Mailer(object):
1638    """An object that can send emails."""
1639
1640    def send(self, lines, to_addrs):
1641        """Send an email consisting of lines.
1642
1643        lines must be an iterable over the lines constituting the
1644        header and body of the email.  to_addrs is a list of recipient
1645        addresses (can be needed even if lines already contains a
1646        "To:" field).  It can be either a string (comma-separated list
1647        of email addresses) or a Python list of individual email
1648        addresses.
1649
1650        """
1651
1652        raise NotImplementedError()
1653
1654
1655class SendMailer(Mailer):
1656    """Send emails using 'sendmail -oi -t'."""
1657
1658    SENDMAIL_CANDIDATES = [
1659        '/usr/sbin/sendmail',
1660        '/usr/lib/sendmail',
1661        ]
1662
1663    @staticmethod
1664    def find_sendmail():
1665        for path in SendMailer.SENDMAIL_CANDIDATES:
1666            if os.access(path, os.X_OK):
1667                return path
1668        else:
1669            raise ConfigurationException(
1670                'No sendmail executable found.  '
1671                'Try setting multimailhook.sendmailCommand.'
1672                )
1673
1674    def __init__(self, command=None, envelopesender=None):
1675        """Construct a SendMailer instance.
1676
1677        command should be the command and arguments used to invoke
1678        sendmail, as a list of strings.  If an envelopesender is
1679        provided, it will also be passed to the command, via '-f
1680        envelopesender'."""
1681
1682        if command:
1683            self.command = command[:]
1684        else:
1685            self.command = [self.find_sendmail(), '-oi', '-t']
1686
1687        if envelopesender:
1688            self.command.extend(['-f', envelopesender])
1689
1690    def send(self, lines, to_addrs):
1691        try:
1692            p = subprocess.Popen(self.command, stdin=subprocess.PIPE)
1693        except OSError, e:
1694            sys.stderr.write(
1695                '*** Cannot execute command: %s\n' % ' '.join(self.command)
1696                + '*** %s\n' % str(e)
1697                + '*** Try setting multimailhook.mailer to "smtp"\n'
1698                '*** to send emails without using the sendmail command.\n'
1699                )
1700            sys.exit(1)
1701        try:
1702            p.stdin.writelines(lines)
1703        except Exception, e:
1704            sys.stderr.write(
1705                '*** Error while generating commit email\n'
1706                '***  - mail sending aborted.\n'
1707                )
1708            try:
1709                # subprocess.terminate() is not available in Python 2.4
1710                p.terminate()
1711            except AttributeError:
1712                pass
1713            raise e
1714        else:
1715            p.stdin.close()
1716            retcode = p.wait()
1717            if retcode:
1718                raise CommandError(self.command, retcode)
1719
1720
1721class SMTPMailer(Mailer):
1722    """Send emails using Python's smtplib."""
1723
1724    def __init__(self, envelopesender, smtpserver,
1725                 smtpservertimeout=10.0, smtpserverdebuglevel=0,
1726                 smtpencryption='none',
1727                 smtpuser='', smtppass='',
1728                 ):
1729        if not envelopesender:
1730            sys.stderr.write(
1731                'fatal: git_multimail: cannot use SMTPMailer without a sender address.\n'
1732                'please set either multimailhook.envelopeSender or user.email\n'
1733                )
1734            sys.exit(1)
1735        if smtpencryption == 'ssl' and not (smtpuser and smtppass):
1736            raise ConfigurationException(
1737                'Cannot use SMTPMailer with security option ssl '
1738                'without options username and password.'
1739                )
1740        self.envelopesender = envelopesender
1741        self.smtpserver = smtpserver
1742        self.smtpservertimeout = smtpservertimeout
1743        self.smtpserverdebuglevel = smtpserverdebuglevel
1744        self.security = smtpencryption
1745        self.username = smtpuser
1746        self.password = smtppass
1747        try:
1748            if self.security == 'none':
1749                self.smtp = smtplib.SMTP(self.smtpserver, timeout=self.smtpservertimeout)
1750            elif self.security == 'ssl':
1751                self.smtp = smtplib.SMTP_SSL(self.smtpserver, timeout=self.smtpservertimeout)
1752            elif self.security == 'tls':
1753                if ':' not in self.smtpserver:
1754                    self.smtpserver += ':587'  # default port for TLS
1755                self.smtp = smtplib.SMTP(self.smtpserver, timeout=self.smtpservertimeout)
1756                self.smtp.ehlo()
1757                self.smtp.starttls()
1758                self.smtp.ehlo()
1759            else:
1760                sys.stdout.write('*** Error: Control reached an invalid option. ***')
1761                sys.exit(1)
1762            if self.smtpserverdebuglevel > 0:
1763                sys.stdout.write(
1764                    "*** Setting debug on for SMTP server connection (%s) ***\n"
1765                    % self.smtpserverdebuglevel)
1766                self.smtp.set_debuglevel(self.smtpserverdebuglevel)
1767        except Exception, e:
1768            sys.stderr.write(
1769                '*** Error establishing SMTP connection to %s ***\n'
1770                % self.smtpserver)
1771            sys.stderr.write('*** %s\n' % str(e))
1772            sys.exit(1)
1773
1774    def __del__(self):
1775        if hasattr(self, 'smtp'):
1776            self.smtp.quit()
1777
1778    def send(self, lines, to_addrs):
1779        try:
1780            if self.username or self.password:
1781                sys.stderr.write("*** Authenticating as %s ***\n" % self.username)
1782                self.smtp.login(self.username, self.password)
1783            msg = ''.join(lines)
1784            # turn comma-separated list into Python list if needed.
1785            if isinstance(to_addrs, basestring):
1786                to_addrs = [email for (name, email) in getaddresses([to_addrs])]
1787            self.smtp.sendmail(self.envelopesender, to_addrs, msg)
1788        except Exception, e:
1789            sys.stderr.write('*** Error sending email ***\n')
1790            sys.stderr.write('*** %s\n' % str(e))
1791            self.smtp.quit()
1792            sys.exit(1)
1793
1794
1795class OutputMailer(Mailer):
1796    """Write emails to an output stream, bracketed by lines of '=' characters.
1797
1798    This is intended for debugging purposes."""
1799
1800    SEPARATOR = '=' * 75 + '\n'
1801
1802    def __init__(self, f):
1803        self.f = f
1804
1805    def send(self, lines, to_addrs):
1806        self.f.write(self.SEPARATOR)
1807        self.f.writelines(lines)
1808        self.f.write(self.SEPARATOR)
1809
1810
1811def get_git_dir():
1812    """Determine GIT_DIR.
1813
1814    Determine GIT_DIR either from the GIT_DIR environment variable or
1815    from the working directory, using Git's usual rules."""
1816
1817    try:
1818        return read_git_output(['rev-parse', '--git-dir'])
1819    except CommandError:
1820        sys.stderr.write('fatal: git_multimail: not in a git directory\n')
1821        sys.exit(1)
1822
1823
1824class Environment(object):
1825    """Describes the environment in which the push is occurring.
1826
1827    An Environment object encapsulates information about the local
1828    environment.  For example, it knows how to determine:
1829
1830    * the name of the repository to which the push occurred
1831
1832    * what user did the push
1833
1834    * what users want to be informed about various types of changes.
1835
1836    An Environment object is expected to have the following methods:
1837
1838        get_repo_shortname()
1839
1840            Return a short name for the repository, for display
1841            purposes.
1842
1843        get_repo_path()
1844
1845            Return the absolute path to the Git repository.
1846
1847        get_emailprefix()
1848
1849            Return a string that will be prefixed to every email's
1850            subject.
1851
1852        get_pusher()
1853
1854            Return the username of the person who pushed the changes.
1855            This value is used in the email body to indicate who
1856            pushed the change.
1857
1858        get_pusher_email() (may return None)
1859
1860            Return the email address of the person who pushed the
1861            changes.  The value should be a single RFC 2822 email
1862            address as a string; e.g., "Joe User <user@example.com>"
1863            if available, otherwise "user@example.com".  If set, the
1864            value is used as the Reply-To address for refchange
1865            emails.  If it is impossible to determine the pusher's
1866            email, this attribute should be set to None (in which case
1867            no Reply-To header will be output).
1868
1869        get_sender()
1870
1871            Return the address to be used as the 'From' email address
1872            in the email envelope.
1873
1874        get_fromaddr()
1875
1876            Return the 'From' email address used in the email 'From:'
1877            headers.  (May be a full RFC 2822 email address like 'Joe
1878            User <user@example.com>'.)
1879
1880        get_administrator()
1881
1882            Return the name and/or email of the repository
1883            administrator.  This value is used in the footer as the
1884            person to whom requests to be removed from the
1885            notification list should be sent.  Ideally, it should
1886            include a valid email address.
1887
1888        get_reply_to_refchange()
1889        get_reply_to_commit()
1890
1891            Return the address to use in the email "Reply-To" header,
1892            as a string.  These can be an RFC 2822 email address, or
1893            None to omit the "Reply-To" header.
1894            get_reply_to_refchange() is used for refchange emails;
1895            get_reply_to_commit() is used for individual commit
1896            emails.
1897
1898    They should also define the following attributes:
1899
1900        announce_show_shortlog (bool)
1901
1902            True iff announce emails should include a shortlog.
1903
1904        refchange_showgraph (bool)
1905
1906            True iff refchanges emails should include a detailed graph.
1907
1908        refchange_showlog (bool)
1909
1910            True iff refchanges emails should include a detailed log.
1911
1912        diffopts (list of strings)
1913
1914            The options that should be passed to 'git diff' for the
1915            summary email.  The value should be a list of strings
1916            representing words to be passed to the command.
1917
1918        graphopts (list of strings)
1919
1920            Analogous to diffopts, but contains options passed to
1921            'git log --graph' when generating the detailed graph for
1922            a set of commits (see refchange_showgraph)
1923
1924        logopts (list of strings)
1925
1926            Analogous to diffopts, but contains options passed to
1927            'git log' when generating the detailed log for a set of
1928            commits (see refchange_showlog)
1929
1930        commitlogopts (list of strings)
1931
1932            The options that should be passed to 'git log' for each
1933            commit mail.  The value should be a list of strings
1934            representing words to be passed to the command.
1935
1936        quiet (bool)
1937            On success do not write to stderr
1938
1939        stdout (bool)
1940            Write email to stdout rather than emailing. Useful for debugging
1941
1942        combine_when_single_commit (bool)
1943
1944            True if a combined email should be produced when a single
1945            new commit is pushed to a branch, False otherwise.
1946
1947    """
1948
1949    REPO_NAME_RE = re.compile(r'^(?P<name>.+?)(?:\.git)$')
1950
1951    def __init__(self, osenv=None):
1952        self.osenv = osenv or os.environ
1953        self.announce_show_shortlog = False
1954        self.maxcommitemails = 500
1955        self.diffopts = ['--stat', '--summary', '--find-copies-harder']
1956        self.graphopts = ['--oneline', '--decorate']
1957        self.logopts = []
1958        self.refchange_showgraph = False
1959        self.refchange_showlog = False
1960        self.commitlogopts = ['-C', '--stat', '-p', '--cc']
1961        self.quiet = False
1962        self.stdout = False
1963        self.combine_when_single_commit = True
1964
1965        self.COMPUTED_KEYS = [
1966            'administrator',
1967            'charset',
1968            'emailprefix',
1969            'fromaddr',
1970            'pusher',
1971            'pusher_email',
1972            'repo_path',
1973            'repo_shortname',
1974            'sender',
1975            ]
1976
1977        self._values = None
1978
1979    def get_repo_shortname(self):
1980        """Use the last part of the repo path, with ".git" stripped off if present."""
1981
1982        basename = os.path.basename(os.path.abspath(self.get_repo_path()))
1983        m = self.REPO_NAME_RE.match(basename)
1984        if m:
1985            return m.group('name')
1986        else:
1987            return basename
1988
1989    def get_pusher(self):
1990        raise NotImplementedError()
1991
1992    def get_pusher_email(self):
1993        return None
1994
1995    def get_fromaddr(self):
1996        config = Config('user')
1997        fromname = config.get('name', default='')
1998        fromemail = config.get('email', default='')
1999        if fromemail:
2000            return formataddr([fromname, fromemail])
2001        return self.get_sender()
2002
2003    def get_administrator(self):
2004        return 'the administrator of this repository'
2005
2006    def get_emailprefix(self):
2007        return ''
2008
2009    def get_repo_path(self):
2010        if read_git_output(['rev-parse', '--is-bare-repository']) == 'true':
2011            path = get_git_dir()
2012        else:
2013            path = read_git_output(['rev-parse', '--show-toplevel'])
2014        return os.path.abspath(path)
2015
2016    def get_charset(self):
2017        return CHARSET
2018
2019    def get_values(self):
2020        """Return a dictionary {keyword: expansion} for this Environment.
2021
2022        This method is called by Change._compute_values().  The keys
2023        in the returned dictionary are available to be used in any of
2024        the templates.  The dictionary is created by calling
2025        self.get_NAME() for each of the attributes named in
2026        COMPUTED_KEYS and recording those that do not return None.
2027        The return value is always a new dictionary."""
2028
2029        if self._values is None:
2030            values = {}
2031
2032            for key in self.COMPUTED_KEYS:
2033                value = getattr(self, 'get_%s' % (key,))()
2034                if value is not None:
2035                    values[key] = value
2036
2037            self._values = values
2038
2039        return self._values.copy()
2040
2041    def get_refchange_recipients(self, refchange):
2042        """Return the recipients for notifications about refchange.
2043
2044        Return the list of email addresses to which notifications
2045        about the specified ReferenceChange should be sent."""
2046
2047        raise NotImplementedError()
2048
2049    def get_announce_recipients(self, annotated_tag_change):
2050        """Return the recipients for notifications about annotated_tag_change.
2051
2052        Return the list of email addresses to which notifications
2053        about the specified AnnotatedTagChange should be sent."""
2054
2055        raise NotImplementedError()
2056
2057    def get_reply_to_refchange(self, refchange):
2058        return self.get_pusher_email()
2059
2060    def get_revision_recipients(self, revision):
2061        """Return the recipients for messages about revision.
2062
2063        Return the list of email addresses to which notifications
2064        about the specified Revision should be sent.  This method
2065        could be overridden, for example, to take into account the
2066        contents of the revision when deciding whom to notify about
2067        it.  For example, there could be a scheme for users to express
2068        interest in particular files or subdirectories, and only
2069        receive notification emails for revisions that affecting those
2070        files."""
2071
2072        raise NotImplementedError()
2073
2074    def get_reply_to_commit(self, revision):
2075        return revision.author
2076
2077    def filter_body(self, lines):
2078        """Filter the lines intended for an email body.
2079
2080        lines is an iterable over the lines that would go into the
2081        email body.  Filter it (e.g., limit the number of lines, the
2082        line length, character set, etc.), returning another iterable.
2083        See FilterLinesEnvironmentMixin and MaxlinesEnvironmentMixin
2084        for classes implementing this functionality."""
2085
2086        return lines
2087
2088    def log_msg(self, msg):
2089        """Write the string msg on a log file or on stderr.
2090
2091        Sends the text to stderr by default, override to change the behavior."""
2092        sys.stderr.write(msg)
2093
2094    def log_warning(self, msg):
2095        """Write the string msg on a log file or on stderr.
2096
2097        Sends the text to stderr by default, override to change the behavior."""
2098        sys.stderr.write(msg)
2099
2100    def log_error(self, msg):
2101        """Write the string msg on a log file or on stderr.
2102
2103        Sends the text to stderr by default, override to change the behavior."""
2104        sys.stderr.write(msg)
2105
2106
2107class ConfigEnvironmentMixin(Environment):
2108    """A mixin that sets self.config to its constructor's config argument.
2109
2110    This class's constructor consumes the "config" argument.
2111
2112    Mixins that need to inspect the config should inherit from this
2113    class (1) to make sure that "config" is still in the constructor
2114    arguments with its own constructor runs and/or (2) to be sure that
2115    self.config is set after construction."""
2116
2117    def __init__(self, config, **kw):
2118        super(ConfigEnvironmentMixin, self).__init__(**kw)
2119        self.config = config
2120
2121
2122class ConfigOptionsEnvironmentMixin(ConfigEnvironmentMixin):
2123    """An Environment that reads most of its information from "git config"."""
2124
2125    def __init__(self, config, **kw):
2126        super(ConfigOptionsEnvironmentMixin, self).__init__(
2127            config=config, **kw
2128            )
2129
2130        for var, cfg in (
2131                ('announce_show_shortlog', 'announceshortlog'),
2132                ('refchange_showgraph', 'refchangeShowGraph'),
2133                ('refchange_showlog', 'refchangeshowlog'),
2134                ('quiet', 'quiet'),
2135                ('stdout', 'stdout'),
2136                ):
2137            val = config.get_bool(cfg)
2138            if val is not None:
2139                setattr(self, var, val)
2140
2141        maxcommitemails = config.get('maxcommitemails')
2142        if maxcommitemails is not None:
2143            try:
2144                self.maxcommitemails = int(maxcommitemails)
2145            except ValueError:
2146                self.log_warning(
2147                    '*** Malformed value for multimailhook.maxCommitEmails: %s\n' % maxcommitemails
2148                    + '*** Expected a number.  Ignoring.\n'
2149                    )
2150
2151        diffopts = config.get('diffopts')
2152        if diffopts is not None:
2153            self.diffopts = shlex.split(diffopts)
2154
2155        graphopts = config.get('graphOpts')
2156        if graphopts is not None:
2157            self.graphopts = shlex.split(graphopts)
2158
2159        logopts = config.get('logopts')
2160        if logopts is not None:
2161            self.logopts = shlex.split(logopts)
2162
2163        commitlogopts = config.get('commitlogopts')
2164        if commitlogopts is not None:
2165            self.commitlogopts = shlex.split(commitlogopts)
2166
2167        reply_to = config.get('replyTo')
2168        self.__reply_to_refchange = config.get('replyToRefchange', default=reply_to)
2169        if (
2170                self.__reply_to_refchange is not None
2171                and self.__reply_to_refchange.lower() == 'author'
2172                ):
2173            raise ConfigurationException(
2174                '"author" is not an allowed setting for replyToRefchange'
2175                )
2176        self.__reply_to_commit = config.get('replyToCommit', default=reply_to)
2177
2178        combine = config.get_bool('combineWhenSingleCommit')
2179        if combine is not None:
2180            self.combine_when_single_commit = combine
2181
2182    def get_administrator(self):
2183        return (
2184            self.config.get('administrator')
2185            or self.get_sender()
2186            or super(ConfigOptionsEnvironmentMixin, self).get_administrator()
2187            )
2188
2189    def get_repo_shortname(self):
2190        return (
2191            self.config.get('reponame')
2192            or super(ConfigOptionsEnvironmentMixin, self).get_repo_shortname()
2193            )
2194
2195    def get_emailprefix(self):
2196        emailprefix = self.config.get('emailprefix')
2197        if emailprefix is not None:
2198            emailprefix = emailprefix.strip()
2199            if emailprefix:
2200                return emailprefix + ' '
2201            else:
2202                return ''
2203        else:
2204            return '[%s] ' % (self.get_repo_shortname(),)
2205
2206    def get_sender(self):
2207        return self.config.get('envelopesender')
2208
2209    def get_fromaddr(self):
2210        fromaddr = self.config.get('from')
2211        if fromaddr:
2212            return fromaddr
2213        return super(ConfigOptionsEnvironmentMixin, self).get_fromaddr()
2214
2215    def get_reply_to_refchange(self, refchange):
2216        if self.__reply_to_refchange is None:
2217            return super(ConfigOptionsEnvironmentMixin, self).get_reply_to_refchange(refchange)
2218        elif self.__reply_to_refchange.lower() == 'pusher':
2219            return self.get_pusher_email()
2220        elif self.__reply_to_refchange.lower() == 'none':
2221            return None
2222        else:
2223            return self.__reply_to_refchange
2224
2225    def get_reply_to_commit(self, revision):
2226        if self.__reply_to_commit is None:
2227            return super(ConfigOptionsEnvironmentMixin, self).get_reply_to_commit(revision)
2228        elif self.__reply_to_commit.lower() == 'author':
2229            return revision.author
2230        elif self.__reply_to_commit.lower() == 'pusher':
2231            return self.get_pusher_email()
2232        elif self.__reply_to_commit.lower() == 'none':
2233            return None
2234        else:
2235            return self.__reply_to_commit
2236
2237    def get_scancommitforcc(self):
2238        return self.config.get('scancommitforcc')
2239
2240
2241class FilterLinesEnvironmentMixin(Environment):
2242    """Handle encoding and maximum line length of body lines.
2243
2244        emailmaxlinelength (int or None)
2245
2246            The maximum length of any single line in the email body.
2247            Longer lines are truncated at that length with ' [...]'
2248            appended.
2249
2250        strict_utf8 (bool)
2251
2252            If this field is set to True, then the email body text is
2253            expected to be UTF-8.  Any invalid characters are
2254            converted to U+FFFD, the Unicode replacement character
2255            (encoded as UTF-8, of course).
2256
2257    """
2258
2259    def __init__(self, strict_utf8=True, emailmaxlinelength=500, **kw):
2260        super(FilterLinesEnvironmentMixin, self).__init__(**kw)
2261        self.__strict_utf8 = strict_utf8
2262        self.__emailmaxlinelength = emailmaxlinelength
2263
2264    def filter_body(self, lines):
2265        lines = super(FilterLinesEnvironmentMixin, self).filter_body(lines)
2266        if self.__strict_utf8:
2267            lines = (line.decode(ENCODING, 'replace') for line in lines)
2268            # Limit the line length in Unicode-space to avoid
2269            # splitting characters:
2270            if self.__emailmaxlinelength:
2271                lines = limit_linelength(lines, self.__emailmaxlinelength)
2272            lines = (line.encode(ENCODING, 'replace') for line in lines)
2273        elif self.__emailmaxlinelength:
2274            lines = limit_linelength(lines, self.__emailmaxlinelength)
2275
2276        return lines
2277
2278
2279class ConfigFilterLinesEnvironmentMixin(
2280        ConfigEnvironmentMixin,
2281        FilterLinesEnvironmentMixin,
2282        ):
2283    """Handle encoding and maximum line length based on config."""
2284
2285    def __init__(self, config, **kw):
2286        strict_utf8 = config.get_bool('emailstrictutf8', default=None)
2287        if strict_utf8 is not None:
2288            kw['strict_utf8'] = strict_utf8
2289
2290        emailmaxlinelength = config.get('emailmaxlinelength')
2291        if emailmaxlinelength is not None:
2292            kw['emailmaxlinelength'] = int(emailmaxlinelength)
2293
2294        super(ConfigFilterLinesEnvironmentMixin, self).__init__(
2295            config=config, **kw
2296            )
2297
2298
2299class MaxlinesEnvironmentMixin(Environment):
2300    """Limit the email body to a specified number of lines."""
2301
2302    def __init__(self, emailmaxlines, **kw):
2303        super(MaxlinesEnvironmentMixin, self).__init__(**kw)
2304        self.__emailmaxlines = emailmaxlines
2305
2306    def filter_body(self, lines):
2307        lines = super(MaxlinesEnvironmentMixin, self).filter_body(lines)
2308        if self.__emailmaxlines:
2309            lines = limit_lines(lines, self.__emailmaxlines)
2310        return lines
2311
2312
2313class ConfigMaxlinesEnvironmentMixin(
2314        ConfigEnvironmentMixin,
2315        MaxlinesEnvironmentMixin,
2316        ):
2317    """Limit the email body to the number of lines specified in config."""
2318
2319    def __init__(self, config, **kw):
2320        emailmaxlines = int(config.get('emailmaxlines', default='0'))
2321        super(ConfigMaxlinesEnvironmentMixin, self).__init__(
2322            config=config,
2323            emailmaxlines=emailmaxlines,
2324            **kw
2325            )
2326
2327
2328class FQDNEnvironmentMixin(Environment):
2329    """A mixin that sets the host's FQDN to its constructor argument."""
2330
2331    def __init__(self, fqdn, **kw):
2332        super(FQDNEnvironmentMixin, self).__init__(**kw)
2333        self.COMPUTED_KEYS += ['fqdn']
2334        self.__fqdn = fqdn
2335
2336    def get_fqdn(self):
2337        """Return the fully-qualified domain name for this host.
2338
2339        Return None if it is unavailable or unwanted."""
2340
2341        return self.__fqdn
2342
2343
2344class ConfigFQDNEnvironmentMixin(
2345        ConfigEnvironmentMixin,
2346        FQDNEnvironmentMixin,
2347        ):
2348    """Read the FQDN from the config."""
2349
2350    def __init__(self, config, **kw):
2351        fqdn = config.get('fqdn')
2352        super(ConfigFQDNEnvironmentMixin, self).__init__(
2353            config=config,
2354            fqdn=fqdn,
2355            **kw
2356            )
2357
2358
2359class ComputeFQDNEnvironmentMixin(FQDNEnvironmentMixin):
2360    """Get the FQDN by calling socket.getfqdn()."""
2361
2362    def __init__(self, **kw):
2363        super(ComputeFQDNEnvironmentMixin, self).__init__(
2364            fqdn=socket.getfqdn(),
2365            **kw
2366            )
2367
2368
2369class PusherDomainEnvironmentMixin(ConfigEnvironmentMixin):
2370    """Deduce pusher_email from pusher by appending an emaildomain."""
2371
2372    def __init__(self, **kw):
2373        super(PusherDomainEnvironmentMixin, self).__init__(**kw)
2374        self.__emaildomain = self.config.get('emaildomain')
2375
2376    def get_pusher_email(self):
2377        if self.__emaildomain:
2378            # Derive the pusher's full email address in the default way:
2379            return '%s@%s' % (self.get_pusher(), self.__emaildomain)
2380        else:
2381            return super(PusherDomainEnvironmentMixin, self).get_pusher_email()
2382
2383
2384class StaticRecipientsEnvironmentMixin(Environment):
2385    """Set recipients statically based on constructor parameters."""
2386
2387    def __init__(
2388            self,
2389            refchange_recipients, announce_recipients, revision_recipients, scancommitforcc,
2390            **kw
2391            ):
2392        super(StaticRecipientsEnvironmentMixin, self).__init__(**kw)
2393
2394        # The recipients for various types of notification emails, as
2395        # RFC 2822 email addresses separated by commas (or the empty
2396        # string if no recipients are configured).  Although there is
2397        # a mechanism to choose the recipient lists based on on the
2398        # actual *contents* of the change being reported, we only
2399        # choose based on the *type* of the change.  Therefore we can
2400        # compute them once and for all:
2401        if not (refchange_recipients
2402                or announce_recipients
2403                or revision_recipients
2404                or scancommitforcc):
2405            raise ConfigurationException('No email recipients configured!')
2406        self.__refchange_recipients = refchange_recipients
2407        self.__announce_recipients = announce_recipients
2408        self.__revision_recipients = revision_recipients
2409
2410    def get_refchange_recipients(self, refchange):
2411        return self.__refchange_recipients
2412
2413    def get_announce_recipients(self, annotated_tag_change):
2414        return self.__announce_recipients
2415
2416    def get_revision_recipients(self, revision):
2417        return self.__revision_recipients
2418
2419
2420class ConfigRecipientsEnvironmentMixin(
2421        ConfigEnvironmentMixin,
2422        StaticRecipientsEnvironmentMixin
2423        ):
2424    """Determine recipients statically based on config."""
2425
2426    def __init__(self, config, **kw):
2427        super(ConfigRecipientsEnvironmentMixin, self).__init__(
2428            config=config,
2429            refchange_recipients=self._get_recipients(
2430                config, 'refchangelist', 'mailinglist',
2431                ),
2432            announce_recipients=self._get_recipients(
2433                config, 'announcelist', 'refchangelist', 'mailinglist',
2434                ),
2435            revision_recipients=self._get_recipients(
2436                config, 'commitlist', 'mailinglist',
2437                ),
2438            scancommitforcc=config.get('scancommitforcc'),
2439            **kw
2440            )
2441
2442    def _get_recipients(self, config, *names):
2443        """Return the recipients for a particular type of message.
2444
2445        Return the list of email addresses to which a particular type
2446        of notification email should be sent, by looking at the config
2447        value for "multimailhook.$name" for each of names.  Use the
2448        value from the first name that is configured.  The return
2449        value is a (possibly empty) string containing RFC 2822 email
2450        addresses separated by commas.  If no configuration could be
2451        found, raise a ConfigurationException."""
2452
2453        for name in names:
2454            retval = config.get_recipients(name)
2455            if retval is not None:
2456                return retval
2457        else:
2458            return ''
2459
2460
2461class ProjectdescEnvironmentMixin(Environment):
2462    """Make a "projectdesc" value available for templates.
2463
2464    By default, it is set to the first line of $GIT_DIR/description
2465    (if that file is present and appears to be set meaningfully)."""
2466
2467    def __init__(self, **kw):
2468        super(ProjectdescEnvironmentMixin, self).__init__(**kw)
2469        self.COMPUTED_KEYS += ['projectdesc']
2470
2471    def get_projectdesc(self):
2472        """Return a one-line descripition of the project."""
2473
2474        git_dir = get_git_dir()
2475        try:
2476            projectdesc = open(os.path.join(git_dir, 'description')).readline().strip()
2477            if projectdesc and not projectdesc.startswith('Unnamed repository'):
2478                return projectdesc
2479        except IOError:
2480            pass
2481
2482        return 'UNNAMED PROJECT'
2483
2484
2485class GenericEnvironmentMixin(Environment):
2486    def get_pusher(self):
2487        return self.osenv.get('USER', self.osenv.get('USERNAME', 'unknown user'))
2488
2489
2490class GenericEnvironment(
2491        ProjectdescEnvironmentMixin,
2492        ConfigMaxlinesEnvironmentMixin,
2493        ComputeFQDNEnvironmentMixin,
2494        ConfigFilterLinesEnvironmentMixin,
2495        ConfigRecipientsEnvironmentMixin,
2496        PusherDomainEnvironmentMixin,
2497        ConfigOptionsEnvironmentMixin,
2498        GenericEnvironmentMixin,
2499        Environment,
2500        ):
2501    pass
2502
2503
2504class GitoliteEnvironmentMixin(Environment):
2505    def get_repo_shortname(self):
2506        # The gitolite environment variable $GL_REPO is a pretty good
2507        # repo_shortname (though it's probably not as good as a value
2508        # the user might have explicitly put in his config).
2509        return (
2510            self.osenv.get('GL_REPO', None)
2511            or super(GitoliteEnvironmentMixin, self).get_repo_shortname()
2512            )
2513
2514    def get_pusher(self):
2515        return self.osenv.get('GL_USER', 'unknown user')
2516
2517    def get_fromaddr(self):
2518        GL_USER = self.osenv.get('GL_USER')
2519        if GL_USER is not None:
2520            # Find the path to gitolite.conf.  Note that gitolite v3
2521            # did away with the GL_ADMINDIR and GL_CONF environment
2522            # variables (they are now hard-coded).
2523            GL_ADMINDIR = self.osenv.get(
2524                'GL_ADMINDIR',
2525                os.path.expanduser(os.path.join('~', '.gitolite')))
2526            GL_CONF = self.osenv.get(
2527                'GL_CONF',
2528                os.path.join(GL_ADMINDIR, 'conf', 'gitolite.conf'))
2529            if os.path.isfile(GL_CONF):
2530                f = open(GL_CONF, 'rU')
2531                try:
2532                    in_user_emails_section = False
2533                    re_template = r'^\s*#\s*{}\s*$'
2534                    re_begin, re_user, re_end = (
2535                        re.compile(re_template.format(x))
2536                        for x in (
2537                            r'BEGIN\s+USER\s+EMAILS',
2538                            re.escape(GL_USER) + r'\s+(.*)',
2539                            r'END\s+USER\s+EMAILS',
2540                            ))
2541                    for l in f:
2542                        l = l.rstrip('\n')
2543                        if not in_user_emails_section:
2544                            if re_begin.match(l):
2545                                in_user_emails_section = True
2546                            continue
2547                        if re_end.match(l):
2548                            break
2549                        m = re_user.match(l)
2550                        if m:
2551                            return m.group(1)
2552                finally:
2553                    f.close()
2554        return super(GitoliteEnvironmentMixin, self).get_fromaddr()
2555
2556
2557class IncrementalDateTime(object):
2558    """Simple wrapper to give incremental date/times.
2559
2560    Each call will result in a date/time a second later than the
2561    previous call.  This can be used to falsify email headers, to
2562    increase the likelihood that email clients sort the emails
2563    correctly."""
2564
2565    def __init__(self):
2566        self.time = time.time()
2567
2568    def next(self):
2569        formatted = formatdate(self.time, True)
2570        self.time += 1
2571        return formatted
2572
2573
2574class GitoliteEnvironment(
2575        ProjectdescEnvironmentMixin,
2576        ConfigMaxlinesEnvironmentMixin,
2577        ComputeFQDNEnvironmentMixin,
2578        ConfigFilterLinesEnvironmentMixin,
2579        ConfigRecipientsEnvironmentMixin,
2580        PusherDomainEnvironmentMixin,
2581        ConfigOptionsEnvironmentMixin,
2582        GitoliteEnvironmentMixin,
2583        Environment,
2584        ):
2585    pass
2586
2587
2588class Push(object):
2589    """Represent an entire push (i.e., a group of ReferenceChanges).
2590
2591    It is easy to figure out what commits were added to a *branch* by
2592    a Reference change:
2593
2594        git rev-list change.old..change.new
2595
2596    or removed from a *branch*:
2597
2598        git rev-list change.new..change.old
2599
2600    But it is not quite so trivial to determine which entirely new
2601    commits were added to the *repository* by a push and which old
2602    commits were discarded by a push.  A big part of the job of this
2603    class is to figure out these things, and to make sure that new
2604    commits are only detailed once even if they were added to multiple
2605    references.
2606
2607    The first step is to determine the "other" references--those
2608    unaffected by the current push.  They are computed by listing all
2609    references then removing any affected by this push.  The results
2610    are stored in Push._other_ref_sha1s.
2611
2612    The commits contained in the repository before this push were
2613
2614        git rev-list other1 other2 other3 ... change1.old change2.old ...
2615
2616    Where "changeN.old" is the old value of one of the references
2617    affected by this push.
2618
2619    The commits contained in the repository after this push are
2620
2621        git rev-list other1 other2 other3 ... change1.new change2.new ...
2622
2623    The commits added by this push are the difference between these
2624    two sets, which can be written
2625
2626        git rev-list \
2627            ^other1 ^other2 ... \
2628            ^change1.old ^change2.old ... \
2629            change1.new change2.new ...
2630
2631    The commits removed by this push can be computed by
2632
2633        git rev-list \
2634            ^other1 ^other2 ... \
2635            ^change1.new ^change2.new ... \
2636            change1.old change2.old ...
2637
2638    The last point is that it is possible that other pushes are
2639    occurring simultaneously to this one, so reference values can
2640    change at any time.  It is impossible to eliminate all race
2641    conditions, but we reduce the window of time during which problems
2642    can occur by translating reference names to SHA1s as soon as
2643    possible and working with SHA1s thereafter (because SHA1s are
2644    immutable)."""
2645
2646    # A map {(changeclass, changetype): integer} specifying the order
2647    # that reference changes will be processed if multiple reference
2648    # changes are included in a single push.  The order is significant
2649    # mostly because new commit notifications are threaded together
2650    # with the first reference change that includes the commit.  The
2651    # following order thus causes commits to be grouped with branch
2652    # changes (as opposed to tag changes) if possible.
2653    SORT_ORDER = dict(
2654        (value, i) for (i, value) in enumerate([
2655            (BranchChange, 'update'),
2656            (BranchChange, 'create'),
2657            (AnnotatedTagChange, 'update'),
2658            (AnnotatedTagChange, 'create'),
2659            (NonAnnotatedTagChange, 'update'),
2660            (NonAnnotatedTagChange, 'create'),
2661            (BranchChange, 'delete'),
2662            (AnnotatedTagChange, 'delete'),
2663            (NonAnnotatedTagChange, 'delete'),
2664            (OtherReferenceChange, 'update'),
2665            (OtherReferenceChange, 'create'),
2666            (OtherReferenceChange, 'delete'),
2667            ])
2668        )
2669
2670    def __init__(self, changes, ignore_other_refs=False):
2671        self.changes = sorted(changes, key=self._sort_key)
2672        self.__other_ref_sha1s = None
2673        self.__cached_commits_spec = {}
2674
2675        if ignore_other_refs:
2676            self.__other_ref_sha1s = set()
2677
2678    @classmethod
2679    def _sort_key(klass, change):
2680        return (klass.SORT_ORDER[change.__class__, change.change_type], change.refname,)
2681
2682    @property
2683    def _other_ref_sha1s(self):
2684        """The GitObjects referred to by references unaffected by this push.
2685        """
2686        if self.__other_ref_sha1s is None:
2687            # The refnames being changed by this push:
2688            updated_refs = set(
2689                change.refname
2690                for change in self.changes
2691                )
2692
2693            # The SHA-1s of commits referred to by all references in this
2694            # repository *except* updated_refs:
2695            sha1s = set()
2696            fmt = (
2697                '%(objectname) %(objecttype) %(refname)\n'
2698                '%(*objectname) %(*objecttype) %(refname)'
2699                )
2700            for line in read_git_lines(
2701                    ['for-each-ref', '--format=%s' % (fmt,)]):
2702                (sha1, type, name) = line.split(' ', 2)
2703                if sha1 and type == 'commit' and name not in updated_refs:
2704                    sha1s.add(sha1)
2705
2706            self.__other_ref_sha1s = sha1s
2707
2708        return self.__other_ref_sha1s
2709
2710    def _get_commits_spec_incl(self, new_or_old, reference_change=None):
2711        """Get new or old SHA-1 from one or each of the changed refs.
2712
2713        Return a list of SHA-1 commit identifier strings suitable as
2714        arguments to 'git rev-list' (or 'git log' or ...).  The
2715        returned identifiers are either the old or new values from one
2716        or all of the changed references, depending on the values of
2717        new_or_old and reference_change.
2718
2719        new_or_old is either the string 'new' or the string 'old'.  If
2720        'new', the returned SHA-1 identifiers are the new values from
2721        each changed reference.  If 'old', the SHA-1 identifiers are
2722        the old values from each changed reference.
2723
2724        If reference_change is specified and not None, only the new or
2725        old reference from the specified reference is included in the
2726        return value.
2727
2728        This function returns None if there are no matching revisions
2729        (e.g., because a branch was deleted and new_or_old is 'new').
2730        """
2731
2732        if not reference_change:
2733            incl_spec = sorted(
2734                getattr(change, new_or_old).sha1
2735                for change in self.changes
2736                if getattr(change, new_or_old)
2737                )
2738            if not incl_spec:
2739                incl_spec = None
2740        elif not getattr(reference_change, new_or_old).commit_sha1:
2741            incl_spec = None
2742        else:
2743            incl_spec = [getattr(reference_change, new_or_old).commit_sha1]
2744        return incl_spec
2745
2746    def _get_commits_spec_excl(self, new_or_old):
2747        """Get exclusion revisions for determining new or discarded commits.
2748
2749        Return a list of strings suitable as arguments to 'git
2750        rev-list' (or 'git log' or ...) that will exclude all
2751        commits that, depending on the value of new_or_old, were
2752        either previously in the repository (useful for determining
2753        which commits are new to the repository) or currently in the
2754        repository (useful for determining which commits were
2755        discarded from the repository).
2756
2757        new_or_old is either the string 'new' or the string 'old'.  If
2758        'new', the commits to be excluded are those that were in the
2759        repository before the push.  If 'old', the commits to be
2760        excluded are those that are currently in the repository.  """
2761
2762        old_or_new = {'old': 'new', 'new': 'old'}[new_or_old]
2763        excl_revs = self._other_ref_sha1s.union(
2764            getattr(change, old_or_new).sha1
2765            for change in self.changes
2766            if getattr(change, old_or_new).type in ['commit', 'tag']
2767            )
2768        return ['^' + sha1 for sha1 in sorted(excl_revs)]
2769
2770    def get_commits_spec(self, new_or_old, reference_change=None):
2771        """Get rev-list arguments for added or discarded commits.
2772
2773        Return a list of strings suitable as arguments to 'git
2774        rev-list' (or 'git log' or ...) that select those commits
2775        that, depending on the value of new_or_old, are either new to
2776        the repository or were discarded from the repository.
2777
2778        new_or_old is either the string 'new' or the string 'old'.  If
2779        'new', the returned list is used to select commits that are
2780        new to the repository.  If 'old', the returned value is used
2781        to select the commits that have been discarded from the
2782        repository.
2783
2784        If reference_change is specified and not None, the new or
2785        discarded commits are limited to those that are reachable from
2786        the new or old value of the specified reference.
2787
2788        This function returns None if there are no added (or discarded)
2789        revisions.
2790        """
2791        key = (new_or_old, reference_change)
2792        if key not in self.__cached_commits_spec:
2793            ret = self._get_commits_spec_incl(new_or_old, reference_change)
2794            if ret is not None:
2795                ret.extend(self._get_commits_spec_excl(new_or_old))
2796            self.__cached_commits_spec[key] = ret
2797        return self.__cached_commits_spec[key]
2798
2799    def get_new_commits(self, reference_change=None):
2800        """Return a list of commits added by this push.
2801
2802        Return a list of the object names of commits that were added
2803        by the part of this push represented by reference_change.  If
2804        reference_change is None, then return a list of *all* commits
2805        added by this push."""
2806
2807        spec = self.get_commits_spec('new', reference_change)
2808        return git_rev_list(spec)
2809
2810    def get_discarded_commits(self, reference_change):
2811        """Return a list of commits discarded by this push.
2812
2813        Return a list of the object names of commits that were
2814        entirely discarded from the repository by the part of this
2815        push represented by reference_change."""
2816
2817        spec = self.get_commits_spec('old', reference_change)
2818        return git_rev_list(spec)
2819
2820    def send_emails(self, mailer, body_filter=None):
2821        """Use send all of the notification emails needed for this push.
2822
2823        Use send all of the notification emails (including reference
2824        change emails and commit emails) needed for this push.  Send
2825        the emails using mailer.  If body_filter is not None, then use
2826        it to filter the lines that are intended for the email
2827        body."""
2828
2829        # The sha1s of commits that were introduced by this push.
2830        # They will be removed from this set as they are processed, to
2831        # guarantee that one (and only one) email is generated for
2832        # each new commit.
2833        unhandled_sha1s = set(self.get_new_commits())
2834        send_date = IncrementalDateTime()
2835        for change in self.changes:
2836            sha1s = []
2837            for sha1 in reversed(list(self.get_new_commits(change))):
2838                if sha1 in unhandled_sha1s:
2839                    sha1s.append(sha1)
2840                    unhandled_sha1s.remove(sha1)
2841
2842            # Check if we've got anyone to send to
2843            if not change.recipients:
2844                change.environment.log_warning(
2845                    '*** no recipients configured so no email will be sent\n'
2846                    '*** for %r update %s->%s\n'
2847                    % (change.refname, change.old.sha1, change.new.sha1,)
2848                    )
2849            else:
2850                if not change.environment.quiet:
2851                    change.environment.log_msg(
2852                        'Sending notification emails to: %s\n' % (change.recipients,))
2853                extra_values = {'send_date': send_date.next()}
2854
2855                rev = change.send_single_combined_email(sha1s)
2856                if rev:
2857                    mailer.send(
2858                        change.generate_combined_email(self, rev, body_filter, extra_values),
2859                        rev.recipients,
2860                        )
2861                    # This change is now fully handled; no need to handle
2862                    # individual revisions any further.
2863                    continue
2864                else:
2865                    mailer.send(
2866                        change.generate_email(self, body_filter, extra_values),
2867                        change.recipients,
2868                        )
2869
2870            max_emails = change.environment.maxcommitemails
2871            if max_emails and len(sha1s) > max_emails:
2872                change.environment.log_warning(
2873                    '*** Too many new commits (%d), not sending commit emails.\n' % len(sha1s)
2874                    + '*** Try setting multimailhook.maxCommitEmails to a greater value\n'
2875                    + '*** Currently, multimailhook.maxCommitEmails=%d\n' % max_emails
2876                    )
2877                return
2878
2879            for (num, sha1) in enumerate(sha1s):
2880                rev = Revision(change, GitObject(sha1), num=num + 1, tot=len(sha1s))
2881                if not rev.recipients and rev.cc_recipients:
2882                    change.environment.log_msg('*** Replacing Cc: with To:\n')
2883                    rev.recipients = rev.cc_recipients
2884                    rev.cc_recipients = None
2885                if rev.recipients:
2886                    extra_values = {'send_date': send_date.next()}
2887                    mailer.send(
2888                        rev.generate_email(self, body_filter, extra_values),
2889                        rev.recipients,
2890                        )
2891
2892        # Consistency check:
2893        if unhandled_sha1s:
2894            change.environment.log_error(
2895                'ERROR: No emails were sent for the following new commits:\n'
2896                '    %s\n'
2897                % ('\n    '.join(sorted(unhandled_sha1s)),)
2898                )
2899
2900
2901def run_as_post_receive_hook(environment, mailer):
2902    changes = []
2903    for line in sys.stdin:
2904        (oldrev, newrev, refname) = line.strip().split(' ', 2)
2905        changes.append(
2906            ReferenceChange.create(environment, oldrev, newrev, refname)
2907            )
2908    push = Push(changes)
2909    push.send_emails(mailer, body_filter=environment.filter_body)
2910
2911
2912def run_as_update_hook(environment, mailer, refname, oldrev, newrev, force_send=False):
2913    changes = [
2914        ReferenceChange.create(
2915            environment,
2916            read_git_output(['rev-parse', '--verify', oldrev]),
2917            read_git_output(['rev-parse', '--verify', newrev]),
2918            refname,
2919            ),
2920        ]
2921    push = Push(changes, force_send)
2922    push.send_emails(mailer, body_filter=environment.filter_body)
2923
2924
2925def choose_mailer(config, environment):
2926    mailer = config.get('mailer', default='sendmail')
2927
2928    if mailer == 'smtp':
2929        smtpserver = config.get('smtpserver', default='localhost')
2930        smtpservertimeout = float(config.get('smtpservertimeout', default=10.0))
2931        smtpserverdebuglevel = int(config.get('smtpserverdebuglevel', default=0))
2932        smtpencryption = config.get('smtpencryption', default='none')
2933        smtpuser = config.get('smtpuser', default='')
2934        smtppass = config.get('smtppass', default='')
2935        mailer = SMTPMailer(
2936            envelopesender=(environment.get_sender() or environment.get_fromaddr()),
2937            smtpserver=smtpserver, smtpservertimeout=smtpservertimeout,
2938            smtpserverdebuglevel=smtpserverdebuglevel,
2939            smtpencryption=smtpencryption,
2940            smtpuser=smtpuser,
2941            smtppass=smtppass,
2942            )
2943    elif mailer == 'sendmail':
2944        command = config.get('sendmailcommand')
2945        if command:
2946            command = shlex.split(command)
2947        mailer = SendMailer(command=command, envelopesender=environment.get_sender())
2948    else:
2949        environment.log_error(
2950            'fatal: multimailhook.mailer is set to an incorrect value: "%s"\n' % mailer
2951            + 'please use one of "smtp" or "sendmail".\n'
2952            )
2953        sys.exit(1)
2954    return mailer
2955
2956
2957KNOWN_ENVIRONMENTS = {
2958    'generic': GenericEnvironmentMixin,
2959    'gitolite': GitoliteEnvironmentMixin,
2960    }
2961
2962
2963def choose_environment(config, osenv=None, env=None, recipients=None):
2964    if not osenv:
2965        osenv = os.environ
2966
2967    environment_mixins = [
2968        ProjectdescEnvironmentMixin,
2969        ConfigMaxlinesEnvironmentMixin,
2970        ComputeFQDNEnvironmentMixin,
2971        ConfigFilterLinesEnvironmentMixin,
2972        PusherDomainEnvironmentMixin,
2973        ConfigOptionsEnvironmentMixin,
2974        ]
2975    environment_kw = {
2976        'osenv': osenv,
2977        'config': config,
2978        }
2979
2980    if not env:
2981        env = config.get('environment')
2982
2983    if not env:
2984        if 'GL_USER' in osenv and 'GL_REPO' in osenv:
2985            env = 'gitolite'
2986        else:
2987            env = 'generic'
2988
2989    environment_mixins.append(KNOWN_ENVIRONMENTS[env])
2990
2991    if recipients:
2992        environment_mixins.insert(0, StaticRecipientsEnvironmentMixin)
2993        environment_kw['refchange_recipients'] = recipients
2994        environment_kw['announce_recipients'] = recipients
2995        environment_kw['revision_recipients'] = recipients
2996        environment_kw['scancommitforcc'] = config.get('scancommitforcc')
2997    else:
2998        environment_mixins.insert(0, ConfigRecipientsEnvironmentMixin)
2999
3000    environment_klass = type(
3001        'EffectiveEnvironment',
3002        tuple(environment_mixins) + (Environment,),
3003        {},
3004        )
3005    return environment_klass(**environment_kw)
3006
3007
3008def main(args):
3009    parser = optparse.OptionParser(
3010        description=__doc__,
3011        usage='%prog [OPTIONS]\n   or: %prog [OPTIONS] REFNAME OLDREV NEWREV',
3012        )
3013
3014    parser.add_option(
3015        '--environment', '--env', action='store', type='choice',
3016        choices=['generic', 'gitolite'], default=None,
3017        help=(
3018            'Choose type of environment is in use.  Default is taken from '
3019            'multimailhook.environment if set; otherwise "generic".'
3020            ),
3021        )
3022    parser.add_option(
3023        '--stdout', action='store_true', default=False,
3024        help='Output emails to stdout rather than sending them.',
3025        )
3026    parser.add_option(
3027        '--recipients', action='store', default=None,
3028        help='Set list of email recipients for all types of emails.',
3029        )
3030    parser.add_option(
3031        '--show-env', action='store_true', default=False,
3032        help=(
3033            'Write to stderr the values determined for the environment '
3034            '(intended for debugging purposes).'
3035            ),
3036        )
3037    parser.add_option(
3038        '--force-send', action='store_true', default=False,
3039        help=(
3040            'Force sending refchange email when using as an update hook. '
3041            'This is useful to work around the unreliable new commits '
3042            'detection in this mode.'
3043            ),
3044        )
3045
3046    (options, args) = parser.parse_args(args)
3047
3048    config = Config('multimailhook')
3049
3050    try:
3051        environment = choose_environment(
3052            config, osenv=os.environ,
3053            env=options.environment,
3054            recipients=options.recipients,
3055            )
3056
3057        if options.show_env:
3058            sys.stderr.write('Environment values:\n')
3059            for (k, v) in sorted(environment.get_values().items()):
3060                sys.stderr.write('    %s : %r\n' % (k, v))
3061            sys.stderr.write('\n')
3062
3063        if options.stdout or environment.stdout:
3064            mailer = OutputMailer(sys.stdout)
3065        else:
3066            mailer = choose_mailer(config, environment)
3067
3068        # Dual mode: if arguments were specified on the command line, run
3069        # like an update hook; otherwise, run as a post-receive hook.
3070        if args:
3071            if len(args) != 3:
3072                parser.error('Need zero or three non-option arguments')
3073            (refname, oldrev, newrev) = args
3074            run_as_update_hook(environment, mailer, refname, oldrev, newrev, options.force_send)
3075        else:
3076            run_as_post_receive_hook(environment, mailer)
3077    except ConfigurationException, e:
3078        sys.exit(str(e))
3079
3080
3081if __name__ == '__main__':
3082    main(sys.argv[1:])