]> Tony Duckles's Git Repositories (git.nynim.org) - svn2svn.git/blob - README.mkd
Set LC_MESSAGES to C
[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 `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)