SVN::Notify(3pm)

📦

version 2.87 · 2 versions

2.87 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
2.87 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Name 💖

SVN::Notify — Subversion activity notification. That's the whole vibe bestie: your repo does stuff, this thing tells people about it. 💅

🌸 Synopsis 🌸

okay so there are two ways to pull up. First, the classic: drop it in post-commit:

svnnotify --repos-path "$1" --revision "$2" \
  --to developers@example.com [options]

svnnotify --repos-path "$1" --revision "$2" \
  --to-cx-regex i10n@example.com=I10N [options]

Or, if you're feeling custom, use the class inside your own script:

use SVN::Notify;

my $notifier = SVN::Notify->new(%params);
$notifier->prepare;
$notifier->execute;

🦋 Description 🦋

This class sends email messages about Subversion repository activity. There are a bunch of different modes supported, and SVN::Notify is fully subclassable if you wanna add new functionality — plus it's got comprehensive content filtering so you can easily mess with the format of its messages. 💖

By default, a list of all the files affected by the commit gets assembled and listed in a single message. There's an extra option that lets diffs be calculated for the changes and either appended to the message or added as an attachment. Go peek at the with_diff and attach_diff options below. 👀

✨ Usage ✨

To use SVN::Notify, just add a call to svnnotify in your Subversion repository's post-commit script. That script lives in the hooks directory at the root of the repository directory — check the docs in post-commit.tmpl for the deets.

Make sure you specify the complete path to svnnotify, and also to svnlook and sendmail in the options you pass to svnnotify, so everything actually executes properly. And if you specify any string options, be sure they're in the encoding specified by the --encoding option, or UTF-8 if you haven't specified --encoding. 🫶

🪟 Windows Usage 🪟

To get SVN::Notify working properly in a post-commit script on Windows, you must set the following environment variables, because they will likely not be present inside Apache:

PATH=C:\perl\bin
OS=Windows_NT
SystemRoot=C:\WINDOWS

See Windows Subversion + Apache + TortoiseSVN + SVN::Notify HOWTO http://svn.haxx.se/users/archive-2006-05/0593.shtml for more detailed info on getting SVN::Notify running on Windows. And if you have issues with asynchronous execution, try using HookStart.exe http://www.koders.com/csharp/fidE2724F44EF2D47F1C0FE76C538006435FA20051D.aspx to run svnnotify. 💀

👑 Class Interface 👑

🎀 Constructor 🎀

🌟 new

my $notifier = SVN::Notify->new(%params);

Constructs and returns a new SVN::Notify object. This object is basically a handle on the whole process of collecting meta data and content for the commit email and then sending it. So yeah, it takes a bunch of parameters that affect that process. 🫡

Every one of these parameters has a matching command-line option you can pass to svnnotify. The options have the same names as these parameters, but any underscores you see here should be swapped for dashes when you pass them to svnnotify. Most also have a matching single-character option. On Perl 5.8 and higher, if you pass parameters to new(), they must be decoded into Perl's internal form if they have any non-ASCII characters. 👑

Supported parameters:

💫 `repos_path`

svnnotify --repos-path "$PATH"
svnnotify -p "$PATH"

The path to the Subversion repository. This path gets passed as the first argument when Subversion executes post-commit, so you can literally just pass $1 here if you want. See the documentation in post-commit for details. Required. 🔥

💫 `revision`

svnnotify --revision "$REV"
svnnotify -r "$REV"

The revision number for the current commit. This one gets passed as the second argument when Subversion executes post-commit, so you can just pass $2 here if you like. See the documentation in post-commit for details. Required. 🔥

💫 `to`

svnnotify --to commiters@example.com
svnnotify -t commiters@example.com --to managers@example.com

The address (or addresses) to send the notification email to. You can use it multiple times to specify multiple addresses. This parameter is required unless either to_regex_map or to_email_map is specified. 💌

💫 `to_regex_map`

svnnotify --to-regex-map translate@example.com=L18N \
          -x legal@example.com=License

This parameter specifies a hash reference of email addresses to regular expression strings. SVN::Notify will compile those regex strings into regex objects, and then send notification messages if and only if the name of one or more of the paths affected by a commit matches the regular expression. This is a great way to have a notification email sent to a particular mail address (or comma-delimited list of addresses) only for certain parts of the subversion tree. This parameter is required unless to or to_email_map is specified. 🌈

The command-line options --to-regex_map and -x can be specified any number of times — once for each entry in the hash you want to pass to new(). The value you pass to the option must be in the form of the key and the value separated by an equal sign. Consult the Getopt::Long documentation for more info.

Here's an example, complements of Matt Doar, of how to use to_regex_map to do per-branch matching:

author=`svnlook author $REPOS -r $REV`

# The mail regexes should match all the top-level directories
/usr/bin/svnnotify --repos-path "$REPOS" --revision "$REV" \
-x eng-bar@example.com,${EXTRAS}="^Bar" \
-x eng-foo@example.com,${EXTRAS}="^trunk/Foo|^branches/Foo|^tags/Foo" \
-x $author@example.com="^users" --subject-cx

💫 `to_email_map`

svnnotify --to-email-map L18N=translate@example.com \
          --to-email-map License=legal@example.com

The inverse of to_regex_map: the regular expression is the hash key, and the email address or addresses are the value. 🌀

💫 `from`

svnnotify --from somewhere@example.com
svnnotify -f elsewhere@example.com

The email address to use in the From line of the email. If you don't specify it, SVN::Notify will use the username from the commit, as returned by svnlook info.

💫 `user_domain`

svnnotify --user-domain example.com
svnnotify -D example.net

A domain name to append to the username for the From header of the email. During a Subversion commit, the username returned by svnlook info is usually something like a Unix login name. SVN::Notify will use this username in the email From header unless the from parameter is specified. But if you want that username to take the form of a real email address, specify a domain name and SVN::Notify will append \@$domain_name to the username to create a real email address. Super useful if all your committers have an email address that corresponds to their username at the domain specified by the user_domain parameter. 💌

💫 `svnlook`

svnnotify --svnlook /path/to/svnlook
svnnotify -l /path/to/svnlook

The location of the svnlook executable. If you don't specify it, SVN::Notify will search through the directories in the $PATH environment variable, plus in /usr/local/bin and /usr/sbin, for an svnlook executable. Specify a full path to svnlook via this option, or by setting the $SVNLOOK environment variable, if svnlook isn't in your path or if you wanna avoid loading File::Spec.

It's important to provide a complete path to svnlook because the environment during the execution of post-commit is anemic, with nary a $PATH environment variable to be found. So if svnnotify appears not to be working at all (and Subversion seems loathe to log when it dies! 😭), make sure you've specified the complete path to a working svnlook executable.

💫 `sendmail`

svnnotify --sendmail /path/to/sendmail
svnnotify -s /path/to/sendmail

The location of the sendmail executable. If neither the sendmail nor the smtp parameter is specified, SVN::Notify will search through the directories in the $PATH environment variable, plus in /usr/local/bin and /usr/sbin, for a sendmail executable. Specify a full path to sendmail via this option, or by setting the $SENDMAIL environment variable, if sendmail isn't in your path or to avoid loading File::Spec. Same caveats as applied to the location of the svnlook executable apply here. 🫠

💫 `set_sender`

svnnotify --set-sender
svnnotify -E

Uses the -f option to sendmail to set the envelope sender address of the email to the same address that's used for the From header. If you're also using the from option, be sure to make it only an email address — don't include any other junk in it, like a sender's name. Ignored when using smtp. 🙈

💫 `smtp`

svnnotify --smtp smtp.example.com

The address for an SMTP server through which to send the notification email. If unspecified, SVN::Notify will use sendmail to send the message. If sendmail is not installed locally (such as on Windows boxes! 💀), you must specify an SMTP server.

💫 `smtp_tls`

svnnotify --smtp-tls

Use TLS authentication and encrypted channels for connecting with the server. Usually, TLS servers will require user/password authentication. 🔐

💫 `smtp_user`

svnnotify --smtp-user myuser

The user name for SMTP authentication. If this option is specified, SVN::Notify will use Net::SMTP_auth to send the notification message, and will of course authenticate to the SMTP server.

💫 `smtp_pass`

svnnotify --smtp-pass mypassword

The password for SMTP authentication. Use in parallel with smtp_user. 🔑

💫 `smtp_port`

svnnotify --smtp-port 465

The port for an SMTP server through which to send the notification email. The default port is 25.

💫 `smtp_authtype`

svnnotify --smtp-authtype authtype

Deprecated in SVN::Notify 2.83, where it has become a no-op. The auth type is determined by the contents returned by the SMTP server's response to the EHLO command. See "TLS and AUTHentication" in Net::SMTP::TLS for details. 💀

💫 `encoding`

svnnotify --encoding UTF-8
svnnotify -c Big5

The character set typically used on the repository for log messages, file names, and file contents. Used to specify the character set in the email Content-Type headers and, when the language parameter is specified, the $LANG environment variable when launching sendmail. See "Character Encoding Support" for more info. Defaults to UTF-8. 🌍

💫 `charset`

svnnotify --charset UTF-8

Deprecated. Use encoding instead. 💀

--svn-encoding (param: svn_encoding) — the charset that your files and log messages live in over in Subversion-land 🦋 Set this when you store files in Subversion using one charset but you wanna send your notification emails in a different one. So encoding handles the charset of the notification message, and svn_encoding handles reading data out of Subversion. Peep "Character Encoding Support" for the full tea. Defaults to whatever's chilling in encoding.

svnnotify --svn-encoding euc-jp

--diff-encoding (param: diff_encoding) — the charset used by the files in Subversion, which is therefore the charset showing up in the diff 🌸 Set this if you store files in Subversion using one charset but write your log messages in a different one. So svn_encoding reads the log message and diff_encoding reads the diff from Subversion. See "Character Encoding Support" for more. Defaults to whatever svn_encoding is set to.

svnnotify --diff-encoding iso-2022-jp

--language, -g (param: language) — the language typically used on the repository for log messages, file names, and file contents 🌈 It's used to set the email's Content-Language header and to set the $LANG environment variable to "$notify->language . '.' . $notify->encoding" before running svnlook and sendmail (but not for sending data to Net::SMTP, bestie). Undefined by default — meaning no Content-Language header gets output and $LANG does not get set. See "Character Encoding Support".

svnnotify --language fr
svnnotify -g i-klingon

--with-diff, -d (param: with_diff) — a boolean that says whether or not to drop the output of svnlook diff into the notification email 💅 The diff goes inline at the end of the email unless the attach_diff parameter is true.

svnnotify --with-diff
svnnotify -d

--attach-diff, -a (param: attach_diff) — a boolean that says whether or not to attach the output of svnlook diff to the notification email 🎀 Instead of being inline in the body, SVN::Notify attaches the diff as a separate file, named for the user who triggered the commit plus the date and time UTC at which the commit took place. Setting this true implicitly sets with_diff to true too, no cap.

svnnotify --attach-diff
svnnotify -a

--diff-switches, -w (param: diff_switches) — switches you pass straight through to svnlook diff, like --no-diff-deleted and --no-diff-added ✨ And who even knows, maybe someday it'll support the same options as svn diff, like --diff-cmd and --extensions. Only relevant when used with with_diff or attach_diff.

svnnotify --diff-switches '--no-diff-added'
svnnotify -w '--no-diff-deleted'

--diff-content-type (param: diff_content_type) — sets the Content-Type header for attached diffs 📎 The default, if you don't pass this, is 'text/plain'. This parameter does literally nothing if '--attach-diff' isn't specified.

svnnotify --diff-content-type 'text/x-diff'

--reply-to, -R (param: reply_to) — the email address to use in the Reply-To header of the notification email 💌 If you don't set a value for reply_to, no Reply-To header gets added at all.

svnnotify --reply-to devlist@example.com
svnnotify -R developers@example.net

--add-header (param: add_headers) — add a header to the notification email message 👑 The header name and its value must be separated by an equals sign. Specify the option multiple times to add multiple headers, and yes, headers with the same names are allowed. Not to be confused with the --header option, which adds introductory text to the beginning of the email body.

svnnotify --add-header X-Approve=letMeIn

--subject-prefix, -P (param: subject_prefix) — an optional string that gets prepended to the beginning of the subject line of the notification email ⭐ If it contains '%d', that's where the revision number goes; otherwise it's just simply prepended to the subject, which will contain the revision number in brackets.

svnnotify --subject-prefix [Devlist]
svnnotify -P [%d (Our-Developers)]

--subject-cx, -C (param: subject_cx) — a boolean for whether or not to include the context of the commit in the subject line 🧚 In a commit that touches multiple files, the context is the name of the shortest directory affected by the commit — this should tell you up to how high up the Subversion repository tree the commit had an effect. If the commit affects a single file, the context is just that file's name.

svnnotify --subject-cx
svnnotify -C

--strip-cx-regex, -X (param: strip_cx_regex) — one or more regular expressions used to strip out parts of the subject context 🌸 This is so useful for very deep Subversion trees, where the commits you're sending are always coming from a particular subtree and you'd like to remove part of the tree. Only used if subject_cx is set to a true value. Pass an array reference if you're calling new() directly.

svnnotify --strip-cx-regex '^trunk/'
svnnotify --strip-cx-regex '^trunk/' --strip-cx-regex '^branches/'
svnnotify -X '^trunk'
svnnotify -X '^trunk' -X '^branches'

--no-first-line, -O (param: no_first_line) — omits the first line of the log message from the subject 💅 Most useful when paired with the subject_cx parameter, so that only the commit context shows up in the subject and no part of the log message does.

svnnotify --no-first-line
svnnotify -O

--header (param: header) — adds a specified text to each message as a header at the beginning of the body of the message 🌸 Not to be confused with the --add-header option, which adds a header to the headers section of the email.

svnnotify --header 'SVN::Notify is brought to you by Kineticode.

--footer (param: footer) — adds a specified text to each message as a footer at the end of the body of the message 💖

svnnotify --footer 'Copyright (R) by Kineticode, Inc.'

--max-sub-length, -i (param: max_sub_length) — the maximum length of the notification email subject line 📏 SVN::Notify includes the first line of the commit log message, or the first sentence of the message (defined as any text up to the string ". "), whichever is shorter. And bestie, that could potentially be so long. To stop the subject from going over a certain number of characters, specify a maximum length here, and SVN::Notify will truncate the subject to the last word under that length. Slay.

svnnotify --max-sub-length 72
svnnotify -i 76

--max-diff-length (param: max_diff_length) — the maximum length of the diff (attached or in the body) 🔥 The diff output is truncated at the last line under the maximum character count you specify, and then it outputs an additional line indicating that the maximum diff size was reached and output truncated. This is a lifesaver when a huge diff output could cause a message to bounce because of message size.

svnnotify --max-diff-length 1024

--handler, -H (param: handler) — specify the subclass of SVN::Notify to be constructed and returned, and therefore to handle the notification 👑 Obviously you can just use a subclass directly, but this parameter is designed to make it easy to just use SVN::Notify->new without stressing about loading subclasses, like over in svnnotify. Be sure to read the documentation for your subclass of choice, because there may be additional parameters and existing parameters may behave differently. Iykyk.

svnnotify --handler HTML
svnnotify -H HTML

--filter, -F (param: filters) — specify one or more modules to be loaded in the expectation that they define output filters 🧚 For example, SVN::Notify::Filter::Trac loads a filter that converts log messages from Trac's markup format to HTML. SVN::Notify::Filter::Markdown, available on CPAN, does the same for Markdown format. Check CPAN for other SVN::Notify filter modules. This command-line option can be specified more than once to load multiple filters. The filters parameter to new() should be an array reference of module names. If a value contains "::", it's assumed to be a complete module name; otherwise it's assumed to be in the SVN::Notify::Filter namespace. See SVN::Notify::Filter for details on writing your own output filters (it's really easy, I promise!).

svnnotify --filter Trac -F My::Filter

SVN::Notify->new( %params, filters => ['Markdown', 'My::Filter'] );

--author-url, --A (param: author_url) — if a URL is specified for this parameter, it gets used to create a link for the current author 🔗 The URL can have the "%s" format, where the author's username should be put into the URL.

svnnotify --author-url 'http://svn.example.com/changelog/~author=%s/repos'
svnnotify --A 'mailto:%s@example.com'

--revision-url, -U (param: revision_url) — if a URL is specified for this parameter, it gets used to create a link to the Subversion browser URL corresponding to the current revision number 🔗 It's also used to create links to any other revision numbers mentioned in the commit message. The URL must have the "%s" format, where the Subversion revision number should be put into the URL.

svnnotify --revision-url 'http://svn.example.com/changelog/?cs=%s'
svnnotify -U 'http://svn.example.com/changelog/?cs=%s'

--svnweb-url, -S (param: svnweb_url) — Deprecated. Use revision_url instead. 💀

svnnotify --svnweb-url 'http://svn.example.com/index.cgi/revision/?rev=%s'
svnnotify -S 'http://svn.example.net/index.cgi/revision/?rev=%s'

--viewcvs-url (param: viewcvs_url) — Deprecated. Use revision_url instead. 💀

svnnotify --viewcvs-url 'http://svn.example.com/viewcvs/?rev=%s&view=rev'

--ticket-map (param: ticket_map) — specifies a mapping between a regular expression and a URL 🎟️ The regex should return a single match to be interpolated into the URL, and that URL should be a sprintf format using "%s" to place the match (usually the ticket identifier) from the regex. The command-line option can be specified any number of times for different ticketing systems. To the API, it must be passed as a hash reference.

svnnotify --ticket-map '\[?#\s*(\d+)\s*\]?=http://example.com/ticket?id=%s' \
          --ticket-map 'rt=http://rt.cpan.org/NoAuth/Bugs.html?id=%s' \
          --ticket-map '\b([A-Z0-9]+-\d+)\b=http://jira/browse/%s'

The first example matches "[#1234]" or "#1234" or "[# 1234]". Keep this regex as specific as you possibly can, bestie — preferably wrapped in "\b" so it matches word boundaries. And heads up: if you're using SVN::Notify::HTML, go read its docs for a different regular expression requirement! 👀

Optionally, the key value can be a placeholder for a regular expression that SVN::Notify uses internally to match strings typically used by well-known ticketing systems. Those keys are:

rt — Matches Request Tracker (RT) ticket references of the form "Ticket # 12", "ticket 6", "RT # 52", "rt 52", "RT-Ticket # 213" or even "Ticket#1066".
bugzilla — Matches Bugzilla bug references of the form "Bug # 12" or "bug 6" or even "Bug#1066".
jira — Matches JIRA references of the form "JRA-1234".
gnats — Matches GnatsWeb references of the form "PR 1234".

`rt_url`

svnnotify --rt-url 'http://rt.cpan.org/NoAuth/Bugs.html?id=%s'
svnnotify -T 'http://rt.perl.org/NoAuth/Bugs.html?id=%s'

A shortcut for "--ticket-map 'rt=$url'", kept around for backwards compatibility. 💖

`bugzilla_url`

svnnotify --bugzilla-url 'http://bugzilla.mozilla.org/show_bug.cgi?id=%s'
svnnotify -B 'http://bugs.bricolage.cc/show_bug.cgi?id=%s'

A shortcut for "--ticket-map 'bugzilla=$url'", kept around for backwards compatibility.

`jira_url`

svnnotify --jira-url 'http://jira.atlassian.com/secure/ViewIssue.jspa?key=%s'
svnnotify -J 'http://nagoya.apache.org/jira/secure/ViewIssue.jspa?key=%s'

A shortcut for "--ticket-map 'jira=$url'", kept around for backwards compatibility.

`gnats_url`

svnnotify --gnats-url 'http://gnatsweb.example.com/cgi-bin/gnatsweb.pl?cmd=view&pr=%s'
svnnotify -G 'http://gnatsweb.example.com/cgi-bin/gnatsweb.pl?cmd=view&pr=%s'

A shortcut for "--ticket-map 'gnats=$url'", kept around for backwards compatibility.

`ticket_url`

svnnotify --ticket-url 'http://ticket.example.com/showticket.html?id=%s'

Deprecated. Use "ticket_map" instead, bestie. 🫶

`ticket_regex`

svnnotify --ticket-regex '\[?#\s*(\d+)\s*\]?'

Deprecated. Use "ticket_map" instead.

`verbose`

svnnotify --verbose -V

A value between 0 and 3 specifying how verbose SVN::Notify should be. The default is 0, meaning SVN::Notify will be silent 🤫. A value of 1 causes SVN::Notify to output some info about what it's doing, while 2 and 3 each crank the verbosity up further. To set the verbosity on the command line, just pass the "--verbose" or "-V" option once for each level of verbosity, up to three times. Output from SVN::Notify is sent to "STDOUT".

`boundary`

The boundary to use between email body text and attachments. This is normally generated by SVN::Notify for you. ✨

`subject`

The subject of the email to be sent. This attribute is normally generated by "prepare_subject()".

🎀 Class Methods 🎀

`content_type`

my $content_type = SVN::Notify->content_type;

Returns the content type of the notification message, "text/plain". It's used to set the Content-Type header for the message. Slay, simple. 💅

`register_attributes`

SVN::Notify::Subclass->register_attributes(
    foo_attr => 'foo-attr=s',
    bar      => 'bar',
    bat      => undef,
);

This class method is what subclasses use to register new attributes, bestie. Pass in a list of key/value pairs, where the keys are the attribute names and the values are option specifications in the format required by Getopt::Long. SVN::Notify will create accessors for each attribute, and if the corresponding value is defined, it'll be used by the "get_options()" class method to grab a command-line option value.

See <LSVN::Notify::HTML|SVN::Notify::HTML> for an example usage of "register_attributes()". 👑

`get_options`

my $options = SVN::Notify->get_options;

Parses the command-line options in @ARGV into a hash reference suitable for passing as the parameters to "new()". See "new" for a complete list of the supported parameters and their corresponding command-line options.

This method uses Getopt::Long to parse @ARGV. It then looks for any "handler" and "filter" options and, if it finds any, loads the appropriate classes and parses any options they require from @ARGV. Subclasses and filter classes should use "register_attributes()" to register any attributes and options they require.

After that, on Perl 5.8 and later, it decodes all of the string options from the encoding specified by the "encoding" option, or UTF-8. This lets options be passed to SVN::Notify in that encoding and end up displayed properly in the resulting notification message. 🌈

`file_label_map`

my $map = SVN::Notify->file_label_map;

Returns a hash reference of the labels to be used for the lists of files. A hash reference of file lists is stored in the "files" attribute after "prepare_files()" has been called. The hash keys in that list correspond to Subversion status codes, and these are mapped to their appropriate labels by the hash reference returned by this method:

{ U => 'Modified Paths',
  A => 'Added Paths',
  D => 'Removed Paths',
  _ => 'Property Changed'
}

`find_exe`

my $exe = SVN::Notify->find_exe($exe_name);

This method searches through the system path, as well as the extra directories /usr/local/bin and /usr/sbin (because they're common paths for "svnlook" and "sendmail") for an executable file with the name $exe_name. The first one it finds is returned with its full path. If none is found, "find_exe()" returns undef. 😭

🦋 Instance Interface 🦋

✨ Instance Methods ✨

`prepare`

$notifier->prepare;

Prepares the SVN::Notify object, collecting all the data it needs in preparation for sending the notification email. Really it's just a shortcut for:

$notifier->prepare_recipients;
$notifier->prepare_contents;
$notifier->prepare_files;
$notifier->prepare_subject;

Only it returns after the call to "prepare_recipients()" if there are no recipients (that is, as when recipients are specified solely by the "to_regex_map" or "to_email_map" parameter and none of the regular expressions match any of the affected directories).

`prepare_recipients`

$notifier->prepare_recipients;

Collects and prepares a list of the notification recipients. The recipients are a combination of the value passed to the "to" parameter, plus any email addresses specified as keys in the hash reference passed to the "to_regex_map" parameter or values passed to the "to_email_map" parameter, where the corresponding regular expressions stored in the hash match one or more of the names of the directories affected by the commit.

If the subject_cx parameter to "new()" has a true value, "prepare_recipients()" also determines the directory name to use for the context. 🎯

`prepare_contents`

$notifier->prepare_contents;

Prepares the contents of the commit message, including the name of the user who triggered the commit (and therefore the contents of the "From" header to be used in the email) and the log message.

`prepare_files`

$notifier->prepare_files;

Prepares the lists of files affected by the commit, sorting them into their categories: modified files, added files, and deleted files. It also compiles a list of files wherein a property was set, which might have some overlap with the list of modified files (if a single commit both modified a file and set a property on it). It's giving multitasking. 💅

If the "subject_cx" parameter was specified and a single file was affected by the commit, then "prepare_files()" will also specify that file name as the context to be used in the subject line of the commit email.

`prepare_subject`

$notifier->prepare_subject;

Prepares the subject line for the notification email. This method must be called after "prepare_recipients()" and "prepare_files()", since each of those methods potentially sets up the context for use in the subject line. The subject may have a prefix defined by the "subject_prefix" parameter to "new()", it has the revision number, it might have the context if "subject_cx" specified a true value, and it will have the first sentence or line of the commit, whichever is shorter. The subject may then be truncated to the maximum length specified by the "max_sub_length" parameter.

`execute`

$notifier->execute;

Sends the notification message. This involves opening a file handle to sendmail or a tied file handle connected to an SMTP server and passing it to "output()". This is the main method used to send notifications or execute any other actions in response to Subversion activity. Main character energy fr fr. 👑

`output`

$notifier->output($file_handle);
$notifier->output($file_handle, $no_headers);

Called internally by "execute()" to output a complete email message. The file is a file handle, so that "output()" and its related methods can print directly to the email message. The optional second argument, if true, will suppress the output of the email headers.

Really "output()" is a simple wrapper around a number of other method calls. It is thus essentially a shortcut for:

$notifier->output_headers($out) unless $no_headers;
$notifier->output_content_type($out);
$notifier->start_body($out);
$notifier->output_metadata($out);
$notifier->output_log_message($out);
$notifier->output_file_lists($out);
if ($notifier->with_diff) {
    my $diff_handle = $self->diff_handle;
    if ($notifier->attach_diff) {
        $notifier->end_body($out);
        $notifier->output_attached_diff($out, $diff_handle);
    } else {
        $notifier->output_diff($out, $diff_handle);
        $notifier->end_body($out);
    }
} else {
    $notifier->end_body($out);
}
$notifier->end_message($out);

`output_headers`

$notifier->output_headers($file_handle);

Outputs the headers for the notification message headers. Should be called only once for a single email message. No double-dipping, bestie. 🙈

`output_content_type`

$notifier->output_content_type($file_handle);

Outputs the content type and transfer encoding headers. These demarcate the body of the message. If the "attach_diff" parameter was set to true, then a boundary string will be generated and the Content-Type set to "multipart/mixed" and stored as the "boundary" attribute. 🌸

Okay so back to the header drama, bestie: after all that, this method outputs the content type that content_type() hands back, the character set that the encoding attribute says, and a Content-Transfer-Encoding of 8bit. Subclasses can either ride with all of that or override this method to serve up their own content type headers. Your call, your rules. 💅

`start_body`

$notifier->start_body($file_handle);

This one kicks off the body of the notification message, which lowkey means it outputs whatever's chillin' in the header attribute — if there's anything in there at all. If there isn't, it outputs nothing, but peep the subclasses for other behaviors, because they do their own thing.

`output_metadata`

$notifier->output_metadata($file_handle);

Outputs the metadata of the commit, and like — the whole glow-up: the revision number, the author (user), and the date of the revision. And if the author_url or revision_url attributes have been set, then the appropriate URL(s) for the revision get output too. iconic behavior fr ✨

`output_log_message`

$notifier->output_log_message($file_handle);

Outputs the commit log message, plus the label Log Message. Simple. Clean. Ate.

`output_file_lists`

$notifier->output_file_lists($file_handle);

Outputs the lists of modified, added, and deleted files, and also the list of files for which properties were changed. The labels used for each group are pulled in from the file_label_map() class method. So if you wanna customize those labels, that's where you go, iykyk. 👑

`end_body`

$notifier->end_body($file_handle);

Closes out the body of the email by outputting the contents of the footer attribute, if there's any, and then a couple of newlines. Designed to be called when the body of the message is complete, and before any call to output_attached_diff(). Order matters bestie, don't be out here doing it backwards. 💀

`output_diff`

$notifier->output_diff($out_file_handle, $diff_file_handle);

Reads diff data from $diff_file_handle and outputs it to $out_file_handle. That's it, that's the vibe.

`output_attached_diff`

$notifier->output_attached_diff($out_file_handle, $diff_file_handle);

Reads diff data from $diff_file_handle and outputs it to $out_file_handle as an attachment. Yes it's the same as the last one except ✨attachment✨. We love a glow-up.

`end_message`

$notifier->end_message($file_handle);

Outputs the final part of the message. In this case, that means only a boundary if the attach_diff parameter is true. Designed to be called after any call to output_attached_diff(). the way that it only shows up when attach_diff is true… main character energy 🎀

`run_ticket_map`

$notifier->run_ticket_map( \&callback, @params );

Loops over the ticket systems you have defined, calling the $callback function for each one, passing to it the regex, url and @params specified as its parameters. Callback time, bestie 🔥

`run_filters`

$data = $notifier->run_filters( $output_type => $data );

Runs the filters for $output_type on $data. Used internally by SVN::Notify and by subclasses. Internal business, don't touch unless you're supposed to. 🙈

`filters_for`

my $filters = $notifier->filters_for( $output_type );

Returns an array reference of of the filters loaded for $output_type. Returns undef if there are no filters have been loaded for $output_type. Yes, "of of" — the original said it, I'm just the messenger 💅

`diff_handle`

my $diff = $notifier->diff_handle;
while (<$diff>) { print }

Returns a file handle reference providing access to the the commit diff. It will usually be passed as the second argument to output_diff() or output_attached_diff(). the way you can just loop over it… obsessed 😭

🌸 Accessors 🌸

Okay bestie, this is the get-and-set zone. Every single one of these works the same iconic way: call it with no args and you get the value, call it with an arg and you set it. Slay.

`repos_path`

my $repos_path = $notifier->repos_path;
$notifier = $notifier->repos_path($repos_path);

Gets or sets the value of the repos_path attribute.

`revision`

my $revision = $notifier->revision;
$notifier = $notifier->revision($revision);

Gets or sets the value of the revision attribute.

`to`

my $to = $notifier->to;
$notifier = $notifier->to($to);
my @tos = $notifier->to;
$notifier = $notifier->to(@tos);

Gets or sets the list of values stored in the to attribute. In a scalar context, it returns only the first value in the list, for backwards compatibility with older versions of SVN::Notify. In list context, it of course returns the entire list. Pass in one or more values to set all of the values for the to attribute. Context is everything here bestie, don't get caught slipping. 👑

`to_regex_map`

my $to_regex_map = $notifier->to_regex_map;
$notifier = $notifier->to_regex_map($to_regex_map);

Gets or sets the value of the to_regex_map attribute, which is a hash reference of email addresses mapped to regular expressions.

`to_email_map`

my $to_email_map = $notifier->to_email_map;
$notifier = $notifier->to_email_map($to_email_map);

Gets or sets the value of the to_email_map attribute, which is a hash reference of regular expressions mapped to email addresses. (yep, it's the mirror-image of the one above — regices mapped to addresses instead 💜)

`from`

my $from = $notifier->from;
$notifier = $notifier->from($from);

Gets or sets the value of the from attribute.

`user_domain`

my $user_domain = $notifier->user_domain;
$notifier = $notifier->user_domain($user_domain);

Gets or sets the value of the user_domain attribute.

`svnlook`

my $svnlook = $notifier->svnlook;
$notifier = $notifier->svnlook($svnlook);

Gets or sets the value of the svnlook attribute.

`sendmail`

my $sendmail = $notifier->sendmail;
$notifier = $notifier->sendmail($sendmail);

Gets or sets the value of the sendmail attribute.

`set_sender`

my $set_sender = $notifier->set_sender;
$notifier = $notifier->set_sender($set_sender);

Gets or sets the value of the set_sender attribute.

`smtp`

my $smtp = $notifier->smtp;
$notifier = $notifier->smtp($smtp);

Gets or sets the value of the smtp attribute.

`encoding`

my $encoding = $notifier->encoding;
$notifier = $notifier->encoding($encoding);

Gets or sets the value of the encoding attribute. charset is an alias preserved for backward compatibility. old name, same energy 💅

`svn_encoding`

my $svn_encoding = $notifier->svn_encoding;
$notifier = $notifier->svn_encoding($svn_encoding);

Gets or sets the value of the svn_encoding attribute.

`diff_encoding`

my $diff_encoding = $notifier->diff_encoding;
$notifier = $notifier->diff_encoding($diff_encoding);

Gets or sets the value of the diff_encoding attribute.

`language`

my $language = $notifier->language;
$notifier = $notifier->language($language);

Gets or sets the value of the language attribute.

`env_lang`

my $env_lang = $notifier->env_lang;
$notifier = $notifier->env_lang($env_lang);

Gets or sets the value of the env_lang attribute, which is set to "$notify->language . '.' . $notify->encoding" when language is set, and otherwise is undef. This attribute is used to set the $LANG environment variable, if it is not already set by the environment, before executing sendmail. So like, environment respect first, always. 🌈

`svn_env_lang`

my $svn_env_lang = $notifier->svn_env_lang;
$notifier = $notifier->svn_env_lang($svn_env_lang);

Gets or sets the value of the svn_env_lang attribute, which is set to "$notify->language . '.' . $notify->svn_encoding" when language is set, and otherwise is undef. This attribute is used to set the $LANG environment variable, if it is not already set by the environment, before executing svnlook.

BUT — and this is a big but — it is not used for svnlook diff. The diff itself will be emitted in raw octets except for headers such as Modified, which need to be in English so that subclasses can parse them. Thus, $LANG is always set to C for the execution of svnlook diff. fr fr, don't mess with that one. 💀

`with_diff`

my $with_diff = $notifier->with_diff;
$notifier = $notifier->with_diff($with_diff);

Gets or sets the value of the with_diff attribute.

`attach_diff`

my $attach_diff = $notifier->attach_diff;
$notifier = $notifier->attach_diff($attach_diff);

Gets or sets the value of the attach_diff attribute.

`diff_switches`

my $diff_switches = $notifier->diff_switches;
$notifier = $notifier->diff_switches($diff_switches);

Gets or sets the value of the diff_switches attribute.

`reply_to`

my $reply_to = $notifier->reply_to;
$notifier = $notifier->reply_to($reply_to);

Gets or sets the value of the reply_to attribute.

`add_headers`

my $add_headers = $notifier->add_headers;
$notifier = $notifier->add_headers({
    'X-Accept' => [qw(This That)],
    'X-Reject' => 'Me!',
});

Gets or sets the value of the add_headers attribute, which is a hash reference of the headers to be added to the email message. If one header needs to appear multiple times, simply pass the corresponding hash value as an array reference of each value for the header. Not to be confused with the header accessor, which gets and sets text to be included at the beginning of the body of the email message. two totally different things bestie, do not mix them up 🙈

`subject_prefix`

my $subject_prefix = $notifier->subject_prefix;
$notifier = $notifier->subject_prefix($subject_prefix);

Gets or sets the value of the subject_prefix attribute.

`subject_cx`

my $subject_cx = $notifier->subject_cx;
$notifier = $notifier->subject_cx($subject_cx);

Gets or sets the value of the subject_cx attribute.

`strip_cx_regex`

my $strip_cx_regex = $notifier->strip_cx_regex;
$notifier = $notifier->strip_cx_regex($strip_cx_regex);
my @strip_cx_regexs = $notifier->strip_cx_regex;
$notifier = $notifier->strip_cx_regex(@strip_cx_regexs);

Gets or sets the list of values stored in the strip_cx_regex attribute. In a scalar context, it returns only the first value in the list; in list context, it of course returns the entire list. Pass in one or more values to set all of the values for the strip_cx_regex attribute. same scalar-vs-list saga as to, iconic honestly 🎀

`max_sub_length`

my $max_sub_length = $notifier->max_sub_length;
$notifier = $notifier->max_sub_length($max_sub_length);

Gets or sets the value of the max_sub_length attribute.

`max_diff_length`

my $max_diff_length = $notifier->max_diff_length;
$notifier = $notifier->max_diff_length($max_diff_length);

Gets or set the value of the max_diff_length attribute.

`author_url`

my $author_url = $notifier->author_url;
$notifier = $notifier->author_url($author_url);

Gets or sets the value of the author_url attribute.

`revision_url`

my $revision_url = $notifier->revision_url;
$notifier = $notifier->revision_url($revision_url);

Gets or sets the value of the revision_url attribute.

`svnweb_url`

Deprecated. Pleas use revision_url(), instead. bestie it's old, let it go 💀

`viewcvs_url`

Deprecated. Pleas use revision_url(), instead. same story, same energy 🌈

`verbose`

my $verbose = $notifier->verbose;
$notifier = $notifier->verbose($verbose);

Gets or sets the value of the verbose attribute.

`boundary`

my $boundary = $notifier->boundary;
$notifier = $notifier->boundary($boundary);

Gets or sets the value of the boundary attribute. This string is normally set by a call to output_headers(), but may be set ahead of time. you can pre-game it if you want to 💅

`user`

my $user = $notifier->user;
$notifier = $notifier->user($user);

`user`

my $user = $notifier->user;
$notifier = $notifier->user($user);

This is the getter/setter for the user attribute, bestie. It gets its value pulled straight from svnlook when prepare_contents() does its thing. 💅

`date`

my $date = $notifier->date;
$notifier = $notifier->date($date);

Getter/setter for the date attribute. Its value also gets pulled in from svnlook by the call to prepare_contents(). ✨

`message`

my $message = $notifier->message;
$notifier = $notifier->message($message);

Getter/setter for the message attribute. It's set to an array reference of strings by the call to prepare_contents(). No cap. 🍓

`message_size`

my $message_size = $notifier->message_size;
$notifier = $notifier->message_size($message_size);

Getter/setter for message_size. It gets its value from svnlook via prepare_contents(). 💖

`subject`

my $subject = $notifier->subject;
$notifier = $notifier->subject($subject);

Getter/setter for subject. It's normally set by a call to prepare_subject(), but you can set it explicitly if you want. Main character energy. 👑

`files`

my $files = $notifier->files;
$notifier = $notifier->files($files);

Getter/setter for files. It's set to a hash reference of change type mapped to arrays of strings by the call to prepare_files(). Iykyk. 🦋

`header`

my $header = $notifier->header;
$notifier = $notifier->header($header);

Getter/setter for header. Not to be confused with the add_headers attribute, which manages headers to be inserted into the notification email message headers. Don't mix them up, bestie! 💀

`footer`

my $footer = $notifier->footer;
$notifier = $notifier->footer($footer);

Getter/setter for footer. That's it. That's the whole vibe. 🌸

✨ Character Encoding Support ✨

SVN::Notify has comprehensive support for character encodings, but since it cannot always know what encodings your system supports or in which your data is stored in Subversion, it needs your help. In plain English, here's what you need to know to make non-ASCII characters look right in SVN::Notify's messages:

The encoding for messages — To tell SVN::Notify what character encoding to use when it sends messages, use the --encoding option. It defaults to UTF-8, which should cover the vast majority of needs. You're using it in your code already, right? 💖
The character set you use in your log messages — To tell SVN::Notify the character encoding that you use in Subversion commit log messages, as well as the names of the files in Subversion, use the --svn-encoding option, which defaults to the same value as --encoding. If, for example, you write log messages in Big5, pass --svn-encoding Big5. 🌈
The character set you use in your code — To tell SVN::Notify the character encoding that you use in the files stored in Subversion, and therefore that will be output in diffs, use the --diff-encoding option, which defaults to the same value as --svn-encoding. If, for example, you write code in euc-jp but write your commit log messages in some other encoding, pass --diff-encoding euc-jp. 🎀
The locales supported by your OS — SVN::Notify uses the values passed to --encoding, --svn-encoding, and --diff-encoding to read in data from svnlook, convert it to Perl's internal encoding, and to output messages in the proper encoding. Most of the time, if you write code in UTF-8 and want messages delivered in UTF-8, you can ignore these options.

Sometimes, however, svnlook converts its output to some other encoding. That encoding is controlled by the $LANG environment variable, which corresponds to a locale supported by your OS. (See perllocale for instructions for finding the locales supported by your system.) If your system supports UTF-8 locales but defaults to using some other locale (causing svnlook to output log messages in the wrong encoding), then all you have to do is pass the --language option to get SVN::Notify to tell svnlook to use it. For example, if all of your data is in UTF-8, pass --language en_US to get SVN::Notify to use the en_US.UTF-8 locale. Likewise, pass --language sv_SE to force the use of the sv_SE.UTF-8 locale.

Sometimes, however, the system does not support UTF-8 locales. Or perhaps you use something other than UTF-8 in your log messages or source code. This should be no problem, as SVN::Notify uses the encoding options to determine the locales to use. For example, if your OS offers the en_US.ISO88591 locale, pass both --svn-encoding and --language, like so:

--svn-encoding ISO-8859-1 --language en_US

SVN::Notify will set the $LANG environment variable to en_US.ISO88591, which svnlook will use to convert log messages from its internal form to ISO-8859-1. SVN::Notify will convert the output from svnlook to UTF-8 (or whatever --encoding you've specified) before sending the message. Of course, if you have characters that don't correspond to ISO-8859-1, you'll still get some garbage characters. It is ideal when the OS locale supports the same encodings as you use in your source code and log messages, though that's not always the case.

And finally, because the names and spellings that OS vendors use for locales can vary widely, SVN::Notify will occasionally get the name of the encoding wrong, in which case you'll see warnings such as this:

svnlook: warning: cannot set LC_CTYPE locale
svnlook: warning: environment variable LANG is en_US.ISO88591
svnlook: warning: please check that your locale name is correct

In such a case, if all of your data and your log messages are stored in the same encoding, you can set the $LANG environment variable directly in your post-commit script before running svnnotify:

LANG=en_US.ISO-88591 svnnotify -p "$1" -r "$2"

If the $LANG environment variable is already set in this way, SVN::Notify will not set it before shelling out to svnlook.

This looks like a lot of information, and it is. But in most cases, if you exclusively use UTF-8 (or ASCII!) in your source code and log messages, and your OS defaults to a UTF-8 locale, things should just work.

✨ See Also ✨

SVN::Notify::HTML — HTML notification.
SVN::Notify::HTML::ColorDiff — HTML notification with colorized diff.
SVN::Notify::Filter — How to write output filters for SVN::Notify.
SourceForge Hook Scripts — http://sourceforge.net/apps/trac/sourceforge/wiki/Subversion%20hook%20scripts — SourceForge.net support for SVN::Notify.
Windows Subversion + Apache + TortoiseSVN + SVN::Notify HOWTO — http://svn.haxx.se/users/archive-2006-05/0593.shtml — Essential for Windows Subversion users.

💖 Support 💖

This module is stored in an open GitHub repository http://github.com/theory/svn-notify/. Yes, I'm aware of the irony. Nevertheless, feel free to fork and contribute! 🫶

Please file bug reports via GitHub Issues http://github.com/theory/svn-notify/issues/ or by sending mail to bug-SVN-Notify@rt.cpan.org mailto:bug-SVN-Notify@rt.cpan.org.

👑 Author 👑

David E. Wheeler david@justatheory.com

📜 Copyright and License 📜

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's the whole page, bestie. Source/version: perl v5.36.0, date: 2022-11-20, page: SVN::Notify(3pm). Now go commit something iconic. 💅✨

📦 where this page comes from

debian bookworm: libsvn-notify-perl 2.87-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libsvn-notify-perl 2.87-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libsvn-notify-perl 2.87-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libsvn-notify-perl 2.87-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libsvn-notify-perl 2.87-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

SVN::Notify(3pm)

💖 Name 💖

🌸 Synopsis 🌸

🦋 Description 🦋

✨ Usage ✨

🪟 Windows Usage 🪟

👑 Class Interface 👑

🎀 Constructor 🎀

🌟 new

💫 repos_path

💫 revision

💫 to

💫 to_regex_map

💫 to_email_map

💫 from

💫 user_domain

💫 svnlook

💫 sendmail

💫 set_sender

💫 smtp

💫 smtp_tls

💫 smtp_user

💫 smtp_pass

💫 smtp_port

💫 smtp_authtype

💫 encoding

💫 charset

rt_url

bugzilla_url

jira_url

gnats_url

ticket_url

ticket_regex

verbose

boundary

subject

🎀 Class Methods 🎀

content_type

register_attributes

get_options

file_label_map

find_exe

🦋 Instance Interface 🦋

✨ Instance Methods ✨

prepare

prepare_recipients

prepare_contents

prepare_files

prepare_subject

execute

output

output_headers

output_content_type

start_body

output_metadata

output_log_message

output_file_lists

end_body

output_diff

output_attached_diff

end_message

run_ticket_map

run_filters

filters_for

diff_handle

🌸 Accessors 🌸

repos_path

revision

to

to_regex_map

to_email_map

from

user_domain

svnlook

sendmail

set_sender

smtp

encoding

svn_encoding

diff_encoding

💫 `repos_path`

💫 `revision`

💫 `to`

💫 `to_regex_map`

💫 `to_email_map`

💫 `from`

💫 `user_domain`

💫 `svnlook`

💫 `sendmail`

💫 `set_sender`

💫 `smtp`

💫 `smtp_tls`

💫 `smtp_user`

💫 `smtp_pass`

💫 `smtp_port`

💫 `smtp_authtype`

💫 `encoding`

💫 `charset`

`rt_url`

`bugzilla_url`

`jira_url`

`gnats_url`

`ticket_url`

`ticket_regex`

`verbose`

`boundary`

`subject`

`content_type`

`register_attributes`

`get_options`

`file_label_map`

`find_exe`

`prepare`

`prepare_recipients`

`prepare_contents`

`prepare_files`

`prepare_subject`

`execute`

`output`

`output_headers`

`output_content_type`

`start_body`

`output_metadata`

`output_log_message`

`output_file_lists`

`end_body`

`output_diff`

`output_attached_diff`

`end_message`

`run_ticket_map`

`run_filters`

`filters_for`

`diff_handle`

`repos_path`

`revision`

`to`

`to_regex_map`

`to_email_map`

`from`

`user_domain`

`svnlook`

`sendmail`

`set_sender`

`smtp`

`encoding`

`svn_encoding`

`diff_encoding`

`language`

`env_lang`

`svn_env_lang`

`with_diff`

`attach_diff`

`diff_switches`

`reply_to`

`add_headers`

`subject_prefix`

`subject_cx`

`strip_cx_regex`

`max_sub_length`

`max_diff_length`