1REPOCUTTER(1) Development Tools REPOCUTTER(1)
2
6 repocutter - surgical and filtering operations on Subversion dump files
7
9 repocutter [-q] [-r selection] subcommand [-d] [-i]
10
12 This program does surgical and filtering operations on Subversion dump
13 files. While it is is not as flexible as reposurgeon(1), it can perform
14 Subversion-specific transformations that reposurgeon cannot, and can be
15 useful for processing Subversion repositories into a form suitable for
16 conversion.
17 (As a matter of possible historical interest, the reason for the
19 partial functional overlap between repocutter and reposurgeon is that
20 repocutter was first written earlier and became a testbed for some of
21 the design concepts in reposurgeon. After reposurgeon was written, the
22 author learned that it could not naturally support some useful
23 operations very specific to Subversion, and enhanced repocutter to do
24 those.)
25 In all commands, the -r (or --range) option limits the selection of
27 revisions over which an operation will be performed. A selection
28 consists of one or more comma-separated ranges. A range may consist of
29 an integer revision number or the special name HEAD for the head
30 revision. Or it may be a colon-separated pair of integers, or an
31 integer followed by a colon followed by HEAD.
32 Normally, each subcommand produces a progress spinner on standard
34 error; each turn means another revision has been filtered. The -q (or
35 --quiet) option suppresses this.
36 The -d command enabled debug messages on standard error. These are
38 probably only of interest to repocutter developers.
39 The -i command sets the input source to a specified filename. This is
41 primarilseey useful when running the program under a debugger.
42 Generally, if you need to use this program at all, you will find that
44 you need to pipe your dump file through multiple instances of it doing
45 one kind of operation each. This is not as expensive as it sounds; with
46 the exception of the reduce subcommand, the working set of this program
47 is bounded by the size of the largest commit metadata item. It does not
48 need to hold the entire repo metadata in memory.
49 The following subcommands are available:
51 help
53 Without arguments, list available commands. With a command-name
54 argument, show detailed help for that subcommand.
55 select
57 The 'select' subcommand selects a range and permits only revisions
58 in that range to pass to standard output. A range beginning with 0
59 includes the dumpfile header.
60 propset
62 Set a property to a value. May be restricted by a revision
63 selection. You may specify multiple property settings. See the
64 embedded help for syntax details.
65 propdel
67 Delete the named property. May be restricted by a revision
68 selection. You may specify multiple properties to be deleted. See
69 the embedded help for syntax details.
70 proprename
72 Rename a property. May be restricted by a revision selection. You
73 may specify multiple properties to be renamed. See the embedded
74 help for syntax details.
75 log
77 enerate a log report, same format as the output of svn log on a
78 repository, to standard output.
79 setlog
81 Replace the log entries in the input dumpfile with the
82 corresponding entries in a specified file, which should be in the
83 format of an svn log output. Replacements may be restricted to a
84 specified range. See the embedded help for syntax details.
85 strip
87 Replace content with unique generated cookies on all node paths
88 matching the specified regular expressions; if no expressions are
89 given, match all paths. Useful when you need to examine a
90 particularly complex node structure.
91 expunge
93 Delete all operations with Node-path headers matching specified
94 Python regular expressions. Any revision left with no Node records
95 after this filtering has its Revision record removed as well.
96 pathrename
98 Modify Node-path and Node-copyfrom-path headers matching a
99 specified Python regular expression; replace with a given string.
100 The string may contain Python backreferences to parenthesized
101 portions of the pattern. See the embedded help for syntax details.
102 renumber
104 Renumber all revisions, patching Node-copyfrom headers as required.
105 Any selection option is ignored. Takes no arguments.
106 reduce
108 Strip revisions out of a dump so the only parts left those likely
109 to be relevant to a conversion problem. See the embedded help for
110 syntax details and the relevance filter.
111 see
113 Render a very condensed report on the repository node structure,
114 mainly useful for examining strange and pathological repositories.
115 File content is ignored. You get one line per repository operation,
116 reporting the revision, operation type, file path, and the copy
117 source (if any). Directory paths are distinguished by a trailing
118 slash. The 'copy' operation is really an 'add' with a directory
119 source and target; the display name is changed to make them easier
120 to see.
121 swap
123 Swap the top two components of every path. This is sometimes useful
124 when converting a multi-project Subversion repository that has
125 normal trunk/branch/tag structure under each top-level directory
126 (of course the alternative is to break it into componebts using
127 multiple strip operations).
128
130 Under the name “snvcutter”, an ancestor of this program traveled in the
131 contrib/ director of the Subversion distribution. It had functional
132 overlap with reposurgeon(1) because it was directly ancestral to that
133 code. It was moved to the reposurgeon(1) distribution in January 2016.
134 This program was ported from Python to Go in Aygust 2018, at which time
136 the obsolete "squash" command was retired.
137
139 There is one regression since the Python version: repocutter no longer
140 recognizes Macintosh-syle line endings consisting of a carriage return
141 only. This may be addressed in a future version.
142 Because the native Go regular-expression library declines to support
144 backreferences (in order to scale better) the regexps in the pathrename
145 comand are implemented using a third-party library that supports Perl
146 regular-expression syntax. Neither are exactly identical to the Python
147 regexps supported in older versions.
148
150 reposurgeon(1).
151
153 Suppose you have a Subversion repository with the following
154 semi-pathological structure:
155 Directory1/ (with unrelated content)
157 Directory2/ (with unrelated content)
158 TheDirIWantToMigrate/
159 branches/
160 crazy-feature/
161 UnrelatedApp1/
162 TheAppIWantToMigrate/
163 tags/
164 v1.001/
165 UnrelatedApp1/
166 UnrelatedApp2/
167 TheAppIWantToMigrate/
168 trunk/
169 UnrelatedApp1/
170 UnrelatedApp2/
171 TheAppIWantToMigrate/
172 You want to transform the dump file so that TheAppIWantToMigrate can be
174 subject to a regular branchy lift. A way to dissect out the code of
175 interest would be with the following series of filters applied:
176 repocutter expunge '^Directory1' '^Directory2'
178 repocutter pathrename '^TheDirIWantToMigrate/' ''
179 repocutter expunge '^branches/crazy-feature/UnrelatedApp1/
180 repocutter pathrename 'branches/crazy-feature/TheAppIWantToMigrate/' 'branches/crazy-feature/'
181 repocutter expunge '^tags/v1.001/UnrelatedApp1/'
182 repocutter expunge '^tags/v1.001/UnrelatedApp2/'
183 repocutter pathrename '^tags/v1.001/TheAppIWantToMigrate/' 'tags/v1.001/'
184 repocutter expunge '^trunk/UnrelatedApp1/'
185 repocutter expunge '^trunk/UnrelatedApp2/'
186 repocutter pathrename '^trunk/TheAppIWantToMigrate/' 'trunk/'
187
189 The sift and expunge operations can produce output dumps that are
190 invalid. The problem is copyfrom operations (Subversion branch
191 creations). If an included revision includes a copyfrom reference to an
192 excluded one, the reference target won't be in the emitted dump; it
193 won't load correctly in either Subversion or reposurgeon. Attempts to
194 be clever about this won't work; the problem is inherent in the data
195 model of Subversion.
196
198 Eric S. Raymond <esr@thyrsus.com>. This tool is distributed with
199 reposurgeon; see the project page at
200 http://www.catb.org/~esr/reposurgeon.
201repocutter 09/16/2019 REPOCUTTER(1)