notify: rewrite user documentation
The main intent is to turn the reference help into a configuration walkthrough.
It also fix several things:
- Do not suggest to use it for commit notifications, it cannot work
- Fix notify.strip default value
- Mention that subscriptions can be setup in Mercurial configuration files
- Improve notify.strip and notify.domain documentation
--- a/hgext/notify.py Mon Jul 25 22:19:28 2011 +0300
+++ b/hgext/notify.py Tue Jul 26 21:30:12 2011 +0200
@@ -5,71 +5,115 @@
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.
-'''hooks for sending email notifications at commit/push time
+'''hooks for sending email push notifications
-Subscriptions can be managed through a hgrc file. Default mode is to
-print messages to stdout, for testing and configuring.
+This extension let you run hooks sending email notifications when
+changesets are being pushed, from the sending or receiving side.
-To use, configure the notify extension and enable it in hgrc like
-this::
-
- [extensions]
- notify =
+First, enable the extension as explained in :hg:`help extensions`, and
+register the hook you want to run. ``incoming`` and ``outgoing`` hooks
+are run by the changesets receiver while the ``outgoing`` one is for
+the sender::
[hooks]
# one email for each incoming changeset
incoming.notify = python:hgext.notify.hook
- # batch emails when many changesets incoming at one time
+ # one email for all incoming changesets
changegroup.notify = python:hgext.notify.hook
- # batch emails when many changesets outgoing at one time (client side)
+
+ # one email for all outgoing changesets
outgoing.notify = python:hgext.notify.hook
- [notify]
- # config items go here
-
-Required configuration items::
-
- config = /path/to/file # file containing subscriptions
-
-Optional configuration items::
-
- test = True # print messages to stdout for testing
- strip = 3 # number of slashes to strip for url paths
- domain = example.com # domain to use if committer missing domain
- style = ... # style file to use when formatting email
- template = ... # template to use when formatting email
- incoming = ... # template to use when run as incoming hook
- outgoing = ... # template to use when run as outgoing hook
- changegroup = ... # template to use when run as changegroup hook
- maxdiff = 300 # max lines of diffs to include (0=none, -1=all)
- maxsubject = 67 # truncate subject line longer than this
- diffstat = True # add a diffstat before the diff content
- sources = serve # notify if source of incoming changes in this list
- # (serve == ssh or http, push, pull, bundle)
- merge = False # send notification for merges (default True)
- [email]
- from = user@host.com # email address to send as if none given
- [web]
- baseurl = http://hgserver/... # root of hg web site for browsing commits
-
-The notify config file has same format as a regular hgrc file. It has
-two sections so you can express subscriptions in whatever way is
-handier for you.
-
-::
+Now the hooks are running, subscribers must be assigned to
+repositories. Use the ``[usersubs]`` section to map repositories to a
+given email or the ``[reposubs]`` section to map emails to a single
+repository::
[usersubs]
- # key is subscriber email, value is ","-separated list of glob patterns
+ # key is subscriber email, value is a comma-separated list of glob
+ # patterns
user@host = pattern
[reposubs]
- # key is glob pattern, value is ","-separated list of subscriber emails
+ # key is glob pattern, value is a comma-separated list of subscriber
+ # emails
pattern = user@host
-Glob patterns are matched against path to repository root.
+Glob patterns are matched against absolute path to repository
+root. The subscriptions can be defined in their own file and
+referenced with::
+
+ [notify]
+ config = /path/to/subscriptionsfile
+
+Alternatively, they can be added to Mercurial configuration files by
+setting the previous entry to an empty value.
+
+At this point, notifications should be generated but will not be sent until you
+set the ``notify.test`` entry to ``False``.
+
+Notifications content can be tweaked with the following configuration entries:
+
+notify.test
+ If ``True``, print messages to stdout instead of sending them. Default: True.
+
+notify.sources
+ 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.
+
+notify.strip
+ Number of leading slashes to strip from url paths. By default, notifications
+ references repositories with their absolute path. ``notify.strip`` let you
+ turn them into relative paths. For example, ``notify.strip=3`` will change
+ ``/long/path/repository`` into ``repository``. Default: 0.
+
+notify.domain
+ If subscribers emails or the from email have no domain set, complete them
+ with this value.
-If you like, you can put notify config file in repository that users
-can push changes to, they can manage their own subscriptions.
+notify.style
+ Style file to use when formatting emails.
+
+notify.template
+ Template to use when formatting emails.
+
+notify.incoming
+ Template to use when run as incoming hook, override ``notify.template``.
+
+notify.outgoing
+ Template to use when run as outgoing hook, override ``notify.template``.
+
+notify.changegroup
+ Template to use when running as changegroup hook, override
+ ``notify.template``.
+
+notify.maxdiff
+ Maximum number of diff lines to include in notification email. Set to 0
+ to disable the diff, -1 to include all of it. Default: 300.
+
+notify.maxsubject
+ Maximum number of characters in emails subject line. Default: 67.
+
+notify.diffstat
+ Set to True to include a diffstat before diff content. Default: True.
+
+notify.merge
+ If True, send notifications for merge changesets. Default: True.
+
+If set, the following entries will also be used to customize the notifications:
+
+email.from
+ Email ``From`` address to use if none can be found in generated email content.
+
+web.baseurl
+ Root repository browsing URL to combine with repository paths when making
+ references. See also ``notify.strip``.
+
'''
from mercurial.i18n import _
--- a/tests/test-notify.t Mon Jul 25 22:19:28 2011 +0300
+++ b/tests/test-notify.t Tue Jul 26 21:30:12 2011 +0200
@@ -17,67 +17,111 @@
> * = baz
> EOF
$ hg help notify
- notify extension - hooks for sending email notifications at commit/push time
-
- Subscriptions can be managed through a hgrc file. Default mode is to print
- messages to stdout, for testing and configuring.
+ notify extension - hooks for sending email push notifications
- To use, configure the notify extension and enable it in hgrc like this:
+ This extension let you run hooks sending email notifications when changesets
+ are being pushed, from the sending or receiving side.
- [extensions]
- notify =
+ First, enable the extension as explained in "hg help extensions", and register
+ the hook you want to run. "incoming" and "outgoing" hooks are run by the
+ changesets receiver while the "outgoing" one is for the sender:
[hooks]
# one email for each incoming changeset
incoming.notify = python:hgext.notify.hook
- # batch emails when many changesets incoming at one time
+ # one email for all incoming changesets
changegroup.notify = python:hgext.notify.hook
- # batch emails when many changesets outgoing at one time (client side)
+
+ # one email for all outgoing changesets
outgoing.notify = python:hgext.notify.hook
- [notify]
- # config items go here
-
- Required configuration items:
-
- config = /path/to/file # file containing subscriptions
-
- Optional configuration items:
-
- test = True # print messages to stdout for testing
- strip = 3 # number of slashes to strip for url paths
- domain = example.com # domain to use if committer missing domain
- style = ... # style file to use when formatting email
- template = ... # template to use when formatting email
- incoming = ... # template to use when run as incoming hook
- outgoing = ... # template to use when run as outgoing hook
- changegroup = ... # template to use when run as changegroup hook
- maxdiff = 300 # max lines of diffs to include (0=none, -1=all)
- maxsubject = 67 # truncate subject line longer than this
- diffstat = True # add a diffstat before the diff content
- sources = serve # notify if source of incoming changes in this list
- # (serve == ssh or http, push, pull, bundle)
- merge = False # send notification for merges (default True)
- [email]
- from = user@host.com # email address to send as if none given
- [web]
- baseurl = http://hgserver/... # root of hg web site for browsing commits
-
- The notify config file has same format as a regular hgrc file. It has two
- sections so you can express subscriptions in whatever way is handier for you.
+ Now the hooks are running, subscribers must be assigned to repositories. Use
+ the "[usersubs]" section to map repositories to a given email or the
+ "[reposubs]" section to map emails to a single repository:
[usersubs]
- # key is subscriber email, value is ","-separated list of glob patterns
+ # key is subscriber email, value is a comma-separated list of glob
+ # patterns
user@host = pattern
[reposubs]
- # key is glob pattern, value is ","-separated list of subscriber emails
+ # key is glob pattern, value is a comma-separated list of subscriber
+ # emails
pattern = user@host
- Glob patterns are matched against path to repository root.
+ Glob patterns are matched against absolute path to repository root. The
+ subscriptions can be defined in their own file and referenced with:
+
+ [notify]
+ config = /path/to/subscriptionsfile
+
+ Alternatively, they can be added to Mercurial configuration files by setting
+ the previous entry to an empty value.
+
+ At this point, notifications should be generated but will not be sent until
+ you set the "notify.test" entry to "False".
+
+ Notifications content can be tweaked with the following configuration entries:
+
+ notify.test
+ If "True", print messages to stdout instead of sending them. Default: True.
+
+ notify.sources
+ 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.
+
+ notify.strip
+ Number of leading slashes to strip from url paths. By default, notifications
+ references repositories with their absolute path. "notify.strip" let you
+ turn them into relative paths. For example, "notify.strip=3" will change
+ "/long/path/repository" into "repository". Default: 0.
+
+ notify.domain
+ If subscribers emails or the from email have no domain set, complete them
+ with this value.
- If you like, you can put notify config file in repository that users can push
- changes to, they can manage their own subscriptions.
+ notify.style
+ Style file to use when formatting emails.
+
+ notify.template
+ Template to use when formatting emails.
+
+ notify.incoming
+ Template to use when run as incoming hook, override "notify.template".
+
+ notify.outgoing
+ Template to use when run as outgoing hook, override "notify.template".
+
+ notify.changegroup
+ Template to use when running as changegroup hook, override
+ "notify.template".
+
+ notify.maxdiff
+ Maximum number of diff lines to include in notification email. Set to 0 to
+ disable the diff, -1 to include all of it. Default: 300.
+
+ notify.maxsubject
+ Maximum number of characters in emails subject line. Default: 67.
+
+ notify.diffstat
+ Set to True to include a diffstat before diff content. Default: True.
+
+ notify.merge
+ If True, send notifications for merge changesets. Default: True.
+
+ If set, the following entries will also be used to customize the
+ notifications:
+
+ email.from
+ Email "From" address to use if none can be found in generated email content.
+
+ web.baseurl
+ Root repository browsing URL to combine with repository paths when making
+ references. See also "notify.strip".
no commands defined
$ hg init a