Edit File: mailer.conf.example
# # mailer.conf: example configuration file for mailer.py # # $Id: mailer.conf.example 885511 2009-11-30 17:30:17Z julianfoad $ [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 # # The substitution variable "repos_basename" is provided, and is set to # the directory name of the repository. This can be useful to set # a custom subject that can be re-used in multiple repositories: # # commit_subject_prefix = [svn-%(repos_basename)s] # # For example if the repository is at /path/to/repo/project-x then # the subject of commit emails will be prefixed with [svn-project-x] # # # 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: