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 `svnreplay.py --help`:
  58
  59     $ ./svnreplay.py --help
  60     svn2svn, version 1.6.0
  61     <http://nynim.org/projects/svn2svn> <https://github.com/tonyduckles/svn2svn>
  62
  63     Usage: svnreplay.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       $ svnreplay -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       $ svnreplay -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 REQUIRES
  97                             below).
  98                             Maintain same commit author, same commit time, and
  99                             file/dir properties.
 100       -U, --keep-author     Maintain same commit authors (svn:author) as source.
 101                             (REQUIRES 'pre-revprop-change' hook script to allow
 102                             'svn:author' changes.)
 103       -D, --keep-date       Maintain same commit time (svn:date) as source.
 104                             (REQUIRES 'pre-revprop-change' hook script to allow
 105                             'svn:date' changes.)
 106       -P, --keep-prop       Maintain same file/dir SVN properties as source.
 107       -R, --keep-revnum     Maintain same rev #'s as source. creates placeholder
 108                             target revisions (by modifying a 'svn2svn:keep-revnum'
 109                             property at the root of the target repo).
 110       -c, --continue        Continue from last source commit to target (based on
 111                             svn2svn:* revprops).
 112       -f, --force           Allow replaying into a non-empty target folder.
 113       -r, --revision=ARG    Revision range to replay from source_url.
 114                             A revision argument can be one of:
 115                                START        Start rev # (end will be 'HEAD')
 116                                START:END    Start and ending rev #'s
 117                             Any revision # formats which SVN understands are
 118                             supported, e.g. 'HEAD', '{2010-01-31}', etc.
 119       -u, --log-author      Append source commit author to replayed commit
 120                             mesages.
 121       -d, --log-date        Append source commit time to replayed commit messages.
 122       -l, --limit=NUM       Maximum number of source revisions to process.
 123       -n, --dry-run         Process next source revision but don't commit changes
 124                             to target working-copy (forces --limit=1).
 125       -x, --verify          Verify ancestry and content for changed paths in
 126                             commit after every target commit or last target
 127                             commit.
 128       -X, --verify-all      Verify ancestry and content for entire target_url tree
 129                             after every target commit or last target commit.
 130           --pre-commit=CMD  Run the given shell script before each replayed
 131                             commit, e.g. to modify file-content during replay.
 132           --debug           Enable debugging output (same as -vvv).
 133
 134 Side Effects
 135 ------------
 136 - The source repo is treated as strictly read-only. We do log/info/export/etc.
 137   actions from the source repo, to get the history to replay and to get the
 138   file contents at each step along teh way.
 139 - You must have commit access to the target repo. Additionally, for some of
 140   the optional command-line args, you'll need access to the target repo to
 141   setup hook scripts, e.g. "pre-revprop-change".
 142 - This script will create some folders off of your current working directory:
 143   - "`_wc_target`": This is the checkout of the target\_url, where we replay
 144     actions into and where we commit to the target repo. You can safely
 145     remove this directory after a run, and the script will do a fresh
 146     "svn checkout" (if needed) when starting the next time.
 147   - "`_wc_target_tmp`": This is a temporary folder, which will only be created
 148     if using `--keep-revnum` mode and it should only exist for brief periods
 149     of time. This is where we commit dummy/padding revisions to the target repo,
 150     checking out the root folder of the target repo and modifying a
 151     "`svn2svn:keep-revnum`" property, i.e. a small change to trigger a commit
 152     and in a location that will likely go un-noticed in the final target repo.
 153
 154 Examples
 155 --------
 156 **Create a copy of only /trunk from source repo, starting at r5000**
 157
 158     $ svnadmin create /svn/target
 159     $ svn mkdir -m 'Add trunk' file:///svn/target/trunk
 160     $ svnreplay -av -r 5000 http://server/source/trunk file:///svn/target/trunk
 161
 162 1. The `target_url` will be checked-out to `./_wc_target`.
 163 2. The first commit to `http://server/source/trunk` at/after r5000 will be
 164    exported & added into `_wc_target`.
 165 3. All revisions affecting `http://server/source/trunk` (starting at r5000)
 166    will be replayed to `_wc_target`. Any add/copy/move/replaces that are
 167    copy-from'd some path outside of /trunk (e.g. files renamed on a
 168    /branch and branch was merged into /trunk) will correctly maintain
 169    logical ancestry where possible.
 170
 171 **Use continue-mode (-c) to pick-up where the last run left-off**
 172
 173     $ svnreplay -avc http://server/source/trunk file:///svn/target/trunk
 174
 175 1. The `target_url` will be checked-out to `./_wc_target`, if not already
 176    checked-out
 177 2. All new revisions affecting `http://server/source/trunk` starting from
 178    the last replayed revision to `file:///svn/target/trunk` (based on the
 179    "`svn2svn:*`" revprops) will be replayed to `_wc_target`, maintaining all
 180    logical ancestry where possible.
 181
 182 Credits
 183 -------
 184 This project borrows a lot of code from the "hgsvn" project.  Many thanks to
 185 the folks who have contributed to the hgsvn project, for writing code that is
 186 easily re-usable:
 187
 188 * [http://pypi.python.org/pypi/hgsvn](http://pypi.python.org/pypi/hgsvn)
 189 * [https://bitbucket.org/andialbrecht/hgsvn/overview](https://bitbucket.org/andialbrecht/hgsvn/overview)
 190
 191 This project was originally inspired by this "svn2svn" project:
 192 [http://code.google.com/p/svn2svn/](http://code.google.com/p/svn2svn/)
 193 That project didn't fully meet my needs, so I forked and ended-up rewriting
 194 the majority of the code.
 195
 196 Links
 197 -----
 198 * Introduction: "**[svn2svn: Replaying SVN History](http://nynim.org/blog/2012/02/01/svn2svn-replaying-svn-history/)**"
 199 * Project page: [http://nynim.org/projects/svn2svn](http://nynim.org/projects/svn2svn)
 200 * Source code @ Github: [https://github.com/tonyduckles/svn2svn](https://github.com/tonyduckles/svn2svn)
 201 * Source code @ git.nynim.org [http://git.nynim.org/svn2svn.git](http://git.nynim.org/svn2svn.git)