'\" t
.\"     Title: reposurgeon
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2024-02-24
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "REPOSURGEON" "1" "2024-02-24" "\ \&" "\ \&"
.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"
reposurgeon \- surgical operations on repositories
.SH "SYNOPSIS"
.sp
\fBreposurgeon\fP [command...]
.SH "DESCRIPTION"
.sp
The purpose of reposurgeon is to enable risky operations that VCSes
(version\-control systems) don\(cqt want to let you do, such as (a)
editing past comments and metadata, (b) excising commits, (c)
coalescing and splitting commits, (d) removing files and subtrees from
repo history, (e) merging or grafting two or more repos, and (f)
cutting a repo in two by cutting a parent\-child link, preserving the
branch structure of both child repos.
.sp
A major use of reposurgeon is to assist a human operator to
perform higher\-quality conversions among version control systems than
can be achieved with fully automated converters.
.sp
The original motivation for reposurgeon was
to clean up artifacts created by repository conversions.  It was
foreseen that the tool would also have applications when code needs to
be removed from repositories for legal or policy reasons.
.sp
To keep reposurgeon simple and flexible, it
normally does not do its own repository reading and writing.  Instead, it
relies on being able to parse and emit the command streams created by
git\-fast\-export and read by git\-fast\-import.  This means that it can
be used on any version\-control system that has both fast\-export
and fast\-import utilities. The git\-import stream format also implicitly
defines a common language of primitive operations for
reposurgeon to speak.
.sp
Fully supported systems (those for which reposurgeon can both read and
write repositories) include git, hg, bzr, brz, darcs, bk, RCS, and SRC.
For a complete list, with dependencies and technical notes, type
"prefer" to the reposurgeon prompt.
.sp
Writing to the file\-oriented systems RCS and SRC is done via
rcs\-fast\-import(1) and has some serious limitations because those
systems cannot represent all the metadata in a git\-fast\-export
stream. Consult that tool\(cqs documentation for details and partial
workarounds.
.sp
Fossil repository files can be read in using the \f(CR\-\-format=fossil\fP
option of the \(oq\f(CRread\fP\(cq command and written out with the \f(CR\-\-format=fossil\fP
option of the \(oq\f(CRwrite\fP\(cq. Ignore patterns are not
translated in either direction.
.sp
SVN and CVS are supported for read only, not write.  For CVS,
reposurgeon must be run from within a repository directory (that is, a
tree of CVS masters; a CVSROOT is not required). When reading from a
CVS top\-level directory each module becomes a subdirectory in the
reposurgeon representation of the change history. It is also possible
to read a repository from within a CVS module subdirectory and lift
that individual module.
.sp
In order to deal with version\-control systems that do not have
fast\-export equivalents, reposurgeon can also host extractor code that
reads repositories directly.  For each version\-control system
supported through an extractor, reposurgeon uses a small amount of
knowledge about the system\(cqs command\-line tools to (in effect) replay
repository history into an input stream internally. Repositories under
systems supported through extractors can be read by reposurgeon, but
not modified by it.  In particular, reposurgeon can be used to move a
repository history from any VCS supported by an extractor to any VCS
supported by a normal importer/exporter pair.
.sp
Mercurial repository reading is implemented with an extractor class;
writing is handled with hg\-git\-fast\-import.  A test extractor exists
for git, but is normally disabled in favor of the regular exporter.
.sp
For details on how to operate reposurgeon, see the
\c
.URL "http://www.catb.org/esr/reposurgeon/repository\-editing.html" "Repository Editing and
Conversion With Reposurgeon" .
.SH "REQUIREMENTS"
.sp
reposurgeon relies on importers and exporters
asociated with the VCSes it supports.
.sp
git
.RS 4
Core git supports both export and import.
.RE
.sp
bzr
.RS 4
Requires bzr plus the \f(CRbzr\-fast\-import\fP plugin.
.RE
.sp
brz
.RS 4
Requires brz.
.RE
.sp
hg
.RS 4
Requires core hg and \f(CRhg\-git\-fast\-import\fP.
.RE
.sp
svn
.RS 4
Stock Subversion commands support export and import.
.RE
.sp
darcs
.RS 4
Stock darcs commands support export.
.RE
.sp
CVS
.RS 4
Requires \f(CRcvs\-fast\-export\fP. Note that the quality of CVS lifts may
be poor, with individual lifts requiring serious hand\-hacking. This
is due to inherent problems with CVS\(cqs file\-oriented model.
.RE
.sp
RCS
.RS 4
Requires \f(CRcvs\-fast\-export\fP (yes, that\(cqs not a typo; \f(CRcvs\-fast\-export\fP
handles RCS collections as well). The caveat for CVS applies.
.RE
.sp
SCCS
.RS 4
Requires \f(CRcvs\-fast\-export\fP and \f(CRsccs2rcs\fP, the latter to do a
lossless conversion to RCS. The caveat for CVS applies.
.RE
.sp
bk
.RS 4
Versions 7.3 and after have a fast\-export command that reposurgeon can use.
.RE
.SH "ERROR RETURNS"
.sp
Returns 1 if the last command executed threw an error, 0 otherwise.
.SH "SEE ALSO"
.sp
bzr(1), brz(1), cvs(1), darcs(1), git(1), hg(1), sscs(1), rcs(1), src(1), svn(1), bk(1).
.SH "AUTHOR"
.sp
Eric S. Raymond \c
.MTO "esr\(atthyrsus.com" "" ";"
see the
.URL "http://www.catb.org/~esr/reposurgeon" "project page" "."