#
# mailer.conf: example configuration file for mailer.py
#
# $Id: mailer.conf.example 10012 2004-06-16 14:34:53Z cmpilato $

[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

# 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.
#
#
# 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 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 of the valid options, the mailer will create a diff
# for the appropriate type of change in the repository.  If this is
# empty or contains other words than the valid options 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 delete modify
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


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

#
# [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 =
#
# [another-example]
# # commits to personal repositories should go to that person
# for_repos = /home/(?P<who>[^/]*)/repos
# to_addr = %(who)s@example.com
#