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-repostiroy parameter when running the script.