Skip to content
Snippets Groups Projects
Commit 0fdd8193 authored by David Champion's avatar David Champion
Browse files

notify: various fixes to docstring

Typo corrections, grammar adjustments, clarity improvements.
parent d9238286
No related branches found
No related tags found
No related merge requests found
......@@ -7,8 +7,8 @@
'''hooks for sending email push notifications
This extension let you run hooks sending email notifications when
changesets are being pushed, from the sending or receiving side.
This extension implements hooks to send email notifications when
changesets are sent from or received by the local repository.
First, enable the extension as explained in :hg:`help extensions`, and
register the hook you want to run. ``incoming`` and ``changegroup`` hooks
......@@ -12,8 +12,8 @@
First, enable the extension as explained in :hg:`help extensions`, and
register the hook you want to run. ``incoming`` and ``changegroup`` hooks
are run by the changesets receiver while the ``outgoing`` one is for
the sender::
are run when changesets are received, while ``outgoing`` hooks are for
changesets sent to another repository::
[hooks]
# one email for each incoming changeset
......@@ -24,9 +24,9 @@
# one email for all outgoing changesets
outgoing.notify = python:hgext.notify.hook
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::
This registers the hooks. To enable notification, subscribers must
be assigned to repositories. The ``[usersubs]`` section maps multiple
repositories to a given recipient. The ``[reposubs]`` section maps
multiple recipients to a single repository::
[usersubs]
......@@ -31,6 +31,6 @@
[usersubs]
# key is subscriber email, value is a comma-separated list of glob
# key is subscriber email, value is a comma-separated list of repo glob
# patterns
user@host = pattern
......@@ -40,9 +40,12 @@
pattern = user@host
Glob patterns are matched against absolute path to repository
root. The subscriptions can be defined in their own file and
referenced with::
root.
In order to place them under direct user management, ``[usersubs]`` and
``[reposubs]`` sections may be placed in a separate ``hgrc`` file and
incorporated by reference::
[notify]
config = /path/to/subscriptionsfile
......@@ -45,12 +48,9 @@
[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 will not be sent until the ``notify.test`` value is set
to ``False``; see below.
Notifications content can be tweaked with the following configuration entries:
......@@ -58,13 +58,16 @@
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.
Space-separated list of change sources. Notifications are activated only
when a changeset's source is in this list. Sources may be:
:``serve``: changesets received via http or ssh
:``pull``: changesets received via ``hg pull``
:``unbundle``: changesets received via ``hg unbundle``
:``push``: changesets sent or received via ``hg push``
:``bundle``: changesets sent via ``hg unbundle``
Default: serve.
notify.strip
Number of leading slashes to strip from url paths. By default, notifications
......@@ -68,8 +71,8 @@
notify.strip
Number of leading slashes to strip from url paths. By default, notifications
references repositories with their absolute path. ``notify.strip`` let you
reference repositories with their absolute path. ``notify.strip`` lets you
turn them into relative paths. For example, ``notify.strip=3`` will change
``/long/path/repository`` into ``repository``. Default: 0.
notify.domain
......@@ -72,9 +75,8 @@
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.
Default email domain for sender or recipients with no explicit domain.
notify.style
Style file to use when formatting emails.
......@@ -83,6 +85,6 @@
Template to use when formatting emails.
notify.incoming
Template to use when run as incoming hook, override ``notify.template``.
Template to use when run as an incoming hook, overriding ``notify.template``.
notify.outgoing
......@@ -87,5 +89,5 @@
notify.outgoing
Template to use when run as outgoing hook, override ``notify.template``.
Template to use when run as an outgoing hook, overriding ``notify.template``.
notify.changegroup
......@@ -90,7 +92,7 @@
notify.changegroup
Template to use when running as changegroup hook, override
Template to use when running as a changegroup hook, overriding
``notify.template``.
notify.maxdiff
Maximum number of diff lines to include in notification email. Set to 0
......@@ -93,7 +95,7 @@
``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.
to disable the diff, or -1 to include all of it. Default: 300.
notify.maxsubject
......@@ -98,6 +100,6 @@
notify.maxsubject
Maximum number of characters in emails subject line. Default: 67.
Maximum number of characters in email's subject line. Default: 67.
notify.diffstat
Set to True to include a diffstat before diff content. Default: True.
......@@ -109,7 +111,7 @@
If set, append mails to this mbox file instead of sending. Default: None.
notify.fromauthor
If set, use the first committer of the changegroup for the "From" field of
the notification mail. If not set, take the user from the pushing repo.
Default: False.
If set, use the committer of the first changeset in a changegroup for
the "From" field of the notification mail. If not set, take the user
from the pushing repo. Default: False.
......@@ -115,4 +117,5 @@
If set, the following entries will also be used to customize the notifications:
If set, the following entries will also be used to customize the
notifications:
email.from
......@@ -117,5 +120,6 @@
email.from
Email ``From`` address to use if none can be found in generated email content.
Email ``From`` address to use if none can be found in the generated
email content.
web.baseurl
......@@ -120,6 +124,6 @@
web.baseurl
Root repository browsing URL to combine with repository paths when making
Root repository URL to combine with repository paths when making
references. See also ``notify.strip``.
'''
......
......@@ -19,7 +19,7 @@
$ hg help notify
notify extension - hooks for sending email push notifications
This extension let you run hooks sending email notifications when changesets
are being pushed, from the sending or receiving side.
This extension implements hooks to send email notifications when changesets
are sent from or received by the local repository.
First, enable the extension as explained in "hg help extensions", and register
......@@ -24,7 +24,8 @@
First, enable the extension as explained in "hg help extensions", and register
the hook you want to run. "incoming" and "changegroup" hooks are run by the
changesets receiver while the "outgoing" one is for the sender:
the hook you want to run. "incoming" and "changegroup" hooks are run when
changesets are received, while "outgoing" hooks are for changesets sent to
another repository:
[hooks]
# one email for each incoming changeset
......@@ -35,8 +36,9 @@
# one email for all outgoing changesets
outgoing.notify = python:hgext.notify.hook
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:
This registers the hooks. To enable notification, subscribers must be assigned
to repositories. The "[usersubs]" section maps multiple repositories to a
given recipient. The "[reposubs]" section maps multiple recipients to a single
repository:
[usersubs]
......@@ -41,6 +43,6 @@
[usersubs]
# key is subscriber email, value is a comma-separated list of glob
# key is subscriber email, value is a comma-separated list of repo glob
# patterns
user@host = pattern
......@@ -49,9 +51,12 @@
# emails
pattern = user@host
Glob patterns are matched against absolute path to repository root. The
subscriptions can be defined in their own file and referenced with:
Glob patterns are matched against absolute path to repository root.
In order to place them under direct user management, "[usersubs]" and
"[reposubs]" sections may be placed in a separate "hgrc" file and incorporated
by reference:
[notify]
config = /path/to/subscriptionsfile
......@@ -54,12 +59,9 @@
[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 will not be sent until the "notify.test" value is set to
"False"; see below.
Notifications content can be tweaked with the following configuration entries:
......@@ -67,12 +69,16 @@
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.
Space-separated list of change sources. Notifications are activated only
when a changeset's source is in this list. Sources may be:
"serve" changesets received via http or ssh
"pull" changesets received via "hg pull"
"unbundle" changesets received via "hg unbundle"
"push" changesets sent or received via "hg push"
"bundle" changesets sent via "hg unbundle"
Default: serve.
notify.strip
Number of leading slashes to strip from url paths. By default, notifications
......@@ -76,8 +82,8 @@
notify.strip
Number of leading slashes to strip from url paths. By default, notifications
references repositories with their absolute path. "notify.strip" let you
reference repositories with their absolute path. "notify.strip" lets you
turn them into relative paths. For example, "notify.strip=3" will change
"/long/path/repository" into "repository". Default: 0.
notify.domain
......@@ -80,9 +86,8 @@
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.
Default email domain for sender or recipients with no explicit domain.
notify.style
Style file to use when formatting emails.
......@@ -91,6 +96,6 @@
Template to use when formatting emails.
notify.incoming
Template to use when run as incoming hook, override "notify.template".
Template to use when run as an incoming hook, overriding "notify.template".
notify.outgoing
......@@ -95,5 +100,5 @@
notify.outgoing
Template to use when run as outgoing hook, override "notify.template".
Template to use when run as an outgoing hook, overriding "notify.template".
notify.changegroup
......@@ -98,7 +103,7 @@
notify.changegroup
Template to use when running as changegroup hook, override
Template to use when running as a changegroup hook, overriding
"notify.template".
notify.maxdiff
Maximum number of diff lines to include in notification email. Set to 0 to
......@@ -101,7 +106,7 @@
"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.
disable the diff, or -1 to include all of it. Default: 300.
notify.maxsubject
......@@ -106,6 +111,6 @@
notify.maxsubject
Maximum number of characters in emails subject line. Default: 67.
Maximum number of characters in email's subject line. Default: 67.
notify.diffstat
Set to True to include a diffstat before diff content. Default: True.
......@@ -117,11 +122,11 @@
If set, append mails to this mbox file instead of sending. Default: None.
notify.fromauthor
If set, use the first committer of the changegroup for the "From" field of
the notification mail. If not set, take the user from the pushing repo.
Default: False.
If set, use the committer of the first changeset in a changegroup for the
"From" field of the notification mail. If not set, take the user from the
pushing repo. Default: False.
If set, the following entries will also be used to customize the
notifications:
email.from
......@@ -123,8 +128,9 @@
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.
Email "From" address to use if none can be found in the generated email
content.
web.baseurl
......@@ -129,7 +135,7 @@
web.baseurl
Root repository browsing URL to combine with repository paths when making
references. See also "notify.strip".
Root repository URL to combine with repository paths when making references.
See also "notify.strip".
no commands defined
$ hg init a
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment