= reposurgeon(1) =
:doctype: manpage

== NAME ==
reposurgeon - surgical operations on repositories

== SYNOPSIS ==

*reposurgeon* [command...]

[[description]]
== DESCRIPTION ==

The purpose of reposurgeon is to enable risky operations that VCSes
(version-control systems) don't 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.

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.

The user interface of reposurgeon resembles a symbolic debugger.
It can be used to explore a repository history interactively, but
also has a well-developed scripting capability that can be used
to develop and refine recipes.

Fully supported systems (those for which reposurgeon can both read and
write repositories) include git, hg, bzr, brz, Fossil, darcs, RCS, and SRC.
There is tested read-side support for SCCS, CVS, and svn. Due to
data-model incompatiblities, not all metadata is necessarily passed
through in both import and export directions: for details, consult the long-form
manual referenced later on this page.

The Subversion to Git pathway is particulartly well tested. On the
other hand, the quality of CVS lifts may be poor, with individual
lifts requiring serious hand-hacking - this is due to inherent
problems with CVS's file-oriented model and the fragility of its
repository structures.

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.

If you don't have a tool installed that reposurgeon needs, it will
bail out gradefully and inform you what is missing.

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's 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.

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.

For details on how to operate reposurgeon, see the
http://www.catb.org/esr/reposurgeon/repository-editing.html[Repository Editing and
Conversion With Reposurgeon].

[[returns]]
== ERROR RETURNS ==

Returns 1 if the last command executed threw an error, 0 otherwise.

[[see_also]]
== SEE ALSO ==

bzr(1), brz(1), cvs(1), darcs(1), fossil(1), git(1), hg(1), rcs(1),
sccs(1), src(1), svn(1).

[[author]]
== AUTHOR ==

Eric S. Raymond <esr@thyrsus.com>; see the
http://www.catb.org/~esr/reposurgeon[project page].

// end
