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.7.0
  61     <http://nynim.org/code/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-repo 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                             Called as: CMD [wc_path] [source_rev]
 133           --debug           Enable debugging output (same as -vvv).
 134
 135 Side Effects
 136 ------------
 137 - The source repo is treated as strictly read-only. We do log/info/export/etc.
 138   actions from the source repo, to get the history to replay and to get the
 139   file contents at each step along teh way.
 140 - You must have commit access to the target repo. Additionally, for some of
 141   the optional command-line args, you'll need access to the target repo to
 142   setup hook scripts, e.g. "pre-revprop-change".
 143 - This script will create some folders off of your current working directory:
 144   - "`_wc_target`": This is the checkout of the target\_url, where we replay
 145     actions into and where we commit to the target repo. You can safely
 146     remove this directory after a run, and the script will do a fresh
 147     "svn checkout" (if needed) when starting the next time.
 148   - "`_wc_target_tmp`": This is a temporary folder, which will only be created
 149     if using `--keep-revnum` mode and it should only exist for brief periods
 150     of time. This is where we commit dummy/padding revisions to the target repo,
 151     checking out the root folder of the target repo and modifying a
 152     "`svn2svn:keep-revnum`" property, i.e. a small change to trigger a commit
 153     and in a location that will likely go un-noticed in the final target repo.
 154
 155 Examples
 156 --------
 157 **Create a copy of only /trunk from source repo, starting at r5000**
 158
 159     $ svnadmin create /svn/target
 160     $ svn mkdir -m 'Add trunk' file:///svn/target/trunk
 161     $ svnreplay -av -r 5000 http://server/source/trunk file:///svn/target/trunk
 162
 163 1. The `target_url` will be checked-out to `./_wc_target`.
 164 2. The first commit to `http://server/source/trunk` at/after r5000 will be
 165    exported & added into `_wc_target`.
 166 3. All revisions affecting `http://server/source/trunk` (starting at r5000)
 167    will be replayed to `_wc_target`. Any add/copy/move/replaces that are
 168    copy-from'd some path outside of /trunk (e.g. files renamed on a
 169    /branch and branch was merged into /trunk) will correctly maintain
 170    logical ancestry where possible.
 171
 172 **Use continue-mode (-c) to pick-up where the last run left-off**
 173
 174     $ svnreplay -avc http://server/source/trunk file:///svn/target/trunk
 175
 176 1. The `target_url` will be checked-out to `./_wc_target`, if not already
 177    checked-out
 178 2. All new revisions affecting `http://server/source/trunk` starting from
 179    the last replayed revision to `file:///svn/target/trunk` (based on the
 180    "`svn2svn:*`" revprops) will be replayed to `_wc_target`, maintaining all
 181    logical ancestry where possible.
 182
 183 Credits
 184 -------
 185 This project borrows a lot of code from the "hgsvn" project.  Many thanks to
 186 the folks who have contributed to the hgsvn project, for writing code that is
 187 easily re-usable:
 188
 189 * [http://pypi.python.org/pypi/hgsvn](http://pypi.python.org/pypi/hgsvn)
 190 * [https://bitbucket.org/andialbrecht/hgsvn/overview](https://bitbucket.org/andialbrecht/hgsvn/overview)
 191
 192 This project was originally inspired by this "svn2svn" project:
 193 [http://code.google.com/p/svn2svn/](http://code.google.com/p/svn2svn/)
 194 That project didn't fully meet my needs, so I forked and ended-up rewriting
 195 the majority of the code.
 196
 197 Links
 198 -----
 199 * Introduction: **[svn2svn: Replaying SVN History](http://nynim.org/blog/2012/02/01/svn2svn-replaying-svn-history/)**
 200 * Project page: [http://nynim.org/code/svn2svn](http://nynim.org/code/svn2svn)
 201 * Source code @ Github: [https://github.com/tonyduckles/svn2svn](https://github.com/tonyduckles/svn2svn)
 202 * Source code @ git.nynim.org [http://git.nynim.org/svn2svn.git](http://git.nynim.org/svn2svn.git)