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.
2. Configuration
2.1. .hgrc configuration options
[extensions]
hgext.notify =
# XXX How do these differ, and should they both be configured or only
# one?
[hooks]
incoming.notify = python:hgext.notify.hook
changegroup.notify = python:hgext.notify.hook
[email]
from = your@email.address
[smtp]
host = localhost
# presently it is necessary to specify the baseurl for the notify
# extension to work. It can be a dummy value if your repo isn't
# available via http
[web]
baseurl = http://hgserver/...
[notify]
# multiple sources can be specified as a whitespace separated list
sources = serve push pull bundle
# set this to False when you're ready for mail to start sending
test = True
config = /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 = \ndetails: {baseurl}{webroot}/rev/{node|short}\nchangeset: {rev}:{node|short}\nuser: {author}\ndate: {date|date}\ndescription:\n{desc}\n
maxdiff = 300 # max lines of diffs to include (0=none, -1=all)There are more configuration items available, see hgext/notify.py in the mercurial distribution.
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.
[usersubs] # key is subscriber email, value is comma-separated list of glob patterns user@host = pattern [reposubs] # key is glob pattern, value is comma-separated list of subscriber emails pattern = user@host
3. Hiding repository path
I'm pushing my changes with SSH and using absolute file paths to the repository. This makes the notify emails look like:
Subject: /var/www/hg/project: description details: http://hg.project.org//var/www/hg/project/rev/12345
Which I obviously don't want. I don't know if there's a better way, but at least this solves the problem:
template = Subject: {webroot|basename}: {desc|strip|firstline}\n\ndetails: {baseurl}{webroot|basename}/rev/{node|short}\nchangeset: {rev}:{node|short}\nuser: {author}\ndate: {date|date}\ndescription:\n{desc}\n
4. Usage
This extension doesn't require user interaction to work.
5. Comments
Some comments based on an attempt to use this wiki page. Hopefully these can be merged into the wiki page by someone who knows more about this than I do.
1) The file above can be used as is if added to the .hg/hgrc of a repository.
2) hgext.notify does not require a value (can be left blank) if the extension is in the path.
3) The most common use case is for email to be sent if a push is made to the repository. This is corresponds to the sources keyword "serve", which is not obvious. What each of these keywords means really needs to be documented. Presumably an email will be sent if an action corresponding to any of the listed keywords is performed.
4) [usersubs] and [reposubs] can also be put in the hgrc file. In that case, config can be left blank. Personally, don't see the advantage of a separate config file.
5) baseurl will be used to put a url into the message you receive.
6) When action is performed, eg. push to repos, hg will output a message along the lines of
- sending x subscribers y changes.
7) Having both incoming.notify and changegroup.notify hooks configured results in two mails being sent, so you probably want just one of them.
8) Empty diffstat output, or remote: error: incoming.notify hook raised an exception: cannot concatenate 'str' and 'NoneType' objects error with 0.9.3 release means that you didn't have diffstat program installed. You can also set diffstat=False to disable it.