Notify extension

This extension is currently being distributed along with Mercurial.

Author: Vadim Gelfer

1. Overview

This extension is used to send automated email notifications to a list of subscribed addresses whenever a repo has changes.

It can be used from the incoming.notify and/or changegroup.notify hooks depending on the desired behaviour. On the client hg will output a message along the lines of "sending x subscribers y changes", when action is performed, eg. push to repos.

2. Configuration

2.1. .hgrc configuration example

[extensions]
notify=

[hooks]
# Enable either changegroup or incoming or outgoing.
# changegroup will send one email for all incoming changesets,
# whereas incoming sends one email per incoming changeset.
# Note: Configuring both is possible, but probably not
#       what you want, you'll get one email for the group
#       and one for each changeset in the group.
# outgoing will send one email for all outgoing changesets
changegroup.notify = python:hgext.notify.hook
#incoming.notify = python:hgext.notify.hook
#outgoing.notify = python:hgext.notify.hook
[email]
from = Your Name <your@email.address>

[smtp]
host = localhost
# Optional options:
# username = joeuser
# password = secret
# port = 25
# tls = true
# local_hostname = me.example.com

# the baseurl is used for constructing hgweb-URLs for the mails
# It can be a dummy value if your repo isn't
# available via http
[web]
baseurl = http://hgserver/hg

[notify]
# Space separated list of change sources. Notifications are sent only
# if it includes the incoming or outgoing changes source. Incoming
# sources can be ``serve`` for changes coming from http or ssh,
# ``pull`` for pulled changes, ``unbundle`` for changes added by
# :hg:`unbundle` or ``push`` for changes being pushed
# locally. Outgoing sources are the same except for ``unbundle`` which
# is replaced by ``bundle``. Default: serve.
sources = serve push unbundle

# set this to False when you're ready for mail to start sending
test = True

# While the subscription information can be included in this file,
#   (in which case, set: config =)
# having it in a separate file allows for it to be version controlled
# and for the option of having subscribers maintain it themselves.
config = /full/path/to/subscription/file

# You can override the changeset template here, if you want.
# The template is parsed as email. If it starts with a \n, only the body
# is provided. Otherwise, the first few lines are interpreted as header.
#
# Here's an example that makes the changeset template look more like hg log:
template =
  details:   {baseurl}/{webroot}/rev/{node|short}
  branches:  {branches}
  changeset: {rev}:{node|short}
  user:      {author}
  date:      {date|date}
  description:
  {desc}\n

# max lines of diffs to include (0=none, -1=all)
maxdiff = 300

# if you want to use a shorter repo-name, you can strip off components at the beginning.
# For example to strip off /usr/local/hg/repos from /usr/local/hg/repos/code use
# strip = 5

Check http://hgbook.red-bean.com/read/customizing-the-output-of-mercurial.html for more template keywords like {branches}.

There are more configuration items available, see hgext/notify.py in the mercurial distribution.

Note: If you configure diffstat and get no/empty output or remote: error: incoming.notify hook raised an exception: cannot concatenate 'str' and 'NoneType' objects (with 0.9.3 release), it means that you didn't have the diffstat program installed.

2.2. subscription file configuration options

The notify subscriptions file has same format as regular hgrc. It has two sections so you can express subscriptions in whatever way is handier for you. The glob patterns are matched against path to repo root (for example: /path/to/your/repo).

[usersubs]
# key is subscriber email, value is comma-separated list of glob patterns
user@host = *

[reposubs]
# key is glob pattern, value is comma-separated list of subscriber emails
* = user1@host,user2@host

Note that the patterns are used to match repositories, not files within repositories.

3. Usage

This extension doesn't require user interaction to work.

CategoryBundledExtension