#
# 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 sections other than [general], [defaults], [maps] and sections
# referred to within [maps] are considered to be user-defined groups
# which override values in the [defaults] section.
# These groups are selected using the following three options:
#
#   for_repos
#   for_paths
#   search_logmsg
#
# Each option specifies a regular expression. for_repos is matched
# against the absolute path to the repository the mailer is operating
# against. for_paths 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.
#
# search_logmsg specifies a regular expression to match against the
# log message.  If the regular expression does not match the log
# message, the group is not matched; if the regular expression matches
# once, the group is used.  If there are multiple matches, each
# successful match generates another group-match (this is useful if
# "named groups" are used).  If search_logmsg is not used, no log
# message filtering is performed.
#
# 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.
#
# Further suppose you want to match bug-ids in log messages:
#
#   search_logmsg = (?P<bugid>(ProjA|ProjB)#\d)
#
# The bugids would be of the form ProjA#123 and ProjB#456.  In this
# case, each time the regular expression matches, another match group
# will be generated.  Thus, if you use:
#
#   commit_subject_prefix = %(bugid)s:
#
# Then, a log message such as "Fixes ProjA#123 and ProjB#234" would
# match both bug-ids, and two emails would be generated - one with
# subject "ProjA#123: <...>" and "ProjB#234: <...>".
#
# 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).
# NOTE: If you want to use a different character for separating the
#       addresses put it in front of the addresses included in square
#       brackets '[ ]'.
to_addr = invalid@example.com

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

# Specify which types of repository changes mailer.py will create
# diffs for. Valid options are any combination of
# 'add copy modify delete', or 'none' to never create diffs.
# If the generate_diffs option is empty, the selection is controlled
# by the deprecated options suppress_deletes and suppress_adds.
# Note that this only affects the display of diffs - all changes are
# mentioned in the summary of changed paths at the top of the message,
# regardless of this option's value.
# Meaning of the possible values:
# add:    generates diffs for all added paths
# copy:   generates diffs for all copied paths
#         which were not changed after copying
# modify: generates diffs for all modified paths, including paths that were
#         copied and modified afterwards (within the same commit)
# delete: generates diffs for all removed paths
generate_diffs = add copy modify

# Commit URL construction.  This adds a URL to the top of the message
# that can lead the reader to a Trac, ViewVC or other view of the
# commit as a whole.
#
# The available substitution variable is: rev
#commit_url = http://diffs.server.com/trac/software/changeset/%(rev)s

# 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.
#
# NOTES: - Avoid using map substitution names which differ only in case.
#          Unexpected results may occur.
#        - A colon ':' is also considered as separator between option and
#          value (keep this in mind when trying to map a file path under
#          windows).
#
# 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
#
# [issuetracker]
# search_logmsg = (?P<bugid>(?P<project>projecta|projectb|projectc)#\d+)
# # (or, use a mapping if the bug-id to email address is not this trivial)
# to_addr = %(project)s-tracker@example.com
# commit_subject_prefix = %(bugid)s:
# propchange_subject_prefix = %(bugid)s: