1REPOTOOL(1)                                                        REPOTOOL(1)
2
3
4

NAME

6       repotool - operate on a CVS, SVN, git, bzr, hg, or darcs repository in
7       a uniform way
8

SYNOPSIS

10       repotool 'command' [-d | -q | -v] [args...]
11

DESCRIPTION

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
17       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
20       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
25       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
29       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
37       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
44       The 'tags' option, run from within a repository directory, returns a
45       list of the repository’s release tags.
46
47       The 'branches' option, run from within a repository directory , returns
48       a list of the repository’s branch names.
49
50       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
54       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
75       There is one special checkout option:
76
77       -o
78           Pass the following option through to the underlying checkout
79           command. Can be used, for example, to pass in Subversion’s
80           --ignore-externals option.
81
82       The 'compare' action takes two repository directories. It may
83       optionally take a tag-branch-revision spec as for the checkout option.
84       You can also pass two revisions separated by a colon to the -r option,
85       to have the first one checked out in the first repository and the
86       second one in the second repository. That permits one to compare two
87       different revisions, or the same revision referenced differently in two
88       VCS. You can leave one of the two revisions empty, then the -r option
89       will not be passed to the corresponding repository checkout. This is
90       useful to compare a git tag or branch to the corresponding tag or
91       branch in SVN as seen at a particular revision (specifying both a
92       branch and revision makes sense in SVN, but not in git). The selected
93       versions are compared with diff -r, with noise due to SCCS/RCS/CVS
94       keyword expansion ignored. File permissions well as content are
95       checked, any mismatches will be shown after the diff listing.
96
97       The compare operation accepts the following options:
98
99       -n
100           Passed to the individual checkout commands which means that in
101           cases where it makes sense the complete repository will be checked
102           out flatly, treating branch and tag namespaces as simple
103           directories.
104
105       -a
106           Use an empty directory as the checkout if the asked branch or tag
107           cannot be found, instead of erroring out without any comparison.
108           This is useful when if the other repository uses empty content for
109           deleted refs.
110
111       -u
112           Emit unified diff (default).
113
114       -c
115           Emit context diff.
116
117       -q
118           Suppress nonfatal errors and progress spinners.
119
120       -s
121           List matching files.
122
123       -i
124           Perform comparison of normally ignored dot directories
125
126       The 'compare-tags' action takes two repository directories, extracts a
127       list of tags from the first, then compares the repository contents at
128       each tag in the list, generating a compare report for each. Takes
129       compare options. Additionally the -e option sets exclude patterns for
130       tag names that should be ignored.
131
132       The 'compare-branches' action takes two repository directories,
133       extracts a list of branches common to both, then compares the
134       repository contents at each branch in the list, generating a compare
135       report for each. Takes compare options. Additionally the -e option sets
136       exclude patterns for branch names that should be ignored.
137
138       The 'compare-all' action takes two repository directories, and runs all
139       three above compare actions on them. Even if the same name is a tag in
140       one repository and a branch in the other, it will compare them against
141       each other. Not distinguishing them is useful as CVS tags that are not
142       applied to every file in the repository may get converted to branches.
143       Takes compare options. Additionally the -e option sets exclude patterns
144       for tag and branch names that should be ignored.
145
146       The 'mirror' action makes or updates a local mirror of a Subversion,
147       CVS, git, or hg repo. It requires a single argument, either a
148       repository URL or the name of a local mirror directory created by a
149       previous run. The first form creates a local mirror of the repository
150       in a directory named after the last segment of the URL, with the suffix
151       "-mirror" (the local mirror name can be overridden by an optional
152       second argument). The second form updates the local mirror, doing an
153       incremental fetch; just give the mirror directory name. If the
154       environment variables RUSERNAME and RPASSWORD are set, they are used as
155       login/password credentials for Subversion mirroring.
156
157       Subversion URLs are as specified in the public documentation for
158       Subversion. CVS URLs must specify a host and repository path, followed
159       by a '#', followed by a module name. URLs for git and hg should be in
160       the form normally used for clone commands. Alternatively, a repository
161       URL may be a "file://" URL, in which case the repository type is
162       autodetected from the contents of the indicated directory. Note: A
163       Subversion file URL has three slashes after the "file:" prefix!
164
165       The mirror command can also be passed an rsync URL. This will usually
166       be faster than mirroring through an equivalent Subversion URL.
167
168       The "version" command reports the version level of the software.
169
170       The "help" command displays a summary of commands and options.
171

ENVIRONMENT VARIABLES

173       This program uses the $TMPDIR environment variable, defaulting to
174       '/tmp' if it is not set, to set where checkouts for repository
175       comparisons are done.
176

RETURN VALUES

178       1 on invalid arguments or if a command called by the script failed, 0
179       otherwise. A return value of 0 on a compare operation does not
180       necessarily indicate a clean comparison; only empty output does that.
181

BUGS

183       CVS repositories have an unnamed default branch. This is not listed by
184       "repotool branches"; if there are no named branches the output is
185       empty.
186
187       When a Subversion file is part of a mismatch, the displayed filename is
188       missing its trunk/tag/branch location, which must be inferred from the
189       way the comparison is invoked.
190
191       Tag comparisons with git will not cope well with a branch name
192       containing the string "detached".
193
194       Due to extreme slowness of the Subversion checkout operation, the
195       compare head, tag, and branch modes assume that if one of the
196       directories is a Subversion checkout you have done a full checkout of
197       HEAD before calling this tool; thus no svn update operation is required
198       unless you give an -r option. Spurious errors will be reported if the
199       directory is not a full checkout of HEAD. To avoid this optimization
200       and force updating, do "-r HEAD".
201

REQUIREMENTS

203       The export action is a wrapper around either native export facilities
204       or the following engines: cvs-fast-export(1) (for CVS), svnadmin(1)
205       (for SVN), reposurgeon itself (for hg). You must have the appropriate
206       engine in your $PATH for whatever kind of repository you are streaming.
207
208            [[see_also]]
209           == SEE ALSO ==
210
211       reposurgeon(1).
212

AUTHOR

214       Eric S. Raymond <esr@thyrsus.com>. This tool is distributed with
215       reposurgeon; see the project <http://www.catb.org/~esr/reposurgeon>
216       page" .
217
218
219
220                                  2022-04-21                       REPOTOOL(1)
Impressum