/ 
Darcs-Notify-1.0
River stage zero No dependents
/ darcs-notify

NAME

darcs-notify - Report darcs repository changes to an email list

SYNOPSIS

darcs-notify [options] <email> [<email> ...]

Options:
  --smtp-server=<server>    Use a server other than "localhost".
  -r | --repo=<repo-dir>    Use a repo other than the current directory.
  -h | --help               Show some help.

DESCRIPTION

darcs-notify compares the list of patches in a darcs repository against a saved backup copy and sends emails about the changes. The backup copy is stored in the file _darcs/third-party/darcs-notify/old-inventory.

USAGE

One way to use darcs notify is to just run it periodically. Since it just compares the current list of patches against it's stored set it can run any time. If there is nothing to report, nothing will happen.

However, typical usage is to install it into your darcs repo's post hooks so that it runs automatically when someone pushes, pulls, or unpulls some patches. To do this, edit your _darcs/prefs/defaults file (you might need to create it if it's not there already) and add the following lines:

apply posthook darcs-notify <email>
apply run-posthook
pull posthook darcs-notify <email>
pull run-posthook
unpull posthook darcs-notify <email>
unpull run-posthook

That assumes darcs-notify is in your path. If it is not, then put its absolute path there. One technique is to place darcs-notify inside the _darcs/third-party/darcs-notify directory (you might need to create it if you haven't run darcs-notify yet) and then use its relative path in the _darcs/prefs/defaults file:

apply posthook _darcs/third-party/darcs-notify/darcs-notify <email>
apply run-posthook
pull posthook _darcs/third-party/darcs-notify/darcs-notify <email>
pull run-posthook
unpull posthook _darcs/third-party/darcs-notify/darcs-notify <email>
unpull run-posthook

You should run darcs-notify once manually on a repo before pushing or pulling to the repo. It won't do anything but set itself up.

OPTIONS

--help

Prints the help for the program and exits.

--smtp-server=<server>

Use this option to choose which mailserver gets the notification emails. The default is "localhost".

-r <repo-dir>
--repo=<repo-dir>

Operate on a specific repository. If this option is not specified then the current directory is used.

You probably don't want to use this option, it's really only useful for testing.

PATCH NOTIFICATIONS

Currently there are 2 types of email notifications:

New patch notifications

One email per new patch will be sent to each email address on the command line. This email uses the patch name as a subject and contains the darcs patch synopsis (similar to 'darcs changes' output), the diffstat, and a universal diff of the patch itself. Here's an example from darcs-notify itself:

Subject: Explicitly skip the "pristine" line for clarity/documentation.

Sun Dec 21 06:30:43 PST 2008 David Caldwell <david@porkrind.org>
  * Explicitly skip the "pristine" line for clarity/documentation.

 darcs-notify |    1 +
 1 file changed, 1 insertion(+)

Sun Dec 21 06:30:43 PST 2008  David Caldwell <david@porkrind.org>
  * Explicitly skil the "pristine" line for clarity/documentation.
diff -rN -u old-darcs-notify/darcs-notify new-darcs-notify/darcs-notify
--- old-darcs-notify/darcs-notify	2008-12-21 06:43:32.000000000 -0800
+++ new-darcs-notify/darcs-notify	2008-12-21 06:43:32.000000000 -0800
@@ -44,6 +44,7 @@
     my (@patch, $patch);
     open INV, "<", $filename or return ();
     while (<INV>) {
+        next if /^pristine:$/ && !defined $patch;
         $patch[-1] .= "\n$1" if /^(hash: .*)$/ && !defined $patch;
         (push(@patch, $patch . ($1||"")), undef $patch) if s/^(.*\*[-*]\d{14})?\]//;
         $patch = '' if s/^\s*\[//;
Unpull notifications

A single email with the subject "[Unpulled patches]" containing all unpulled patches will be sent to each email address on the command line. Only the darcs patch synopsis is sent. Here is an example:

Subject: [Unpulled patches]

Unpulled:

Sun Dec 21 06:30:43 PST 2008 David Caldwell <david@porkrind.org>
  * Explicitly skip the "pristine" line for clarity/documentation.

Sun Dec 21 06:33:02 PST 2008 David Caldwell <david@porkrind.org>
  * Add support for darcs-2 and hashed repos.

Each email contains a "X-Darcs-Notify" header set to the name of the repo's directory. This allows you to filter it nicely if you so choose.

COMPATIBILITY

darcs-notify is known to work with darcs-1 and darcs-2 repositories, including the new "old format but hashed" repositories introduced in darcs 2.0.

AUTHOR

David Caldwell <david@porkrind.org>

PROJECT HOME

http://porkrind.org/darcs-notify/