contrib/client-side/svncopy/svncopy.README

   1 Introduction
   2 ============
   3
   4 This Perl script copies one Subversion location or set of locations to another,
   5 in the same way as svn copy.  Using the script allows more advanced operations,
   6 in particular allowing svn:externals to be dealt with properly for branching
   7 or tagging.
   8
   9 Command Line Options
  10 ====================
  11
  12 Run the script with no command line arguments to see all the command
  13 line options it takes.
  14
  15 Dependencies
  16 ============
  17
  18 This script depends on module File::Temp.  This became part of the standard
  19 Perl distribution in 5.8.0.  If you have an earlier version of Perl, you can
  20 download it from CPAN at http://search.cpan.org/search?module=File::Temp .
  21 It works with Perl versions from 5.005 onwards.
  22
  23 Overview
  24 ========
  25
  26 This script performs an svn copy command.  It allows extra processing to get
  27 around the following limitations of svn copy:
  28
  29   svn:externals definitions are (in Subversion 1.0 and 1.1 at least) absolute
  30   paths.  This means that an svn copy used as a branch or tag operation on a
  31   tree with embedded svn:externals will not do what is expected.  The
  32   svn:externals will still point at the original location and will not be
  33   pinned down.
  34
  35 Installation
  36 ============
  37
  38 Rename svncopy.pl.in to svncopy.pl.
  39
  40 Locate the following lines in the script:
  41
  42     # Specify the location of the svn command.
  43     my $svn = '@SVN_BINDIR@/svn';
  44
  45 Replace @SVN_BINDIR@ with the path to your svn executable.  This should be the
  46 command you have to type to use the svn command line.  If svn is on the path,
  47 you can just set this line to:
  48
  49     my $svn = 'svn';
  50
  51 Alternatively, if you have to type /usr/local/bin/svn, you should set it to:
  52
  53     my $svn = '/usr/local/bin/svn';
  54
  55 Branching
  56 =========
  57
  58 svncopy --update-externals (or svncopy --branch) will update any unversioned
  59 svn:externals in the destination tree which point at locations within one of
  60 the source trees so that they point to the corresponding locations within the
  61 destination tree instead.  This effectively updates the reference to
  62 point to the destination tree, and is the behaviour you want for branching.
  63
  64 Tagging
  65 =======
  66
  67 svncopy --pin-externals (or svncopy --tag) will update any unversioned
  68 svn:externals in the destination tree to contain the current version of the
  69 directory listed in the svn:externals definition.  This effectively pins
  70 the reference to the current version, and is the behaviour you want for tagging.
  71
  72 Note: both forms of the command leave unchanged any svn:externals which
  73 already contain a version number.
  74
  75 Examples
  76 ========
  77
  78 These examples assume the following repository layout:
  79
  80 Path                Last mod or svn:externals target
  81 ----                --------------------------------
  82 trunk/              5195
  83     common/         5192
  84         common1.c   5192
  85         common2.c   4997
  86     inc/            4986
  87         common1.h   4331
  88         common2.h   4986
  89     proj_foo/       5003
  90         foo1.c      5001
  91         foo2.c      4995
  92         X common    -r 4997 http://svn/repos/trunk/common
  93         X inc       http://svn/repos/trunk/inc
  94     proj_bar/       5195
  95         bar1.c      5054
  96         bar2.c      5195
  97         bar2.h      5195
  98         X common    http://svn/repos/trunk/common
  99         X inc       http://svn/repos/trunk/inc
 100         X public    http://someserver/repos/public
 101
 102 i.e. both proj_foo and proj_bar have svn:externals set to:
 103
 104 common    http://svn/repos/trunk/common
 105 inc       http://svn/repos/trunk/inc
 106
 107 with proj_foo having pinned common to version 4997.
 108
 109 Example 1 - using svn copy to tag (what not to do)
 110 --------------------------------------------------
 111
 112 This is the naive way of creating a tag.
 113
 114 $ svn copy http://svn/repos/trunk/proj_bar \
 115             http://svn/repos/tags/proj_bar/release_3.2
 116
 117 Result:
 118
 119 trunk/
 120     [ as above]
 121 tags/
 122     proj_bar/
 123         release_3.2/
 124             bar1.c
 125             bar2.c
 126             bar2.h
 127             X common    http://svn/repos/trunk/common
 128             X inc       http://svn/repos/trunk/inc
 129             X public    http://someserver/repos/public
 130
 131 The svn:externals are still pointing to the head revisions in trunk.  Any
 132 changes in trunk/common, trunk/inc or trunk/project/inc will modify the
 133 subdirectories in tags/proj_bar/release_3.2.  This is not the desired effect.
 134
 135 Example 2 - using svn copy to branch (what not to do)
 136 -----------------------------------------------------
 137
 138 This is the naive way of creating a branch.
 139
 140 $ svn copy http://svn/repos/trunk/proj_bar \
 141             http://svn/repos/branches/proj_bar/3.2_bugfix
 142
 143 Result:
 144
 145 trunk/
 146     [ as above]
 147 branches/
 148     proj_bar/
 149         3.2_bugfix/
 150             proj_bar/
 151                 bar1.c
 152                 bar2.c
 153                 bar2.h
 154                 X common    http://svn/repos/trunk/common
 155                 X inc       http://svn/repos/trunk/inc
 156                 X public    http://someserver/repos/public
 157
 158 The svn:externals are still pointing to the head revisions in trunk.  Any
 159 changes in trunk/common, trunk/inc or trunk/project/inc will modify the
 160 subdirectories in branches/proj_bar/3.2_bugfix/proj_bar.  Worse, any
 161 changes in these subdirectories will get propagated back to trunk.  Again,
 162 this is not the desired effect.
 163
 164 Example 3 - tagging properly
 165 ----------------------------
 166
 167 Using the script allows tags to be created which won't change.
 168
 169 $ perl svncopy.pl --tag http://svn/repos/trunk/proj_bar \
 170             http://svn/repos/tags/proj_bar/release_3.2
 171
 172 Result:
 173
 174 trunk/
 175     [ as above]
 176 tags/
 177     proj_bar/
 178         release_3.2/
 179             proj_bar/
 180                 bar1.c
 181                 bar2.c
 182                 bar2.h
 183                 X common    -r 5192 http://svn/repos/trunk/common
 184                 X inc       -r 4986 http://svn/repos/trunk/inc
 185                 X public    -r 17753 http://someserver/repos/public
 186
 187 The svn:externals are pinned to the latest repository version containing a
 188 modification to the corresponding directories.  The contents of the externals
 189 will not change.
 190
 191 Example 4 - tagging retrospectively
 192 -----------------------------------
 193
 194 If you want to create a tag, but changes have been made since the version you
 195 want to tag, all is not lost.  Pass the revision number and the tag will be
 196 done from there.  E.g. if proj_foo should have been tagged at version 5001
 197 (when common was at 4997), the following command will do the trick:
 198
 199 $ perl svncopy.pl --tag --revision 5001 http://svn/repos/trunk/proj_foo \
 200             http://svn/repos/tags/proj_foo/release_2.7
 201
 202 Result:
 203
 204 trunk/
 205     [ as above]
 206 tags/
 207     proj_foo/
 208         release_2.7/
 209             proj_foo/
 210                 foo1.c
 211                 foo2.c
 212                 X common    -r 4997 http://svn/repos/trunk/common
 213                 X inc       -r 4986 http://svn/repos/trunk/inc
 214
 215 The svn:externals are pinned to the latest repository version containing a
 216 modification to the corresponding directories prior to revision 5002.
 217 The contents of the externals will not change.
 218
 219 Example 5 - branching properly
 220 ------------------------------
 221
 222 Using the script allows branches to be created which are really independent.
 223
 224 $ perl svncopy.pl --branch http://svn/repos/trunk \
 225             http://svn/repos/branches/3.2_bugfix
 226
 227 Result:
 228
 229 trunk/
 230     [ as above]
 231 branches/
 232     3.2_bugfix/
 233         trunk/
 234             common/
 235                 common1.c
 236                 common2.c
 237             inc/
 238                 common1.h
 239                 common2.h
 240             proj_foo/
 241                 foo1.c
 242                 foo2.c
 243                 X common    -r 4997 http://svn/repos/trunk/common
 244                 X inc       http://svn/repos/branches/3.2_bugfix/trunk/inc
 245             proj_bar/
 246                 bar1.c
 247                 bar2.c
 248                 bar2.h
 249                 X common    http://svn/repos/branches/3.2_bugfix/trunk/common
 250                 X inc       http://svn/repos/branches/3.2_bugfix/trunk/inc
 251                 X public    http://someserver/repos/public
 252
 253 The svn:externals are now pointing to the corresponding directories in the
 254 branch.  The subdirectories in the branch will be unaffected by changes
 255 in trunk, and similarly trunk will not be affected by changes in the branch.
 256
 257 Note: proj_foo/common was pinned to revision 4997 in trunk.  Because of this
 258 the script has left it unchanged.
 259
 260 Example 6 - branching part of a tree
 261 ------------------------------------
 262
 263 If you don't want to branch the whole tree, you can just branch the directories
 264 which contain your project:
 265
 266 $ perl svncopy.pl --branch http://svn/repos/trunk/common \
 267             http://svn/repos/trunk/inc \
 268             http://svn/repos/trunk/proj_bar \
 269             http://svn/repos/branches/3.2_bugfix
 270
 271 Result:
 272
 273 trunk/
 274     [ as above]
 275 branches/
 276     3.2_bugfix/
 277         common/
 278             common1.c
 279             common2.c
 280         inc/
 281             common1.h
 282             common2.h
 283         proj_bar/
 284             bar1.c
 285             bar2.c
 286             bar2.h
 287             X common    http://svn/repos/branches/3.2_bugfix/common
 288             X inc       http://svn/repos/branches/3.2_bugfix/inc
 289             X public    http://someserver/repos/public
 290
 291 The svn:externals are now pointing to the corresponding directories in
 292 the branch, as in Example 4.
 293
 294 Note: you *must* branch all affected directories simultaneously.  If you
 295 branch them one at a time, the script will not know which externals refer
 296 to other components of the same project, and will leave them unchanged.
 297
 298 Testing svncopy.pl
 299 ==================
 300
 301 svncopy.pl comes with a script to do some basic testing, called testsvncopy.pl.
 302 Installation is similar to svncopy.pl - update @SVN_BINDIR@.  You also have to
 303 supply a scratch repository location for the test script to use.  Either update
 304 @SVN_TEST_REPOSITORY@ in testsvncopy.pl.in or pass in the location using the
 305 --test-repository parameter when running the script.