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.