README.mkd

   1 svn2svn
   2 =======
   3 Replicate (replay) changesets from one Subversion repository to another.
   4
   5 Features
   6 --------
   7 - **Meant for replaying history into an "empty target location**. This could be
   8   an empty target repo or simply an empty folder/branch in the target repo.
   9 - **Maintains logical history (ancestry) when possible**, e.g. uses "svn copy"
  10   for renames.
  11 - **Maintains original commit messages**.
  12 - **Optionally maintain source commit authors (`svn:author`) and commit timestamps
  13   (`svn:date`)**.  Requires a "pre-revprop-change" hook script in the target
  14   repo, to be able to change the "`svn:author`" and "`svn:date`" revprops after
  15   target commits have been made.
  16 - **Optionally maintain identical revision #'s between source vs. target repo**.
  17   Effectively requires that you're replaying into an empty target repo,
  18   or rather that the first source repo revision to be replayed is less than
  19   the last target repo revision. Create blank "padding" revisions in the target
  20   repo as needed.
  21 - **Optionally run an external shell script before each replayed commit**,
  22   to give the ability to dynamically exclude or modify files as part
  23   of the replay.
  24
  25 Requirements
  26 ------------
  27 - **Python 2.6** or higher.
  28 - **Subversion 1.6** or higher.
  29 - Written for a UNIX-type environment, e.g. Linux, Mac OSX, etc. For
  30   Windows-based usage, recommend using [Cygwin](http://www.cygwin.com/) for
  31   best compatibility.
  32
  33 Overview
  34 --------
  35 This is a utility for replicating the revision history from a source path in
  36 a source SVN repository to a target path in a target SVN repository. In other
  37 words, it "replays the history" of a given source SVN repository/branch/path
  38 into a target SVN repository/branch/path.
  39
  40 This can be useful to create filtered version of a source SVN repository. For
  41 example, say that you have a huge SVN repository with a _lot_ of old branch
  42 history which is taking up a lot of disk-space and not serving a lot of purpose
  43 going forward.  You can this utility to replay/filter just the "/trunk" SVN
  44 history into a new repository, so that things like "svn log" and "svn blame"
  45 will still show the correct (logical) history/ancestry, even though we end-up
  46 generating new commits which will have newer commit-dates and revision #'s
  47 (_though this script can optionally maintain the original commit-dates and
  48 revision #'s if desired_).
  49
  50 While this replay process will obviously run faster if you're running between
  51 both a local source and target repositories, none of this *requires* direct
  52 access to the repo server. You could access both the source and target repo's
  53 over standard `http://`, `svn://`, `svn+ssh://`, etc. methods.
  54
  55 Usage
  56 -----
  57 See `svn2svn.py --help`:
  58
  59     $ ./svn2svn.py --help
  60     svn2svn, version 1.5.0
  61     <http://nynim.org/projects/svn2svn> <https://github.com/tonyduckles/svn2svn>
  62
  63     Usage: svn2svn.py [OPTIONS] source_url target_url
  64
  65     Replicate (replay) history from one SVN repository to another. Maintain
  66     logical ancestry wherever possible, so that 'svn log' on the replayed repo
  67     will correctly follow file/folder renames.
  68
  69     Examples:
  70       Create a copy of only /trunk from source repo, starting at r5000
  71       $ svnadmin create /svn/target
  72       $ svn mkdir -m 'Add trunk' file:///svn/target/trunk
  73       $ svn2svn -av -r 5000 http://server/source/trunk file:///svn/target/trunk
  74         1. The target_url will be checked-out to ./_wc_target
  75         2. The first commit to http://server/source/trunk at/after r5000 will be
  76            exported & added into _wc_target
  77         3. All revisions affecting http://server/source/trunk (starting at r5000)
  78            will be replayed to _wc_target. Any add/copy/move/replaces that are
  79            copy-from'd some path outside of /trunk (e.g. files renamed on a
  80            /branch and branch was merged into /trunk) will correctly maintain
  81            logical ancestry where possible.
  82
  83       Use continue-mode (-c) to pick-up where the last run left-off
  84       $ svn2svn -avc http://server/source/trunk file:///svn/target/trunk
  85         1. The target_url will be checked-out to ./_wc_target, if not already
  86            checked-out
  87         2. All new revisions affecting http://server/source/trunk starting from
  88            the last replayed revision to file:///svn/target/trunk (based on the
  89            svn2svn:* revprops) will be replayed to _wc_target, maintaining all
  90            logical ancestry where possible.
  91
  92     Options:
  93           --version       show program's version number and exit
  94       -h, --help          show this help message and exit
  95       -v, --verbose       enable additional output (use -vv or -vvv for more)
  96       -a, --archive       archive/mirror mode; same as -UDP (see REQUIRE's below)
  97                           maintain same commit author, same commit time, and
  98                           file/dir properties
  99       -U, --keep-author   maintain same commit authors (svn:author) as source
 100                           (REQUIRES 'pre-revprop-change' hook script to allow
 101                           'svn:author' changes)
 102       -D, --keep-date     maintain same commit time (svn:date) as source
 103                           (REQUIRES 'pre-revprop-change' hook script to allow
 104                           'svn:date' changes)
 105       -P, --keep-prop     maintain same file/dir SVN properties as source
 106       -R, --keep-revnum   maintain same rev #'s as source. creates placeholder
 107                           target revisions (by modifying a 'svn2svn:keep-revnum'
 108                           property at the root of the target repo)
 109       -c, --continue      continue from last source commit to target (based on
 110                           svn2svn:* revprops)
 111       -f, --force         allow replaying into a non-empty target folder
 112       -r, --revision=ARG  revision range to replay from source_url
 113                           A revision argument can be one of:
 114                              START        start rev # (end will be 'HEAD')
 115                              START:END    start and ending rev #'s
 116                           Any revision # formats which SVN understands are
 117                           supported, e.g. 'HEAD', '{2010-01-31}', etc.
 118       -u, --log-author    append source commit author to replayed commit mesages
 119       -d, --log-date      append source commit time to replayed commit messages
 120       -l, --limit=NUM     maximum number of source revisions to process
 121       -n, --dry-run       process next source revision but don't commit changes to
 122                           target working-copy (forces --limit=1)
 123       -x, --verify        verify ancestry and content for changed paths in commit
 124                           after every target commit or last target commit
 125       -X, --verify-all    verify ancestry and content for entire target_url tree
 126                           after every target commit or last target commit
 127           --debug         enable debugging output (same as -vvv)
 128
 129 Side Effects
 130 ------------
 131 - The source repo is treated as strictly read-only. We do log/info/export/etc.
 132   actions from the source repo, to get the history to replay and to get the
 133   file contents at each step along teh way.
 134 - You must have commit access to the target repo. Additionally, for some of
 135   the optional command-line args, you'll need access to the target repo to
 136   setup hook scripts, e.g. "pre-revprop-change".
 137 - This script will create some folders off of your current working directory:
 138   - "`_wc_target`": This is the checkout of the target\_url, where we replay
 139     actions into and where we commit to the target repo. You can safely
 140     remove this directory after a run, and the script will do a fresh
 141     "svn checkout" (if needed) when starting the next time.
 142   - "`_wc_target_tmp`": This is a temporary folder, which will only be created
 143     if using `--keep-revnum` mode and it should only exist for brief periods
 144     of time. This is where we commit dummy/padding revisions to the target repo,
 145     checking out the root folder of the target repo and modifying a
 146     "`svn2svn:keep-revnum`" property, i.e. a small change to trigger a commit
 147     and in a location that will likely go un-noticed in the final target repo.
 148
 149 Examples
 150 --------
 151 **Create a copy of only /trunk from source repo, starting at r5000**
 152
 153     $ svnadmin create /svn/target
 154     $ svn mkdir -m 'Add trunk' file:///svn/target/trunk
 155     $ svn2svn -av -r 5000 http://server/source/trunk file:///svn/target/trunk
 156
 157 1. The `target_url` will be checked-out to `./_wc_target`.
 158 2. The first commit to `http://server/source/trunk` at/after r5000 will be
 159    exported & added into `_wc_target`.
 160 3. All revisions affecting `http://server/source/trunk` (starting at r5000)
 161    will be replayed to `_wc_target`. Any add/copy/move/replaces that are
 162    copy-from'd some path outside of /trunk (e.g. files renamed on a
 163    /branch and branch was merged into /trunk) will correctly maintain
 164    logical ancestry where possible.
 165
 166 **Use continue-mode (-c) to pick-up where the last run left-off**
 167
 168     $ svn2svn -avc http://server/source/trunk file:///svn/target/trunk
 169
 170 1. The `target_url` will be checked-out to `./_wc_target`, if not already
 171    checked-out
 172 2. All new revisions affecting `http://server/source/trunk` starting from
 173    the last replayed revision to `file:///svn/target/trunk` (based on the
 174    "`svn2svn:*`" revprops) will be replayed to `_wc_target`, maintaining all
 175    logical ancestry where possible.
 176
 177 Credits
 178 -------
 179 This project borrows a lot of code from the "hgsvn" project.  Many thanks to
 180 the folks who have contributed to the hgsvn project, for writing code that is
 181 easily re-usable:
 182
 183 * [http://pypi.python.org/pypi/hgsvn](http://pypi.python.org/pypi/hgsvn)
 184 * [https://bitbucket.org/andialbrecht/hgsvn/overview](https://bitbucket.org/andialbrecht/hgsvn/overview)
 185
 186 This project was originally inspired by this "svn2svn" project:
 187 [http://code.google.com/p/svn2svn/](http://code.google.com/p/svn2svn/)
 188 That project didn't fully meet my needs, so I forked and ended-up rewriting
 189 the majority of the code.
 190
 191 Links
 192 -----
 193 * Introduction: "**[svn2svn: Replaying SVN History](http://nynim.org/blog/2012/02/01/svn2svn-replaying-svn-history/)**"
 194 * Project page: [http://nynim.org/projects/svn2svn](http://nynim.org/projects/svn2svn)
 195 * Source code @ Github: [https://github.com/tonyduckles/svn2svn](https://github.com/tonyduckles/svn2svn)
 196 * Source code @ git.nynim.org [http://git.nynim.org/svn2svn.git](http://git.nynim.org/svn2svn.git)