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