Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
Note: You can generate this documentation with the following commands; * perldoc svn-watch.pl * pod2text svn-watch.pl > documentation.txt #Text Documentation * pod2html svn-watch.pl > svn-watch.html #HTML Documentation ======================================================================== NAME svn-watch.pl SYNOPSIS svn-watch.pl -r <rev> [-directory <dir>] [-suffix <suffix>] \ [-domain <domain>] [-smtphost <host>] [-message <message>] \ [-sender <sender>] [-svnlook <svnlook>] [-subject <subject>] \ [-debug <debuglevel>] [-url <url>] [-noemail] \ [-smtpuser <host> -smtppassword <passwd>] <repos> or svn-watch.pl -help or svn-watch.pl -options DESCRIPTION This program implements watchlists in Subversion. A watchlist is a list of files that a particular user would be notified on if changes occur in a file that user was watching. Although there are many similar programs like this for Subversion, most require access to the Subversion server to set, so users are unable to set their own watch lists. This program, however, allows users of Subversion to set their own watch lists since the watch list is actually stored in the Subversion repository itself. In the user's watchlist, the user specifies the various email addresses where notifications are sent when a file they were watching was modified. Users are allowed to specify multiple email addresses, and the program can be configured to automatically email the user at a default email address if the user didn't specify one. The default email address is set to the user's Subversion account name at the default domain provided when executing this program. Users can specify the files thwy are watching using Ant globbing (which has very straight forward syntax) or Perl regular expressions (which are more powerful, but the syntax is trickier). INSTALLATION This program operates as a Subversion post-commit trigger and is automatically executed after each revision. REQUIREMENTS * Perl 5.7 or later. * Mail::Sendmail (optional). This is an optional Perl module to install. It's very old, but straightforward and usually works without too many issues. You can use the Perl CPAN utility to install this module. If this module is not installed, this program will automatically use the Net::SMTP module which is a standard Perl module, so it doesn't have to be installed. Unfortunately, this module sometimes fails and crashes the post-commit process leaving the Subversion client confused. Still, almost all sites have successfully used this program without installing Mail::Sendmail. WINDOWS Copy this program into your Subversion repository's hook directory. Copy or rename the post-commit.tmpl script to post-commit.bat. Modify the post-commit.bat file to execute this script. The PATH environment will not be set when the hook executes, so you need to include both the path to your Perl interpreter and to this program: set REV=%1 set REPOS=%2 C:\Perl\bin\perl %REPOS%\hooks\svn-watch.pl -r %REV% %REPOS% UNIX, LINUX, MAC OS X, AND OTHER REAL OPERATING SYSTEMS Copy this program into your Subversion repository's hook directory. Copy or rename the post-commit.tmpl script to post-commit. Modify the post-commit script to execute this script. The PATH environment will be set to the default "/bin:/usr/bin", so if your Perl interpreter is located in "/usr/local/bin" or some other non-standard place, you'll need to put the path to your Perl's interpreter and the perl interpreter in the script: REV=$1 REPOS=$2 # If you have Perl located in F</usr/bin> or F</bin> $REPOS/hooks/svn-watch.pl -r $REV $REPOS # If you have Perl in a funky location /usr/local/bin/perl5.8 $REPOS/hooks/svn-watch.pl -r $REV $REPOS path to your Perl interpreter and to this program: DIRECTIONS The default location for the watch files is in the root of the repository under a directory called /watchers. This can be modified by using the command line parameters. However, you shouldn't put this file in under the trunk, branches, or tags directory, nor should it be placed in a module sub-directory. The user's watch file will be the user's Subversion account name followed by a suffix. The default suffix is .cfg, but again the suffix can be changed by the command line parameters. You can use the pre-commit-kitchen-sink-hook.pl program (also available from DaveCo Software and Bait Shoppe, LLC) to prevent users from editing other users' watch files. WATCH FILE LAYOUT Each line in the Watchfile is one of six formats. (There are three line types and each has a synonym). Any other line not in one of these formats is ignored. * "email = "*<User's Email Address>* * "mail = "*<User's Email Address>* * "file = "*<Ant's Glob Description of the File to Watch>* * "glob = "*<Ant's Glob Description of the File to Watch>* * "match = "*<Perl Regular Expression fo the File to Watch>* * "regex = "*<Perl Regular Expression fo the File to Watch>* The line type at the beginning of the line is case insensitive. All white space at the beginning and end of the line is also ignored as well as the white space around the equals sign. All of the following lines do the same thing: email = firstname.lastname@example.org email@example.com EMAIL = firstname.lastname@example.org EmAiL = email@example.com EmAiL= firstname.lastname@example.org The three different types of lines are: email or mail: The email address the notification is sent to. Users can have more than one email line, and a notification message will be sent to all of them. file or glob: Specifies a file to be watched. This specification is in Ant's globbing syntax which is easier and more familar than regular expressions. The globbing syntax has three parts. * A single astrisk represents zero or more characters, but only with in the directory. Thus, if you specify: file = /projects/myproj/*/*.java A watch would be placed on all Java files in the directory "/project/myproj/foo/" and in "/project/myproj/bar", but not Java files in "/project/myproj/foo/bar" since only the directories right below "/project/myproj" were specified and not any of their subdirectories. ? A question mark represents a single character. So "/project/myproj/foo/apple?.java" would place a watch on "/project/myproj/foo/apple1.java" and "/project/myproj/foo/apple2.java", but not "/project/myproj/foo/apple.java" or "/project/myproj/foo/apple12.java". ** A double astrisk represents any number of characters in any directory or subdirectory tree. "/project/myproj/foo/**/*.java" would place a watch on any Jaa file under the "/project/myproj/foo" directory tree. match or regex: This specifies a match using the full set of Perl regular expressions. Perl regular expressions are more complex than simple globs, but gives the user much more power over matching file names. For example, a single Perl regular expression can match multiple suffixes in a file. Regular expressions do not require slashes before and after, and should not be in quotes. Regular expressions are not anchored, so "foo" would match any occurance of "foo" in the file name. You can use the standard Perl anchors of "^" and "$" to anchor a regular expression at teh beginning or end of a line. For more information on Perl regular expressions, type in the following command: $ perldoc perlre NOTE: All glob expressions are anchored to the root of the repository direcotry. And, the root of the directory tree starts with a slash. Thus, merely specifying "myproj/*.java" will not put a watch on any file. However, users can specify a double at the beginning of their file specification to remove this anchoring. Thus "**/myproj/**/*.java" would place a watch on any Java file under a directory "myproj" located anywhere in the repository. WATCH FILE LINE EXAMPLES * Send an email to Bob's Acme's email address mail = email@example.com * Send an email to Bob's Cellphone pager email = firstname.lastname@example.org * Let me know when any build.xml file is modified file = **/build.xml * Let me know when someone modifies any help files glob = **/main/src/**/help/** * Let me know if someone modifies an shell script or Perl script match = \.(pl|sh|ksh|bash)$ * Let me know if someone modifies any build.xml file I suspect that some are in the format build-*.xml or build.*.xml: regex = build(-\.)\w+\.xml$ OPTIONS -r: REQUIRED This is the revision number used for the post-commit trigger and is passed as the second command line argument to the post-commit trigger. -directory: Name of the directory in the repository where the Watch files are stored. Only files stored directly under this directory will be examined as watchfiles files in sub-directories will be ignored. The default is "/watchers". -suffix: The suffix for watch files. Watch files are the same name as the subversion user ID plus the suffix. If a watch file does not have this suffix, it will be ignored. Suffixes are added to the file after a period, so you don't have to specify the beginning period. However, if you do, it will be ignored. The default is "cfg" For example, if both the default for "-directory" and "-suffix" are kept, user "bob" would have the watch file "/watchfiles/bob.cfg". -domain: The domain to add to user names if the user does not specify an email address for example, if the domain is set to "mycompany.com" and user *bob* is suppose to receive a notification message, the message will be sent to "email@example.com". -smtphost: The SMTP host used for sending email messages. -message: This is a text file that contains the message to email to users when a file they are watching is changed. Certain keywords are replaced with values taken from the notificaiton list. If you use your own message, you can include these special keywords in your own message. %AUTHOR% The name of the user who did the commit. %CHANGED% A list of all the files changed that the user is interested in. This listing is one per line. %COMMIT% The commit message made by the author at the time of the commit. NOTE: The commit message can be more than one line long. Remember that when you format your notification message. %EMAIL% The email address of the user. %REVISION% The revision of the Subverision repository. %URL% The URL used by the users to access the Subversion repository. %USER% The Subversion user ID of the user getting the notificaiton message. %WATCHFILE% The name of the user's watchfile including its full path. -sender The email address you want to appear as the sender of the notification message. Note this will be the address used if a user replies to their notification message. Default can be seen via "svn-watch.pl -help". -svnlook: The location of the "svnlook" command. The default is "/usr/bin/svnlook". -debug This is the debug level. The higher the number, the more debugging messages. The default is "0" which means no debugging informtion. -url This is the URL that the users normally use to access the Subversion repository. This is mainly used for the notification email message sent to the users. -smtpuser -smtppassword These two items are required if your SMTP server uses authorization. The "-smtpuser" is the user, the "-smtppassword)" is the password to use, and the "-smtpauth" is the authorization type needed for sending the user name and password. -subject This is the subject line that will appear on emails sent out ot watchers. Certain keywords are replaced with values taken from the notificaiton list. If you use your own subject line, you can include these special keywords in your own subject line. -noemail This option prevents users from defining their own email addresses. Apparently, someone at one of the sites that used this couldn't understand the concept that he wasn't suppose to tell other peoplw what files they were suppose to watch. If used, only the default email address will be used. *<repos>* REQUIRED: The path to the root of the Subversion repository. -help Displays a brief help message just showing the command line options. -options Displays indepth help message showing the command line and description of all the options. BUGS * There is nothing preventing a user from entering someone else's email address, and there's no easy way to catch this. We simply are trusting everyone to act professionally. * This program doesn't show the diff between the files like "svnnotify" does. * It would be nice if this program could interface somehow with svnnotify. An earlier version attempted to, but it never really worked as advertised, and made the code more difficult to read. The whole thing was removed in a later version. SEE ALSO svnnotify(1) AUTHOR David Weintraub <firstname.lastname@example.org> COPYRIGHT Copyright (c) 2011 by David Weintraub. All rights reserved. This program is covered by the open source BMAB license. The BMAB (Buy me a beer) license allows you to use all code for whatever reason you want with these three caveats: 1. If you make any modifications in the code, please consider sending them to me, so I can put them into my code. 2. Give me attribution and credit on this program. 3. If you're in town, buy me a beer. Or, a cup of coffee which is what I'd prefer. Or, if you're feeling really spendthrify, you can buy me lunch. I promise to eat with my mouth closed and to use a napkin instead of my sleeves.