SVN::N...:Mirror(3pm)

💖 SVN::N...:Mirror(3pm) — bestie edition 💖

okay so you found the manual page for SVN::N...:Mirror(3pm), part of the User Contributed Perl Documentation collection, and honestly? she's a baddie. let's get into it 🫶

---

✨ NAME ✨

SVN::Notify::Mirror — keep a mirrored working copy of a repository path. that's it, that's the girl. 🪞

---

✨ SYNOPSIS ✨

slap svnnotify into your post-commit hook like this:

svnnotify --repos-path "$1" --revision "$2" \
 --handler Mirror --to "/path/to/www/htdocs" \
 [--svn-binary /full/path/to/svn] \
 [--tag-regex "regex"]
 [--minimal]

orrrr — and this is the glow-up move — use SVN::Notify::Config for a way 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 ✨

the whole serve of this module: keep a directory in sync with a portion of a Subversion repository. 💅

the classic use case is keeping a development web server in sync with the changes people make to the repo. and here's the tea — that directory can live on the same box as the repository itself, or it can be remote (via an SSH connection). either way, she ate.

---

✨ USAGE ✨

so depending on whether your target is a "Local Mirror" or a Remote Mirror"... okay that's Remote Mirror — there are different options available for each. and every single option works either as a commandline option to svnnotify or as a hash key in SVN::Notify::Config (go check their respective docs for more deets, bestie).

🌸 Common Options 🌸

on top of all the options available to svnnotify, there's exactly one 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 gets 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, say 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. that's 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're 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 — that's the user identity that is running Apache or svnserve respectively. no cap. 🙈

🌸 Local Mirror 🌸

used for directories local to the repository itself (NFS or other network mounted drives count, bestie, we don't gatekeep). 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). this is your sign fr fr 💀

🌸 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. iconic behaviour tbh.

• 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). lowkey convenient ✨

---

✨ 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

---

and that's the whole page, bestie 🫶 this one's running on perl v5.34.0 and was dated 2022-06-17 — go forth and mirror, you absolute main character 💖✨🌈