tools/hook-scripts/mailer/mailer.conf.example - subversion - Git at Google


            
            #

            
            # mailer.conf: example configuration file for mailer.py

            
            #

            
            # $Id$


            [general]


            # The [general].diff option is now DEPRECATED.

            
            # Instead use [defaults].diff .


            #

            
            # One delivery method must be chosen. mailer.py will prefer using the

            
            # "mail_command" option. If that option is empty or commented out,

            
            # then it checks whether the "smtp_hostname" option has been

            
            # specified. If neither option is set, then the commit message is

            
            # delivered to stdout.

            
            #


            # This command will be invoked with destination addresses on the command

            
            # line, and the message piped into it.

            
            #mail_command = /usr/sbin/sendmail


            # This option specifies the hostname for delivery via SMTP

            
            #smtp_hostname = localhost


            # Username and password for SMTP servers requiring authorisation

            
            #smtp_username = example

            
            #smtp_password = example


            # --------------------------------------------------------------------------


            #

            
            # CONFIGURATION GROUPS

            
            #

            
            # Any section other than [general] or [defaults] are considered to be

            
            # user-defined groups which override values in the [defaults] section.

            
            # These groups are selected using the following two options:

            
            #

            
            #   for_repos

            
            #   for_paths

            
            #

            
            # Both options specify a regular expression. The former is matched against

            
            # the absolute path to the repository the mailer is operating against. The

            
            # second is matched against *every* path (files and dirs) that was modified

            
            # during the commit.

            
            #

            
            # The options specified in the [defaults] section are always selected. The

            
            # presence of a non-matching for_repos has no relevance. Note that you may

            
            # still use a for_repos value to extract useful information (more on this

            
            # later). Any user-defined groups without a for_repos, or which contains

            
            # a matching for_repos, will be selected for potential use.

            
            #

            
            # The subset of user-defined groups identified by the repository are further

            
            # refined based on the for_paths option. A group is selected if at least

            
            # one path(*) in the commit matches the for_paths regular expression. Note

            
            # that the paths are relative to the root of the repository and do not

            
            # have a leading slash.

            
            #

            
            # (*) Actually, each path will select just one group. Thus, it is possible

            
            # that one group will match against all paths, while another group matches

            
            # none of the paths, even though its for_paths would have selected some of

            
            # the paths in the commit.

            
            #

            
            # Groups are matched in no particular order. Do not depend upon their

            
            # order within this configuration file. The values from [defaults] will

            
            # be used if no group is matched or an option in a group does not override

            
            # the corresponding value from [defaults].

            
            #

            
            # Generally, a commit email is generated for each group that has been

            
            # selected. The script will try to minimize mails, so it may be possible

            
            # that a single message will be generated to multiple recipients. In

            
            # addition, it is possible for multiple messages per group to be generated,

            
            # based on the various substitutions that are performed (see the following

            
            # section).

            
            #

            
            #

            
            # SUBSTITUTIONS

            
            #

            
            # The regular expressions can use the "named group" syntax to extract

            
            # interesting pieces of the repository or commit path. These named values

            
            # can then be substituted in the option values during mail generation.

            
            #

            
            # For example, let's say that you have a repository with a top-level

            
            # directory named "clients", with several client projects underneath:

            
            #

            
            #   REPOS/

            
            #     clients/

            
            #       gsvn/

            
            #       rapidsvn/

            
            #       winsvn/

            
            #

            
            # The client name can be extracted with a regular expression like:

            
            #

            
            #   for_paths = clients/(?P<client>[^/]*)($|/)

            
            #

            
            # The substitution is performed using Python's dict-based string

            
            # interpolation syntax:

            
            #

            
            #   to_addr = commits@%(client)s.tigris.org

            
            #

            
            # The %(NAME)s syntax will substitute whatever value for NAME was captured

            
            # in the for_repos and for_paths regular expressions. The set of names

            
            # available is obtained from the following set of regular expressions:

            
            #

            
            #   [defaults].for_repos    (if present)

            
            #   [GROUP].for_repos       (if present in the user-defined group "GROUP")

            
            #   [GROUP].for_paths       (if present in the user-defined group "GROUP")

            
            #

            
            # The names from the regexes later in the list override the earlier names.

            
            # If none of the groups match, but a for_paths is present in [defaults],

            
            # then its extracted names will be available.

            
            #

            
            # Note that each unique set of names for substitution will generate an

            
            # email. In the above example, if a commit modified files in all three

            
            # client subdirectories, then an email will be sent to all three commits@

            
            # mailing lists on tigris.org.

            
            #

            
            # The substitution variable "author" is provided by default, and is set

            
            # to the author name passed to mailer.py for revprop changes or the

            
            # author defined for a revision; if neither is available, then it is

            
            # set to "no_author". Thus, you might define a line like:

            
            #

            
            #   from_addr = %(author)s@example.com

            
            #

            
            #

            
            # SUMMARY

            
            #

            
            # While mailer.py will work to minimize the number of mail messages

            
            # generated, a single commit can potentially generate a large number

            
            # of variants of a commit message. The criteria for generating messages

            
            # is based on:

            
            #

            
            #   groups selected by for_repos

            
            #   groups selected by for_paths

            
            #   unique sets of parameters extracted by the above regular expressions

            
            #


            [defaults]


            # This is not passed to the shell, so do not use shell metacharacters.

            
            # The command is split around whitespace, so if you want to include

            
            # whitespace in the command, then ### something ###

            
            diff = /usr/bin/diff -u -L %(label_from)s -L %(label_to)s %(from)s %(to)s


            # The default prefix for the Subject: header for commits

            
            commit_subject_prefix =


            # The default prefix for the Subject: header for propchanges

            
            propchange_subject_prefix =


            # The default prefix for the Subject: header for locks

            
            lock_subject_prefix =


            # The default prefix for the Subject: header for unlocks

            
            unlock_subject_prefix =


            # The default From: address for messages.  If the from_addr is not

            
            # specified or it is specified but there is no text after the `=',

            
            # then the revision's author is used as the from address.  If the

            
            # revision author is not specified, such as when a commit is done

            
            # without requiring authentication and authorization, then the string

            
            # 'no_author' is used.  You can specify a default from_addr here and

            
            # if you want to have a particular for_repos group use the author as

            
            # the from address, you can use "from_addr =".

            
            from_addr = invalid@example.com


            # The default To: addresses for message.  One or more addresses,

            
            # separated by whitespace (no commas):

            
            to_addr = invalid@example.com


            # If this is set, then a Reply-To: will be inserted into the message

            
            reply_to =


            # When set to one or more of the valid options, the mailer will create

            
            # diffs for the corresponding types of changes in the repository.  If

            
            # no options are given, or if any invalid options are given, no diffs

            
            # will be created.  Note that the operation is always mentioned in the

            
            # message header, regardless of this option's value.

            
            #

            
            # Valid options: add copy modify delete

            
            generate_diffs = add copy modify


            # Diff URL construction.  For the configured diff URL types, the diff

            
            # section (which follows the message header) will include the URL

            
            # relevant to the change type, even if actual diff generation for that

            
            # change type is disabled (per the generate_diffs option).

            
            #

            
            # Available substitution variables are: path, base_path, rev, base_rev

            
            #diff_add_url =

            
            #diff_copy_url =

            
            #diff_modify_url = http://diffs.server.com/?p1=%(base_path)s&p2=%(path)s

            
            #diff_delete_url =


            # When set to "yes", the mailer will suppress the creation of a diff which

            
            # deletes all the lines in the file. If this is set to anything else, or

            
            # is simply commented out, then the diff will be inserted. Note that the

            
            # deletion is always mentioned in the message header, regardless of this

            
            # option's value.

            
            ### DEPRECATED (if generate_diffs is not empty, this option is ignored)

            
            suppress_deletes = yes


            # When set to "yes", the mailer will suppress the creation of a diff which

            
            # adds all the lines in the file. If this is set to anything else, or

            
            # is simply commented out, then the diff will be inserted. Note that the

            
            # addition is always mentioned in the message header, regardless of this

            
            # option's value.

            
            ### DEPRECATED (if generate_diffs is not empty, this option is ignored)

            
            #suppress_adds = yes


            # A revision is reported on if any of its changed paths match the

            
            # for_paths option.  If only some of the changed paths of a revision

            
            # match, this variable controls the behaviour for the non-matching

            
            # paths.  Possible values are:

            
            #

            
            #   yes:     (Default) Show in both summary and diffs.

            
            #   summary: Show the changed paths in the summary, but omit the diffs.

            
            #   no:      Show nothing more than a note saying "and changes in other areas"

            
            #

            
            show_nonmatching_paths = yes


            # Subject line length limit.  The generated subject line will be truncated

            
            # and terminated with "...", to remain within the specified maximum length.

            
            # Set to 0 to turn off.

            
            #truncate_subject = 200


            # --------------------------------------------------------------------------


            [maps]


            #

            
            # This section can be used define rewrite mappings for option values. It

            
            # is typically used for computing from/to addresses, but can actually be

            
            # used to remap values for any option in this file.

            
            #

            
            # The mappings are global for the entire configuration file. There is

            
            # no group-specific mapping capability. For each mapping that you want

            
            # to perform, you will provide the name of the option (e.g. from_addr)

            
            # and a specification of how to perform those mappings. These declarations

            
            # are made here in the [maps] section.

            
            #

            
            # When an option is accessed, the value is loaded from the configuration

            
            # file and all %(NAME)s substitutions are performed. The resulting value

            
            # is then passed through the map. If a map entry is not available for

            
            # the value, then it will be used unchanged.

            
            #

            
            # The format to declare a map is:

            
            #

            
            #   option_name_to_remap = mapping_specification

            
            #

            
            # At the moment, there is only one type of mapping specification:

            
            #

            
            #   mapping_specification = '[' sectionname ']'

            
            #

            
            # This will use the given section to map values. The option names in

            
            # the section are the input values, and the option values are the result.

            
            #


            #

            
            # EXAMPLE:

            
            #

            
            # We have two projects using two repositories. The name of the repos

            
            # does not easily map to their commit mailing lists, so we will use

            
            # a mapping to go from a project name (extracted from the repository

            
            # path) to their commit list. The committers also need a special

            
            # mapping to derive their email address from their repository username.

            
            #

            
            # [projects]

            
            # for_repos = .*/(?P<project>.*)

            
            # from_addr = %(author)s

            
            # to_addr = %(project)s

            
            #

            
            # [maps]

            
            # from_addr = [authors]

            
            # to_addr = [mailing-lists]

            
            #

            
            # [authors]

            
            # john = jconnor@example.com

            
            # sarah = sconnor@example.com

            
            #

            
            # [mailing-lists]

            
            # t600 = spottable-commits@example.com

            
            # tx = hotness-commits@example.com

            
            #


            # --------------------------------------------------------------------------


            #

            
            # [example-group]

            
            # # send notifications if any web pages are changed

            
            # for_paths = .*\.html

            
            # # set a custom prefix

            
            # commit_subject_prefix = [commit]

            
            # propchange_subject_prefix = [propchange]

            
            # # override the default, sending these elsewhere

            
            # to_addr = www-commits@example.com

            
            # # use the revision author as the from address

            
            # from_addr =

            
            # # use a custom diff program for this group

            
            # diff = /usr/bin/my-diff -u -L %(label_from)s -L %(label_to)s %(from)s %(to)s

            
            #

            
            # [another-example]

            
            # # commits to personal repositories should go to that person

            
            # for_repos = /home/(?P<who>[^/]*)/repos

            
            # to_addr = %(who)s@example.com

            
            #
	#
	# mailer.conf: example configuration file for mailer.py
	#
	# $Id$

	[general]

	# The [general].diff option is now DEPRECATED.
	# Instead use [defaults].diff .

	#
	# One delivery method must be chosen. mailer.py will prefer using the
	# "mail_command" option. If that option is empty or commented out,
	# then it checks whether the "smtp_hostname" option has been
	# specified. If neither option is set, then the commit message is
	# delivered to stdout.
	#

	# This command will be invoked with destination addresses on the command
	# line, and the message piped into it.
	#mail_command = /usr/sbin/sendmail

	# This option specifies the hostname for delivery via SMTP
	#smtp_hostname = localhost

	# Username and password for SMTP servers requiring authorisation
	#smtp_username = example
	#smtp_password = example

	# --------------------------------------------------------------------------

	#
	# CONFIGURATION GROUPS
	#
	# Any section other than [general] or [defaults] are considered to be
	# user-defined groups which override values in the [defaults] section.
	# These groups are selected using the following two options:
	#
	# for_repos
	# for_paths
	#
	# Both options specify a regular expression. The former is matched against
	# the absolute path to the repository the mailer is operating against. The
	# second is matched against every path (files and dirs) that was modified
	# during the commit.
	#
	# The options specified in the [defaults] section are always selected. The
	# presence of a non-matching for_repos has no relevance. Note that you may
	# still use a for_repos value to extract useful information (more on this
	# later). Any user-defined groups without a for_repos, or which contains
	# a matching for_repos, will be selected for potential use.
	#
	# The subset of user-defined groups identified by the repository are further
	# refined based on the for_paths option. A group is selected if at least
	# one path(*) in the commit matches the for_paths regular expression. Note
	# that the paths are relative to the root of the repository and do not
	# have a leading slash.
	#
	# (*) Actually, each path will select just one group. Thus, it is possible
	# that one group will match against all paths, while another group matches
	# none of the paths, even though its for_paths would have selected some of
	# the paths in the commit.
	#
	# Groups are matched in no particular order. Do not depend upon their
	# order within this configuration file. The values from [defaults] will
	# be used if no group is matched or an option in a group does not override
	# the corresponding value from [defaults].
	#
	# Generally, a commit email is generated for each group that has been
	# selected. The script will try to minimize mails, so it may be possible
	# that a single message will be generated to multiple recipients. In
	# addition, it is possible for multiple messages per group to be generated,
	# based on the various substitutions that are performed (see the following
	# section).
	#
	#
	# SUBSTITUTIONS
	#
	# The regular expressions can use the "named group" syntax to extract
	# interesting pieces of the repository or commit path. These named values
	# can then be substituted in the option values during mail generation.
	#
	# For example, let's say that you have a repository with a top-level
	# directory named "clients", with several client projects underneath:
	#
	# REPOS/
	# clients/
	# gsvn/
	# rapidsvn/
	# winsvn/
	#
	# The client name can be extracted with a regular expression like:
	#
	# for_paths = clients/(?P<client>[^/]*)($\|/)
	#
	# The substitution is performed using Python's dict-based string
	# interpolation syntax:
	#
	# to_addr = commits@%(client)s.tigris.org
	#
	# The %(NAME)s syntax will substitute whatever value for NAME was captured
	# in the for_repos and for_paths regular expressions. The set of names
	# available is obtained from the following set of regular expressions:
	#
	# [defaults].for_repos (if present)
	# [GROUP].for_repos (if present in the user-defined group "GROUP")
	# [GROUP].for_paths (if present in the user-defined group "GROUP")
	#
	# The names from the regexes later in the list override the earlier names.
	# If none of the groups match, but a for_paths is present in [defaults],
	# then its extracted names will be available.
	#
	# Note that each unique set of names for substitution will generate an
	# email. In the above example, if a commit modified files in all three
	# client subdirectories, then an email will be sent to all three commits@
	# mailing lists on tigris.org.
	#
	# The substitution variable "author" is provided by default, and is set
	# to the author name passed to mailer.py for revprop changes or the
	# author defined for a revision; if neither is available, then it is
	# set to "no_author". Thus, you might define a line like:
	#
	# from_addr = %(author)s@example.com
	#
	#
	# SUMMARY
	#
	# While mailer.py will work to minimize the number of mail messages
	# generated, a single commit can potentially generate a large number
	# of variants of a commit message. The criteria for generating messages
	# is based on:
	#
	# groups selected by for_repos
	# groups selected by for_paths
	# unique sets of parameters extracted by the above regular expressions
	#

	[defaults]

	# This is not passed to the shell, so do not use shell metacharacters.
	# The command is split around whitespace, so if you want to include
	# whitespace in the command, then ### something ###
	diff = /usr/bin/diff -u -L %(label_from)s -L %(label_to)s %(from)s %(to)s

	# The default prefix for the Subject: header for commits
	commit_subject_prefix =

	# The default prefix for the Subject: header for propchanges
	propchange_subject_prefix =

	# The default prefix for the Subject: header for locks
	lock_subject_prefix =

	# The default prefix for the Subject: header for unlocks
	unlock_subject_prefix =


	# The default From: address for messages. If the from_addr is not
	# specified or it is specified but there is no text after the `=',
	# then the revision's author is used as the from address. If the
	# revision author is not specified, such as when a commit is done
	# without requiring authentication and authorization, then the string
	# 'no_author' is used. You can specify a default from_addr here and
	# if you want to have a particular for_repos group use the author as
	# the from address, you can use "from_addr =".
	from_addr = invalid@example.com

	# The default To: addresses for message. One or more addresses,
	# separated by whitespace (no commas):
	to_addr = invalid@example.com

	# If this is set, then a Reply-To: will be inserted into the message
	reply_to =

	# When set to one or more of the valid options, the mailer will create
	# diffs for the corresponding types of changes in the repository. If
	# no options are given, or if any invalid options are given, no diffs
	# will be created. Note that the operation is always mentioned in the
	# message header, regardless of this option's value.
	#
	# Valid options: add copy modify delete
	generate_diffs = add copy modify

	# Diff URL construction. For the configured diff URL types, the diff
	# section (which follows the message header) will include the URL
	# relevant to the change type, even if actual diff generation for that
	# change type is disabled (per the generate_diffs option).
	#
	# Available substitution variables are: path, base_path, rev, base_rev
	#diff_add_url =
	#diff_copy_url =
	#diff_modify_url = http://diffs.server.com/?p1=%(base_path)s&p2=%(path)s
	#diff_delete_url =

	# When set to "yes", the mailer will suppress the creation of a diff which
	# deletes all the lines in the file. If this is set to anything else, or
	# is simply commented out, then the diff will be inserted. Note that the
	# deletion is always mentioned in the message header, regardless of this
	# option's value.
	### DEPRECATED (if generate_diffs is not empty, this option is ignored)
	suppress_deletes = yes

	# When set to "yes", the mailer will suppress the creation of a diff which
	# adds all the lines in the file. If this is set to anything else, or
	# is simply commented out, then the diff will be inserted. Note that the
	# addition is always mentioned in the message header, regardless of this
	# option's value.
	### DEPRECATED (if generate_diffs is not empty, this option is ignored)
	#suppress_adds = yes

	# A revision is reported on if any of its changed paths match the
	# for_paths option. If only some of the changed paths of a revision
	# match, this variable controls the behaviour for the non-matching
	# paths. Possible values are:
	#
	# yes: (Default) Show in both summary and diffs.
	# summary: Show the changed paths in the summary, but omit the diffs.
	# no: Show nothing more than a note saying "and changes in other areas"
	#
	show_nonmatching_paths = yes

	# Subject line length limit. The generated subject line will be truncated
	# and terminated with "...", to remain within the specified maximum length.
	# Set to 0 to turn off.
	#truncate_subject = 200

	# --------------------------------------------------------------------------

	[maps]

	#
	# This section can be used define rewrite mappings for option values. It
	# is typically used for computing from/to addresses, but can actually be
	# used to remap values for any option in this file.
	#
	# The mappings are global for the entire configuration file. There is
	# no group-specific mapping capability. For each mapping that you want
	# to perform, you will provide the name of the option (e.g. from_addr)
	# and a specification of how to perform those mappings. These declarations
	# are made here in the [maps] section.
	#
	# When an option is accessed, the value is loaded from the configuration
	# file and all %(NAME)s substitutions are performed. The resulting value
	# is then passed through the map. If a map entry is not available for
	# the value, then it will be used unchanged.
	#
	# The format to declare a map is:
	#
	# option_name_to_remap = mapping_specification
	#
	# At the moment, there is only one type of mapping specification:
	#
	# mapping_specification = '[' sectionname ']'
	#
	# This will use the given section to map values. The option names in
	# the section are the input values, and the option values are the result.
	#

	#
	# EXAMPLE:
	#
	# We have two projects using two repositories. The name of the repos
	# does not easily map to their commit mailing lists, so we will use
	# a mapping to go from a project name (extracted from the repository
	# path) to their commit list. The committers also need a special
	# mapping to derive their email address from their repository username.
	#
	# [projects]
	# for_repos = ./(?P<project>.)
	# from_addr = %(author)s
	# to_addr = %(project)s
	#
	# [maps]
	# from_addr = [authors]
	# to_addr = [mailing-lists]
	#
	# [authors]
	# john = jconnor@example.com
	# sarah = sconnor@example.com
	#
	# [mailing-lists]
	# t600 = spottable-commits@example.com
	# tx = hotness-commits@example.com
	#

	# --------------------------------------------------------------------------

	#
	# [example-group]
	# # send notifications if any web pages are changed
	# for_paths = .*\.html
	# # set a custom prefix
	# commit_subject_prefix = [commit]
	# propchange_subject_prefix = [propchange]
	# # override the default, sending these elsewhere
	# to_addr = www-commits@example.com
	# # use the revision author as the from address
	# from_addr =
	# # use a custom diff program for this group
	# diff = /usr/bin/my-diff -u -L %(label_from)s -L %(label_to)s %(from)s %(to)s
	#
	# [another-example]
	# # commits to personal repositories should go to that person
	# for_repos = /home/(?P<who>[^/]*)/repos
	# to_addr = %(who)s@example.com
	#