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 (when possible)**, e.g. uses "svn copy" for renames.
  10 - **Maintains original commit messages**.
  11 - **Optionally maintain source commit authors (`svn:author`) and commit timestamps
  12   (`svn:date`)**.  Requires a "pre-revprop-change" hook script in the target
  13   repo, to be able to change the "`svn:author`" and "`svn:date`" revprops after
  14   target commits have been made.
  15 - **Optionally maintain identical revision #'s between source vs. target repo**.
  16   Effectively requires that you're replaying into an empty target repo,
  17   or rather that the first source repo revision to be replayed is less than
  18   the last target repo revision. Create blank "padding" revisions in the target
  19   repo as needed.
  20 - **Optionally run an external shell script before each replayed commit**,
  21   to give the ability to dynamically exclude or modify files as part
  22   of the replay.
  23
  24 Overview
  25 --------
  26 This is a utility for replicating the revision history from a source path in
  27 a source SVN repository to a target path in a target SVN repository. In other
  28 words, it "replays the history" of a given source SVN repository/branch/path
  29 into a target SVN repository/branch/path.
  30
  31 This can be useful to create filtered version of a source SVN repository. For
  32 example, say that you have a huge SVN repository with a _lot_ of old branch
  33 history which is taking up a lot of disk-space and not serving a lot of purpose
  34 going forward.  You can this utility to replay/filter just the "/trunk" SVN
  35 history into a new repository, so that things like "svn log" and "svn blame"
  36 will still show the correct (logical) history/ancestry, even though we end-up
  37 generating new commits which will have newer commit-dates and revision #'s.
  38
  39 While this replay will obviously run faster if you're running between both
  40 a local source and target repositories, none of this *requires* direct
  41 access to the repo server. You could access both the source and target repo's
  42 over standard `http://`, `ssh://`, etc. methods.
  43
  44 Usage
  45 -----
  46 See `svn2svn.py --help`
  47
  48 Side Effects
  49 ------------
  50 - The source repo is treated as strictly read-only. We do log/info/export/etc.
  51   actions from the source repo, to get the history to replay and to get the
  52   file contents at each step along teh way.
  53 - You must have commit access to the target repo. Additionally, for some of
  54   the optional command-line args, you'll need access to the target repo to
  55   setup hook scripts, e.g. "pre-revprop-change".
  56 - This script will create some folders off of your current working directory:
  57   - "`_wc_target`": This is the checkout of the target\_url, where we replay
  58     actions into and where we commit to the target repo. You can safely
  59     remove this directory after a run, and the script will do a fresh
  60     "svn checkout" (if needed) when starting the next time.
  61   - "`_tmp_wc_target`": This is a temporary folder, which will only be created
  62     if using `--keep-revnum` mode and it should only exist for brief periods
  63     of time. This is where we commit dummy/padding revisions to the target repo,
  64     checking out the root folder of the target repo and modifying a
  65     "`svn2svn:keep-revnum`" property, i.e. a small change to trigger a commit
  66     and in a location that will likely go un-noticed in the final target repo.
  67
  68 Examples
  69 --------
  70 **Create a copy of only /trunk from source repo, starting at r5000**
  71
  72     $ svnadmin create /svn/target
  73     $ svn mkdir -m 'Add trunk' file:///svn/target/trunk
  74     $ svn2svn -av -r 5000 http://server/source/trunk file:///svn/target/trunk
  75
  76 1. The `target_url` will be checked-out to `./_wc_target`.
  77 2. The first commit to `http://server/source/trunk` at/after r5000 will be
  78    exported & added into `_wc_target`.
  79 3. All revisions affecting `http://server/source/trunk` (starting at r5000)
  80    will be replayed to `_wc_target`. Any add/copy/move/replaces that are
  81    copy-from'd some path outside of /trunk (e.g. files renamed on a
  82    /branch and branch was merged into /trunk) will correctly maintain
  83    logical ancestry where possible.
  84
  85 **Use continue-mode (-c) to pick-up where the last run left-off**
  86
  87     $ svn2svn -avc http://server/source/trunk file:///svn/target/trunk
  88
  89 1. The `target_url` will be checked-out to `./_wc_target`, if not already
  90    checked-out
  91 2. All new revisions affecting `http://server/source/trunk` starting from
  92    the last replayed revision to `file:///svn/target/trunk` (based on the
  93    "`svn2svn:*`" revprops) will be replayed to `_wc_target`, maintaining all
  94    logical ancestry where possible.
  95
  96 Credits
  97 -------
  98 This project borrows a lot of code from the "hgsvn" project.  Many thanks to
  99 the folks who have contributed to the hgsvn project, for writing code that is
 100 easily re-usable:
 101
 102 * [http://pypi.python.org/pypi/hgsvn](http://pypi.python.org/pypi/hgsvn)
 103 * [https://bitbucket.org/andialbrecht/hgsvn/overview](https://bitbucket.org/andialbrecht/hgsvn/overview)
 104
 105 This project was originally inspired by this "svn2svn" project:
 106 [http://code.google.com/p/svn2svn/](http://code.google.com/p/svn2svn/)
 107 That project didn't fully meet my needs, so I forked and ended-up rewriting
 108 the majority of the code.
 109
 110 Links
 111 -----
 112 * Introduction: "**[svn2svn: Replaying SVN History](http://nynim.org/blog/2012/02/01/svn2svn-replaying-svn-history/)**"
 113 * Project page: [http://nynim.org/projects/svn2svn](http://nynim.org/projects/svn2svn)
 114 * Source code @ Github: [https://github.com/tonyduckles/svn2svn](https://github.com/tonyduckles/svn2svn)
 115 * Source code @ git.nynim.org [http://git.nynim.org/svn2svn.git](http://git.nynim.org/svn2svn.git)