SVN::Notify::Mirror - Keep a mirrored working copy of a repository path

       John Peacock <jpeacock@cpan.org>

       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.

       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).

       SVN::Notify::Mirror - Keep a mirrored working copy of a repository path

       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).

       SVN::Notify, SVN::Notify::Config

perl v5.34.0                                       2022-06-17                           SVN::Notify::Mirror(3pm)

       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-"

       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).

   CommonOptions
       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.

   WorkingCopyonMirror
       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).

   LocalMirror
       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.

   RemoteMirror
       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).

   MethodsofMirroring
       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.