NotifyExtension

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.
# changegroup will send one email for each push,
# whereas incoming sends one email per 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.
changegroup.notify = python:hgext.notify.hook
#incoming.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.
# If it doesn't start with \n it may confuse the email parser.
# 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 = config/*.xml,templates/*

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

3. Usage

This extension doesn't require user interaction to work.

CategoryBundledExtension