#
# 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 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

# 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
#