Diff for "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.

2. Configuration

2.1. .hgrc configuration options

[extensions]
hgext.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@email.address

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

# 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
# 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 = /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
# max lines of diffs to include (0=none, -1=all)
maxdiff = 300

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.

[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

- not sure when it was added, but the 'strip' option works good for this, it will strip off leading directories...

[notify]
# to strip off /usr/local/hg/repos
strip = 5

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. (This is true for any extension, should it be mentioned in every one? Should we link to a common explanation? Or do we assume that its to be picked up as common knowledge and not mentioned? --dwp 7/16/2008)

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. (addressed well enough above? --dwp 7/16/2008)

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.

9) If you are using ssh to talk to a remote repository, you need to add [trusted] settings in your remote ~/.hgrc file (see .hgrc ) or you will get the error "remote: Not trusting file /remote/repository's/.hg/hgrc from untrusted user itsowner, group itsgroup". This is because when you communicate with a remote hg repository, you are actually invoking hg on the remote machine, and thus the version of .hgrc on that machine is the one that has to trust the repository on that machine.

CategoryExtension