1REPOTOOL(1) REPOTOOL(1)
2
6 repotool - operate on a CVS, SVN, git, bzr, hg, or darcs repository in
7 a uniform way
8
10 repotool 'command' [-d | -q | -v] [args...]
11
13 repotool is a wrapper around repository operations that differ by
14 version-control system. It is little use by itself, existing mainly to
15 generate and simplify a conversion makefile usable with reposurgeon(1).
16 Not all actions are supported on all systems. You will get an error
18 message and a return value of 1 when attempting an unsupported action.
19 With the -v option, report the commands executed just before they are
21 run. With the -q option, only fatal errors are printed instead of
22 non-fatal gripes. The -q and -v options also disable each other and
23 only the last one will take effect.
24 With the -d option, change to a specified directory before performing
26 whatever operation was selected. If the directory doesn’t exist or
27 can’t be searched into, that’s a fatal error.
28 The "initialize" option takes a project name (and, optionally,
30 following source and target VCS types) and generates a Makefile that
31 will sequence various steps of a repository conversion. It also
32 generates stub lift and options files. This is meant to be run in an
33 empty work directory, the tool will refuse to step on any of these
34 files that already exist. Afterwards, you will need to set some
35 variables in the Makefile; read its header comment.
36 The 'export' action, run from within a repository directory, dumps a
38 copy of a CVS, Subversion, git, bzr, hg, or darcs repository to a flat
39 history file readable by reposurgeon. The format is usually a
40 git-fast-import stream, except that Subversion repositories export as
41 Subversion dump files; the point is to be a lossless representation, or
42 as close to one as possible.
43 The 'tags' option, run from within a repository directory, returns a
45 list of the repository’s release tags.
46 The 'branches' option, run from within a repository directory , returns
48 a list of the repository’s branch names.
49 The 'checkout' option checks out a working copy of the repository. It
51 must be called from within the repository. It takes one required
52 argument - the checkout directory location.
53 The checkout option may take a revision, tag, or branch specification,
55 given with the -r, -t, or -b options. If you specify multiple
56 conflicting specifications, the revision takes precedence, then the
57 tag, then the branch. If the spec is omitted, the tip of the main line
58 of the repository will be used; this is equivalent to specifying branch
59 'master' (git terminology, which is translated by reposurgeon to
60 'trunk' or whatever the underlying VCS uses). In VCSs like SVN where
61 branches and tags are not part of the history model, it is possible to
62 specify both a revision and a branch or tag specification to get the
63 contents of the branch or tag as seen from the given revision. With
64 these VCS types, you can also use the -n (nobranch) option to checkout
65 the complete repository instead, where all branches and tags are simply
66 subdirectories. You can also use the -a (accept-missing) option to let
67 'repotool checkout' return a dangling symlink instead of stopping its
68 execution when the asked branch or tag has not been found in the SVN
69 namespace (this is currently the default for SVN repositories that are
70 yet checked out). With most DVCS checkouts, the -r, -t, and -b options
71 are essentially synonyms. If given a -d option, checkout is performed
72 from the directory specified; this may be convenient when working with
73 CVS or Subversion in order to select the repository directory.
74 The 'compare' action takes two repository directories. It may
76 optionally take a tag-branch-revision spec as for the checkout option.
77 You can also pass two revisions separated by a colon to the -r option,
78 to have the first one checked out in the first repository and the
79 second one in the second repository. That permits one to compare two
80 different revisions, or the same revision referenced differently in two
81 VCS. You can leave one of the two revisions empty, then the -r option
82 will not be passed to the corresponding repository checkout. This is
83 useful to compare a git tag or branch to the corresponding tag or
84 branch in SVN as seen at a particular revision (specifying both a
85 branch and revision makes sense in SVN, but not in git). The selected
86 versions are compared with diff -r, with noise due to SCCS/RCS/CVS
87 keyword expansion ignored. File permissions well as content are
88 checked, any mismatches will be shown after the diff listing.
89 The compare operation accepts the following options:
91 -n
93 Passed to the individual checkout commands which means that in
94 cases where it makes sense the complete repository will be checked
95 out flatly, treating branch and tag namespaces as simple
96 directories.
97 -a
99 Use an empty directory as the checkout if the asked branch or tag
100 cannot be found, instead of erroring out without any comparison.
101 This is useful when if the other repository uses empty content for
102 deleted refs.
103 -u
105 Emit unified diff (default).
106 -c
108 Emit context diff.
109 -q
111 Suppress nonfatal errors.
112 -s
114 List matching files.
115 -i
117 Perform comparison of normally ignored dot directories
118 The 'compare-tags' action takes two repository directories, extracts a
120 list of tags from the first, then compares the repository contents at
121 each tag in the list, generating a compare report for each. Takes
122 compare options. Additionally the -e option sets exclude patterns for
123 tag names that should be ignored.
124 The 'compare-branches' action takes two repository directories,
126 extracts a list of branches common to both, then compares the
127 repository contents at each branch in the list, generating a compare
128 report for each. Takes compare options. Additionally the -e option sets
129 exclude patterns for branch names that should be ignored.
130 The 'compare-all' action takes two repository directories, and runs all
132 three above compare actions on them. Even if the same name is a tag in
133 one repository and a branch in the other, it will compare them against
134 each other. Not distinguishing them is useful as CVS tags that are not
135 applied to every file in the repository may get converted to branches.
136 Takes compare options. Additionally the -e option sets exclude patterns
137 for tag and branch names that should be ignored.
138 The 'mirror' action makes or updates a local mirror of a Subversion,
140 CVS, git, or hg repo. It requires a single argument, either a
141 repository URL or the name of a local mirror directory created by a
142 previous run. The first form creates a local mirror of the repository
143 in a directory named after the last segment of the URL, with the suffix
144 "-mirror" (the local mirror name can be overridden by an optional
145 second argument). The second form updates the local mirror, doing an
146 incremental fetch; just give the mirror directory name. If the
147 environment variables RUSERNAME and RPASSWORD are set, they are used as
148 login/password credentials for Subversion mirroring.
149 Subversion URLs are as specified in the public documentation for
151 Subversion. CVS URLs must specify a host and repository path, followed
152 by a '#', followed by a module name. URLs for git and hg should be in
153 the form normally used for clone commands. Alternatively, a repository
154 URL may be a "file://" URL, in which case the repository type is
155 autodetected from the contents of the indicated directory. Note: A
156 Subversion file URL has three slashes after the "file:" prefix!
157 The mirror command can also be passed an rsync URL. This will usually
159 be faster than mirroring through an equivalent Subversion URL.
160 The "version" command reports the version level of the software.
162 The "help" command displays a summary of commands and options.
164
166 This program uses the $TMPDIR environment variable, defaulting to
167 '/tmp' if it is not set, to set where checkouts for repository
168 comparisons are done.
169
171 1 on invalid arguments or if a command called by the script failed, 0
172 otherwise. A return value of 0 on a compare operation does not
173 necessarily indicate a clean comparison; only empty output does that.
174
176 CVS repositories have an unnamed default branch. This is not listed by
177 "repotool branches"; if there are no named branches the output is
178 empty.
179 When a Subversion file is part of a mismatch, the displayed filename is
181 missing its trunk/tag/branch location, which must be inferred from the
182 way the comparison is invoked.
183 Tag comparisons with git will not cope well with a branch name
185 containing the string "detached".
186 Due to extreme slowness of the Subversion checkout operation, the
188 compare head, tag, and branch modes assume that if one of the
189 directories is a Subversion checkout you have done a full checkout of
190 HEAD before calling this tool; thus no svn update operation is required
191 unless you give an -r option. Spurious errors will be reported if the
192 directory is not a full checkout of HEAD. To avoid this optimization
193 and force updating, do "-r HEAD".
194
196 The export action is a wrapper around either native export facilities
197 or the following engines: cvs-fast-export(1) (for CVS), svnadmin(1)
198 (for SVN), reposurgeon itself (for hg). You must have the appropriate
199 engine in your $PATH for whatever kind of repository you are streaming.
200 [[see_also]]
202 == SEE ALSO ==
203 reposurgeon(1).
205
207 Eric S. Raymond <esr@thyrsus.com>. This tool is distributed with
208 reposurgeon; see the project <http://www.catb.org/~esr/reposurgeon>
209 page" .
210 2021-01-12 REPOTOOL(1)