Introduction
============
This Perl script copies one Subversion location or set of locations to another,
in the same way as svn copy. Using the script allows more advanced operations,
in particular allowing svn:externals to be dealt with properly for branching
or tagging.
Command Line Options
====================
Run the script with no command line arguments to see all the command
line options it takes.
Dependencies
============
This script depends on module File::Temp. This became part of the standard
Perl distribution in 5.8.0. If you have an earlier version of Perl, you can
download it from CPAN at http://search.cpan.org/search?module=File::Temp .
It works with Perl versions from 5.005 onwards.
Overview
========
This script performs an svn copy command. It allows extra processing to get
around the following limitations of svn copy:
svn:externals definitions are (in Subversion 1.0 and 1.1 at least) absolute
paths. This means that an svn copy used as a branch or tag operation on a
tree with embedded svn:externals will not do what is expected. The
svn:externals will still point at the original location and will not be
pinned down.
Installation
============
Rename svncopy.pl.in to svncopy.pl.
Locate the following lines in the script:
# Specify the location of the svn command.
my $svn = '@SVN_BINDIR@/svn';
Replace @SVN_BINDIR@ with the path to your svn executable. This should be the
command you have to type to use the svn command line. If svn is on the path,
you can just set this line to:
my $svn = 'svn';
Alternatively, if you have to type /usr/local/bin/svn, you should set it to:
my $svn = '/usr/local/bin/svn';
Branching
=========
svncopy --update-externals (or svncopy --branch) will update any unversioned
svn:externals in the destination tree which point at locations within one of
the source trees so that they point to the corresponding locations within the
destination tree instead. This effectively updates the reference to
point to the destination tree, and is the behaviour you want for branching.
Tagging
=======
svncopy --pin-externals (or svncopy --tag) will update any unversioned
svn:externals in the destination tree to contain the current version of the
directory listed in the svn:externals definition. This effectively pins
the reference to the current version, and is the behaviour you want for tagging.
Note: both forms of the command leave unchanged any svn:externals which
already contain a version number.
Examples
========
These examples assume the following repository layout:
Path Last mod or svn:externals target
---- --------------------------------
trunk/ 5195
common/ 5192
common1.c 5192
common2.c 4997
inc/ 4986
common1.h 4331
common2.h 4986
proj_foo/ 5003
foo1.c 5001
foo2.c 4995
X common -r 4997 http://svn/repos/trunk/common
X inc http://svn/repos/trunk/inc
proj_bar/ 5195
bar1.c 5054
bar2.c 5195
bar2.h 5195
X common http://svn/repos/trunk/common
X inc http://svn/repos/trunk/inc
X public http://someserver/repos/public
i.e. both proj_foo and proj_bar have svn:externals set to:
common http://svn/repos/trunk/common
inc http://svn/repos/trunk/inc
with proj_foo having pinned common to version 4997.
Example 1 - using svn copy to tag (what not to do)
--------------------------------------------------
This is the naive way of creating a tag.
$ svn copy http://svn/repos/trunk/proj_bar \
http://svn/repos/tags/proj_bar/release_3.2
Result:
trunk/
[ as above]
tags/
proj_bar/
release_3.2/
bar1.c
bar2.c
bar2.h
X common http://svn/repos/trunk/common
X inc http://svn/repos/trunk/inc
X public http://someserver/repos/public
The svn:externals are still pointing to the head revisions in trunk. Any
changes in trunk/common, trunk/inc or trunk/project/inc will modify the
subdirectories in tags/proj_bar/release_3.2. This is not the desired effect.
Example 2 - using svn copy to branch (what not to do)
-----------------------------------------------------
This is the naive way of creating a branch.
$ svn copy http://svn/repos/trunk/proj_bar \
http://svn/repos/branches/proj_bar/3.2_bugfix
Result:
trunk/
[ as above]
branches/
proj_bar/
3.2_bugfix/
proj_bar/
bar1.c
bar2.c
bar2.h
X common http://svn/repos/trunk/common
X inc http://svn/repos/trunk/inc
X public http://someserver/repos/public
The svn:externals are still pointing to the head revisions in trunk. Any
changes in trunk/common, trunk/inc or trunk/project/inc will modify the
subdirectories in branches/proj_bar/3.2_bugfix/proj_bar. Worse, any
changes in these subdirectories will get propagated back to trunk. Again,
this is not the desired effect.
Example 3 - tagging properly
----------------------------
Using the script allows tags to be created which won't change.
$ perl svncopy.pl --tag http://svn/repos/trunk/proj_bar \
http://svn/repos/tags/proj_bar/release_3.2
Result:
trunk/
[ as above]
tags/
proj_bar/
release_3.2/
proj_bar/
bar1.c
bar2.c
bar2.h
X common -r 5192 http://svn/repos/trunk/common
X inc -r 4986 http://svn/repos/trunk/inc
X public -r 17753 http://someserver/repos/public
The svn:externals are pinned to the latest repository version containing a
modification to the corresponding directories. The contents of the externals
will not change.
Example 4 - tagging retrospectively
-----------------------------------
If you want to create a tag, but changes have been made since the version you
want to tag, all is not lost. Pass the revision number and the tag will be
done from there. E.g. if proj_foo should have been tagged at version 5001
(when common was at 4997), the following command will do the trick:
$ perl svncopy.pl --tag --revision 5001 http://svn/repos/trunk/proj_foo \
http://svn/repos/tags/proj_foo/release_2.7
Result:
trunk/
[ as above]
tags/
proj_foo/
release_2.7/
proj_foo/
foo1.c
foo2.c
X common -r 4997 http://svn/repos/trunk/common
X inc -r 4986 http://svn/repos/trunk/inc
The svn:externals are pinned to the latest repository version containing a
modification to the corresponding directories prior to revision 5002.
The contents of the externals will not change.
Example 5 - branching properly
------------------------------
Using the script allows branches to be created which are really independent.
$ perl svncopy.pl --branch http://svn/repos/trunk \
http://svn/repos/branches/3.2_bugfix
Result:
trunk/
[ as above]
branches/
3.2_bugfix/
trunk/
common/
common1.c
common2.c
inc/
common1.h
common2.h
proj_foo/
foo1.c
foo2.c
X common -r 4997 http://svn/repos/trunk/common
X inc http://svn/repos/branches/3.2_bugfix/trunk/inc
proj_bar/
bar1.c
bar2.c
bar2.h
X common http://svn/repos/branches/3.2_bugfix/trunk/common
X inc http://svn/repos/branches/3.2_bugfix/trunk/inc
X public http://someserver/repos/public
The svn:externals are now pointing to the corresponding directories in the
branch. The subdirectories in the branch will be unaffected by changes
in trunk, and similarly trunk will not be affected by changes in the branch.
Note: proj_foo/common was pinned to revision 4997 in trunk. Because of this
the script has left it unchanged.
Example 6 - branching part of a tree
------------------------------------
If you don't want to branch the whole tree, you can just branch the directories
which contain your project:
$ perl svncopy.pl --branch http://svn/repos/trunk/common \
http://svn/repos/trunk/inc \
http://svn/repos/trunk/proj_bar \
http://svn/repos/branches/3.2_bugfix
Result:
trunk/
[ as above]
branches/
3.2_bugfix/
common/
common1.c
common2.c
inc/
common1.h
common2.h
proj_bar/
bar1.c
bar2.c
bar2.h
X common http://svn/repos/branches/3.2_bugfix/common
X inc http://svn/repos/branches/3.2_bugfix/inc
X public http://someserver/repos/public
The svn:externals are now pointing to the corresponding directories in
the branch, as in Example 4.
Note: you *must* branch all affected directories simultaneously. If you
branch them one at a time, the script will not know which externals refer
to other components of the same project, and will leave them unchanged.
Testing svncopy.pl
==================
svncopy.pl comes with a script to do some basic testing, called testsvncopy.pl.
Installation is similar to svncopy.pl - update @SVN_BINDIR@. You also have to
supply a scratch repository location for the test script to use. Either update
@SVN_TEST_REPOSITORY@ in testsvncopy.pl.in or pass in the location using the
--test-repository parameter when running the script.