]> Tony Duckles's Git Repositories (git.nynim.org) - svn2svn.git/blob - README.mkd
svn2svn v1.6.0
[svn2svn.git] / 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)