.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SVN::Notify::Mirror 3pm"
.TH SVN::Notify::Mirror 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SVN::Notify::Mirror \- Keep a mirrored working copy of a repository path
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Use \fIsvnnotify\fR in \fIpost-commit\fR:
.PP
.Vb 5
\& svnnotify \-\-repos\-path "$1" \-\-revision "$2" \e
\& \-\-handler Mirror \-\-to "/path/to/www/htdocs" \e
\& [\-\-svn\-binary /full/path/to/svn] \e
\& [\-\-tag\-regex "regex"]
\& [\-\-minimal]
.Ve
.PP
or better yet, use SVN::Notify::Config for a more
sophisticated setup:
.PP
.Vb 10
\& #!/usr/bin/perl \-MSVN::Notify::Config=$0
\& \-\-\- #YAML:1.0
\& \*(Aq\*(Aq:
\& PATH: "/usr/bin:/usr/local/bin"
\& \*(Aqpath/in/repository\*(Aq:
\& handler: Mirror
\& minimal: 1
\& to: "/path/to/www/htdocs"
\& \*(Aqsome/other/path/in/repository\*(Aq:
\& handler: Mirror
\& to: "/path/to/remote/www/htdocs"
\& \*(Aqsome/project/tags\*(Aq:
\& handler: Mirror
\& to: "/path/to/another/dir"
\& tag\-regex: "TRUNK\-"
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1SSH\s0 connection).
.SH "USAGE"
.IX Header "USAGE"
Depending on whether the target is a \*(L"Local Mirror\*(R" 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).
.SS "Common Options"
.IX Subsection "Common Options"
In addition to all of the options available to svnnotify, there is a
single global option that affects both \*(L"Local Mirror\*(R" and Remote
Mirror targets:
.IP "minimal" 4
.IX Item "minimal"
If the \f(CW\*(C`\-\-minimal\*(C'\fR 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:
.Sp
.Vb 4
\& 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
.Ve
.Sp
\&\fBand\fR the checked-out mirror was in \f(CW\*(C`/path/to/www/htdocs\*(C'\fR, then the
update would be executed in the \f(CW\*(C`/path/to/www/htdocs/subdir\*(C'\fR directory.
This is the shorted common path of the updated files.
.Sp
\&\s-1NOTE:\s0 when using the SVN::Notify::Config mode, the matching path (in the
above example \f(CW\*(C`path/in/repository\*(C'\fR) is stripped off of the shortest
common path prior to appending that to the destination path (the \f(CW\*(C`to:\*(C'\fR
key). It is assumed that a matching key is the \*(L"root\*(R" of the working
copy.
.SS "Working Copy on Mirror"
.IX Subsection "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:
.PP
.Vb 6
\& # Disallow browsing of Subversion working copy
\& # administrative directories.
\&
\& Order deny,allow
\& Deny from all
\&
.Ve
.PP
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).
.SS "Local Mirror"
.IX Subsection "Local Mirror"
Used for directories local to the repository itself (\s-1NFS\s0 or other
network mounted drives count). The only required options are:
.IP "\(bu" 4
handler = Mirror
.Sp
Specifies that this module is called to process the Notify event.
.IP "\(bu" 4
to = /path/to/working/copy
.Sp
Specified which directory should be updated.
.SS "Remote Mirror"
.IX Subsection "Remote Mirror"
Used for mirrors on some other box, e.g. a web server in a \s-1DMZ\s0
network. See SVN::Notify::Mirror::SSH or SVN::Notify::Mirror::Rsync
for more details. All \f(CW\*(C`ssh\-*\*(C'\fR 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).
.SS "Methods of Mirroring"
.IX Subsection "Methods of Mirroring"
There are two schemes to keep a directory synced to a path in the
repository:
.IP "1. Update a checked out working copy" 4
.IX Item "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.
.IP "2. Switch a working copy to a new tag" 4
.IX Item "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.
.PP
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.
.IP "\(bu" 4
tag-regex
.Sp
This optional parameter works with any \*(L"Local Mirror\*(R" or \*(L"Remote Mirror\*(R",
using any of the applicable transfer methods (currently local, \s-1SSH,\s0 or
Rsync). The \f(CW\*(C`\-\-tag\-regex\*(C'\fR 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.
.Sp
For example, using a SVN::Notify::Config file (which is the most useful
way to employ this option):
.Sp
.Vb 11
\& #!/usr/bin/perl \-MSVN::Notify::Config=$0
\& \-\-\- #YAML:1.0
\& \*(Aq\*(Aq:
\& PATH: "/usr/bin:/usr/local/bin"
\& \*(Aqproject1/trunk\*(Aq:
\& handler: Mirror
\& to: "/path/to/test/htdocs"
\& \*(Aqproject1/tags\*(Aq:
\& handler: Mirror
\& to: "/path/to/production/htdocs"
\& tag\-regex: "TRUNK\-"
.Ve
.Sp
This would have the effect of keeping the path \f(CW\*(C`/path/to/test/htdocs\*(C'\fR
in sync on every commit, but \f(CW\*(C`/path/to/production/htdocs\*(C'\fR would be
switched only when a tag was created in \f(CW\*(C`project1/tags\*(C'\fR that matched
the string \f(CW\*(C`TRUNK\-\*(C'\fR. \fB\s-1NOTE:\s0\fR this is not a sophisticated regex; in
particular you should not employ anchors, since the \s-1URL\s0 is not split
into repos-root and path segments before testing.
.Sp
To initialize the switch directory, you must perform an initial
checkout like this:
.Sp
.Vb 1
\& $ svn checkout file://$REPOS/project1/tags/TRUNK\-0_0_1
.Ve
.Sp
where \f(CW\*(C`TRUNK\-0_0_1\*(C'\fR is the name of any path in the \f(CW\*(C`.../tags/\*(C'\fR
folder.
.SH "PREREQUISITES (Optional and otherwise)"
.IX Header "PREREQUISITES (Optional and otherwise)"
The only mandatory prerequisite is SVN::Notify (obviously), but the
presence of several other modules will enable other features:
.IP "SVN::Notify::Config" 4
.IX Item "SVN::Notify::Config"
Permits a \s-1YAML\s0 config file to be used as the entire postcommit script, like
the second example in the \s-1SYNOPSIS\s0 above.
.IP "Net::SSH" 4
.IX Item "Net::SSH"
Required to use \s-1SSH\s0 to update a remote working copy. See
SVN::Notify::Mirror::SSH for usage of that transport method.
.IP "File::Rsync" 4
.IX Item "File::Rsync"
Required to use rsync to update a remote working copy See
SVN::Notify::Mirror::RSync for usage of that transport method..
.PP
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).
.SH "AUTHOR"
.IX Header "AUTHOR"
John Peacock
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2008 John Peacock
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
SVN::Notify, SVN::Notify::Config