'\" t
.\"     Title: repotool
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.16
.\"      Date: 2023-06-05
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "REPOTOOL" "1" "2023-06-05" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
repotool \- operate on aany supporteed repository type in a uniform way
.SH "SYNOPSIS"
.sp
\fBrepotool\fP \*(Aqcommand\*(Aq [\-d | \-q | \-v] [args...]
.SH "DESCRIPTION"
.sp
repotool is a wrapper around repository operations that differ by
version\-control system.  It is little use by itself, existing mainly
to generate and simplify a conversion makefile usable with
reposurgeon(1).
.sp
Not all actions are supported on all systems.  You will get an
error message and a return value of 1 when attempting an unsupported
action.
.sp
With the \-v option, report the commands executed just before
they are run. With the \-q option, only fatal errors are printed
instead of non\-fatal gripes. The \-q and \-v options also disable each
other and only the last one will take effect.
.sp
With the \-d option, change to a specified directory before performing
whatever operation was selected. If the directory doesn\(cqt exist or
can\(cqt be searched into, that\(cqs a fatal error.
.sp
The following subcommands are available:
.sp
initialize
.RS 4
The "initialize" option takes a project name (and, optionally,
following source and target VCS types) and generates a
Makefile that will sequence various steps of a repository
conversion. It also generates stub lift and options files. This is
meant to be run in an empty work directory, the tool will refuse
to step on any of these files that already exist.  Afterwards, you
will need to set some variables in the Makefile; read its header
comment.
.RE
.sp
export
.RS 4
The \*(Aqexport\*(Aq action, run from within a repository directory,
dumps a copy of a CVS, Subversion, git, bzr, hg, or darcs repository
to a flat history file readable by reposurgeon. The format is usually
a git\-fast\-import stream, except that Subversion repositories export
as Subversion dump files; the point is to be a lossless
representation, or as close to one as possible.
.RE
.sp
mirror
.RS 4
The \*(Aqmirror\*(Aq action makes or updates a local mirror of a
Subversion, CVS, git, hg, or p4 repo. It requires an argument,
either a repository URL or the name of a local mirror directory
created by a previous run. The first form creates a local mirror of
the repository in a directory named after the last segment of the URL,
with the suffix "\-mirror" (the local mirror name can be
overridden by an optional second argument). The second form updates
the local mirror, doing an incremental fetch; just give the mirror
directory name.  If the environment variables RUSERNAME and RPASSWORD
are set, they are used as login/password credentials for Subversion
mirroring.
.sp
Subversion URLs are as specified in the public documentation for
Subversion.  CVS URLs must specify a host and repository path,
followed by a \*(Aq#\*(Aq, followed by a module name.  URLs for git and hg
should be in the form normally used for clone commands.  Perforce
(p4) URLs must specify host, path, and depot (project).
.sp
The mirror command can also be passed an rsync URL (service prefix
"rsync://").  This will usually be faster than mirroring through an
equivalent Subversion URL.
.sp
Finally, a repository URL may be a "file://" URL, in which
case the repository type is autodetected from the contents of
the indicated directory. Note: A Subversion file URL has \fBthree\fP
slashes after the "file:" prefix!
.RE
.sp
branches
.RS 4
The \*(Aqbranches\*(Aq option, run from within a repository directory ,
returns a list of the repository\(cqs branch names.
.RE
.sp
checkout
.RS 4
The \*(Aqcheckout\*(Aq option checks out a working copy of the
repository. It must be called from within the repository. It takes one
required argument \- the checkout directory location.
.RE
.sp
compare
.RS 4
The \*(Aqcompare\*(Aq action takes two repository directories. It may
optionally take a tag\-branch\-revision spec as for the checkout
option. You can also pass two revisions separated by a colon to the \-r
option, to have the first one checked out in the first repository and
the second one in the second repository. That permits one to compare
two different revisions, or the same revision referenced differently
in two VCS. You can leave one of the two revisions empty, then the \-r
option will not be passed to the corresponding repository checkout.
This is useful to compare a git tag or branch to the corresponding tag
or branch in SVN as seen at a particular revision (specifying both a
branch and revision makes sense in SVN, but not in git).  The selected
versions are compared with diff \-r, with noise due to SCCS/RCS/CVS
keyword expansion ignored.  File permissions well as
content are checked, any mismatches will be shown after the diff
listing.
.RE
.sp
compare\-tags
.RS 4
The \*(Aqcompare\-tags\*(Aq action takes two repository directories, extracts a
list of tags from the first, then compares the repository contents at
each tag in the list, generating a compare report for each.  Takes
compare options.  Additionally the \-e option sets exclude patterns for
tag names that should be ignored.
.RE
.sp
compare\-branches
.RS 4
The \*(Aqcompare\-branches\*(Aq action takes two repository directories,
extracts a list of branches common to both, then compares the
repository contents at each branch in the list, generating a compare
report for each. Takes compare options.  Additionally the \-e option
sets exclude patterns for branch names that should be ignored.
.RE
.sp
compare\-all
.RS 4
The \*(Aqcompare\-all\*(Aq action takes two repository directories, and runs
all three above compare actions on them. Even if the same name is a
tag in one repository and a branch in the other, it will compare them
against each other. Not distinguishing them is useful as CVS tags that
are not applied to every file in the repository may get converted to
branches.  Takes compare options.  Additionally the \-e option sets
exclude patterns for tag and branch names that should be ignored.
.RE
.sp
version
.RS 4
The "version" command reports the version level of the software.
.RE
.sp
help
.RS 4
The "help" command displays a summary of commands and options.
With a following argument that is a command name, display detailed help for that command.
.RE
.sp
There is one special checkout option:
.sp
\-o
.RS 4
Pass the following option through to the underlying
checkout command. Can be used, for example, to pass
in Subversion\(cqs \-\-ignore\-externals option.
.RE
.sp
The compare operation accepts the following options:
.sp
\-n
.RS 4
Subversion\-only. Passed to the individual checkout commands which means that
in cases where it makes sense the complete repository will be checked
out as a flat one, treating branch and tag namespaces as simple
directories.
.RE
.sp
\-a
.RS 4
Subversion\-only. Use an empty directory
as the checkout if the asked branch or tag cannot be found, instead of
erroring out without any comparison. This is useful when if the other
repository uses empty content for deleted refs.
.RE
.sp
\-u
.RS 4
Emit unified diff (default).
.RE
.sp
\-c
.RS 4
Emit context diff.
.RE
.sp
\-q
.RS 4
Suppress nonfatal errors and progress spinners. The progress
sinner is also suppressed when output is redirected to a
file or pipe.
.RE
.sp
\-s
.RS 4
List matching files.
.RE
.sp
\-i
.RS 4
Perform comparison of normally ignored dot directories
.RE
.SH "ENVIRONMENT VARIABLES"
.sp
This program uses the $TMPDIR environment variable, defaulting
to \*(Aq/tmp\*(Aq if it is not set, to set where checkouts for repository
comparisons are done.
.SH "RETURN VALUES"
.sp
1 on invalid arguments or if a command called by the script failed, 0
otherwise.  A return value of 0 on a compare operation does \fBnot\fP
necessarily indicate a clean comparison; only empty output does that.
.SH "BUGS"
.sp
CVS repositories have an unnamed default branch.  This is not
listed by "repotool branches"; if there are no named branches the
output is empty.
.sp
When a Subversion file is part of a mismatch, the displayed
filename is missing its trunk/tag/branch location, which
must be inferred from the way the comparison is invoked.
.sp
Tag comparisons with git will not cope well with a branch
name containing the string "detached".
.sp
Due to extreme slowness of the Subversion checkout operation,
the compare head, tag, and branch modes assume that if one of the
directories is a Subversion checkout you have done a full checkout of
HEAD before calling this tool; thus no svn update operation is
required unless you give an \-r option.  Spurious errors will be
reported if the directory is not a full checkout of HEAD.  To avoid
this optimization and force updating, do "\-r HEAD".
.sp
There is no support for RCS or SCCS collections.
.SH "REQUIREMENTS"
.sp
The export action is a wrapper around either native export facilities
or the following engines: cvs\-fast\-export(1) (for CVS), svnadmin(1)
(for SVN), reposurgeon itself (for hg).  You must have the
appropriate engine in your $PATH for whatever kind of repository you
are streaming.
.sp
.if n .RS 4
.nf
.fam C
 [[see_also]]
== SEE ALSO ==
.fam
.fi
.if n .RE
.sp
reposurgeon(1).
.SH "AUTHOR"
.sp
Eric S. Raymond \c
.MTO "esr\(atthyrsus.com" "" "."
This tool is distributed with
reposurgeon; see the \c
.URL "http://www.catb.org/~esr/reposurgeon" "project
page" .