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