NAME

       reposurgeon - surgical operations on repositories

SYNOPSIS

       reposurgeon [command...]

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

       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.

       Fully supported systems (those for which reposurgeon can both read and write repositories)
       include git, hg, bzr, darcs, bk, RCS, and SRC. For a complete list, with dependencies and
       technical notes, type "prefer" to the reposurgeon prompt.

       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’s documentation for details and partial
       workarounds.

       Fossil repository files can be read in using the --format=fossil option of the ‘read’
       command and written out with the --format=fossil option of the ‘write’. Ignore patterns
       are not translated in either direction.

       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.

       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 Repository Editing and
       <http://www.catb.org/esr/reposurgeon/repository-editing.html> Conversion With Reposurgeon"
       .

REQUIREMENTS

       reposurgeon relies on importers and exporters associated with the VCSes it supports.

       git
           Core git supports both export and import.

       bzr
           Requires bzr plus the bzr-fast-import plugin.

       hg
           Requires core hg and hg-git-fast-import.

       svn
           Stock Subversion commands support export and import.

       darcs
           Stock darcs commands support export.

       CVS
           Requires cvs-fast-export. 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’s file-oriented model.

       RCS
           Requires cvs-fast-export (yes, that’s not a typo; cvs-fast-export handles RCS
           collections as well). The caveat for CVS applies.

       bk
           Versions 7.3 and after have a fast-export command that reposurgeon can use.

ERROR RETURNS

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

SEE ALSO

       bzr(1), cvs(1), darcs(1), git(1), hg(1), rcs(1), src(1), svn(1), bk(1).

AUTHOR

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

                                            2022-01-12                             REPOSURGEON(1)