NAME¶
SVN::Notify::Mirror - Keep a mirrored working copy of a repository path
SYNOPSIS¶
Use
svnnotify in
post-commit:
svnnotify --repos-path "$1" --revision "$2" \
--handler Mirror --to "/path/to/www/htdocs" \
[--svn-binary /full/path/to/svn] \
[--tag-regex "regex"]
[--minimal]
or better yet, use SVN::Notify::Config for a more sophisticated setup:
#!/usr/bin/perl -MSVN::Notify::Config=$0
--- #YAML:1.0
'':
PATH: "/usr/bin:/usr/local/bin"
'path/in/repository':
handler: Mirror
minimal: 1
to: "/path/to/www/htdocs"
'some/other/path/in/repository':
handler: Mirror
to: "/path/to/remote/www/htdocs"
'some/project/tags':
handler: Mirror
to: "/path/to/another/dir"
tag-regex: "TRUNK-"
DESCRIPTION¶
Keep a directory in sync with a portion of a Subversion repository. Typically
used to keep a development web server in sync with the changes made to the
repository. This directory can either be on the same box as the repository
itself, or it can be remote (via SSH connection).
USAGE¶
Depending on whether the target is a "Local Mirror" or a Remote
Mirror, there are different options available. All options are available
either as a commandline option to svnnotify or as a hash key in
SVN::Notify::Config (see their respective documentation for more details).
Common Options¶
In addition to all of the options available to svnnotify, there is a single
global option that affects both "Local Mirror" and Remote Mirror
targets:
- minimal
- If the "--minimal" flag is passed on the commandline (or a hash
entry created in a config file), then the update will occur at the
shortest common path of all files/dirs that are changed for that revision.
For example, using the example config file above, the following changes
occured in rev 23:
Changed paths:
M path/in/repository/subdir/subdir2/file.1
A path/in/repository/subdir/file.2
M path/in/repository/subdir/subdir3/file.3
and the checked-out mirror was in "/path/to/www/htdocs",
then the update would be executed in the
"/path/to/www/htdocs/subdir" directory. This is the shorted
common path of the updated files.
NOTE: when using the SVN::Notify::Config mode, the matching path (in the
above example "path/in/repository") is stripped off of the
shortest common path prior to appending that to the destination path (the
"to:" key). It is assumed that a matching key is the
"root" of the working copy.
Working Copy on Mirror¶
Because 'svn export' is not able to be consistently updated, the sync'd
directory must be a full working copy, and if you are running Apache, you
should add lines like the following to your Apache configuration file:
# Disallow browsing of Subversion working copy
# administrative directories.
<DirectoryMatch "^/.*/\.svn/">
Order deny,allow
Deny from all
</DirectoryMatch>
The files in the working copy must be writeable (preferrably owned) by the user
identity executing the hook script (this is the user identity that is running
Apache or svnserve respectively).
Local Mirror¶
Used for directories local to the repository itself (NFS or other network
mounted drives count). The only required options are:
- •
- handler = Mirror
Specifies that this module is called to process the Notify event.
- •
- to = /path/to/working/copy
Specified which directory should be updated.
Remote Mirror¶
Used for mirrors on some other box, e.g. a web server in a DMZ network. See
SVN::Notify::Mirror::SSH or SVN::Notify::Mirror::Rsync for more details. All
"ssh-*" options are now deprecated in the base class and support for
them will be removed in the next major release. Please update your
configurations (see SVN::Notify::Mirror::SSH for details).
Methods of Mirroring¶
There are two schemes to keep a directory synced to a path in the repository:
- 1. Update a checked out working copy
- This is the normal mode of operation and is commonly used to keep a test
web server in sync with the repository on every commit.
- 2. Switch a working copy to a new tag
- This is the preferred method when you want to keep a production web server
up to date with only specific revisions, through the use of smart
tagging.
For the latter case, SVN::Notify::Mirror can be configured to monitor a path in
the repository and only trigger an update when the path matches a specific
regular expression, and do so by switching the mirrored path to the new tag.
- •
- tag-regex
This optional parameter works with any "Local Mirror" or
"Remote Mirror", using any of the applicable transfer methods
(currently local, SSH, or Rsync). The "--tag-regex" parameter
takes a string which will be interpreted as a conventional Perl regex, and
only those repository paths which match the regex will be updated. The
regex also determines what the mirrored directory will be switched to.
For example, using a SVN::Notify::Config file (which is the most useful way
to employ this option):
#!/usr/bin/perl -MSVN::Notify::Config=$0
--- #YAML:1.0
'':
PATH: "/usr/bin:/usr/local/bin"
'project1/trunk':
handler: Mirror
to: "/path/to/test/htdocs"
'project1/tags':
handler: Mirror
to: "/path/to/production/htdocs"
tag-regex: "TRUNK-"
This would have the effect of keeping the path
"/path/to/test/htdocs" in sync on every commit, but
"/path/to/production/htdocs" would be switched only when a tag
was created in "project1/tags" that matched the string
"TRUNK-". NOTE: this is not a sophisticated regex; in
particular you should not employ anchors, since the URL is not split into
repos-root and path segments before testing.
To initialize the switch directory, you must perform an initial checkout
like this:
$ svn checkout file://$REPOS/project1/tags/TRUNK-0_0_1
where "TRUNK-0_0_1" is the name of any path in the
".../tags/" folder.
PREREQUISITES (Optional and otherwise)¶
The only mandatory prerequisite is SVN::Notify (obviously), but the presence of
several other modules will enable other features:
- SVN::Notify::Config
- Permits a YAML config file to be used as the entire postcommit script,
like the second example in the SYNOPSIS above.
- Net::SSH
- Required to use SSH to update a remote working copy. See
SVN::Notify::Mirror::SSH for usage of that transport method.
- File::Rsync
- Required to use rsync to update a remote working copy See
SVN::Notify::Mirror::RSync for usage of that transport method..
If you install any of these modules after installing SVN::Notify::Mirror, those
features will be available immediately (though you can rerun the install in
order to see the tests).
AUTHOR¶
John Peacock <jpeacock@cpan.org>
COPYRIGHT¶
Copyright (c) 2005-2008 John Peacock
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this
module.
SEE ALSO¶
SVN::Notify, SVN::Notify::Config
POD ERRORS¶
Hey!
The above document had some coding errors, which are explained
below:
- Around line 275:
- You forgot a '=back' before '=head2'