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

[general]

# 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

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

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

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

# The default prefix for the Subject: header
subject_prefix =

# The default From: and To: addresses for commit messages
from_addr = invalid@example.com
to_addr = invalid@example.com

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

# 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.
suppress_deletes = yes

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

#
# [example-group]
# # send notifications if any web pages are changed
# for_paths = .*\.html
# # set a custom prefix
# subject_prefix = [commit]
# # override the default, sending these elsewhere
# to_addr = www-commits@example.com
#
# [another-example]
# # commits to personal repositories should go to that person
# for_repos = /home/(?P<who>[^/]*)/repos
# to_addr = %(who)s@example.com
#