1REPOSURGEON(1)                                                  REPOSURGEON(1)
2
3
4

NAME

6       reposurgeon - surgical operations on repositories
7

SYNOPSIS

9       reposurgeon [command...]
10

DESCRIPTION

12       The purpose of reposurgeon is to enable risky operations that VCSes
13       (version-control systems) don’t want to let you do, such as (a) editing
14       past comments and metadata, (b) excising commits, (c) coalescing and
15       splitting commits, (d) removing files and subtrees from repo history,
16       (e) merging or grafting two or more repos, and (f) cutting a repo in
17       two by cutting a parent-child link, preserving the branch structure of
18       both child repos.
19
20       A major use of reposurgeon is to assist a human operator to perform
21       higher-quality conversions among version control systems than can be
22       achieved with fully automated converters.
23
24       The original motivation for reposurgeon was to clean up artifacts
25       created by repository conversions. It was foreseen that the tool would
26       also have applications when code needs to be removed from repositories
27       for legal or policy reasons.
28
29       To keep reposurgeon simple and flexible, it normally does not do its
30       own repository reading and writing. Instead, it relies on being able to
31       parse and emit the command streams created by git-fast-export and read
32       by git-fast-import. This means that it can be used on any
33       version-control system that has both fast-export and fast-import
34       utilities. The git-import stream format also implicitly defines a
35       common language of primitive operations for reposurgeon to speak.
36
37       Fully supported systems (those for which reposurgeon can both read and
38       write repositories) include git, hg, bzr, darcs, bk, RCS, and SRC. For
39       a complete list, with dependencies and technical notes, type "prefer"
40       to the reposurgeon prompt.
41
42       Writing to the file-oriented systems RCS and SRC is done via
43       rcs-fast-import(1) and has some serious limitations because those
44       systems cannot represent all the metadata in a git-fast-export stream.
45       Consult that tool’s documentation for details and partial workarounds.
46
47       Fossil repository files can be read in using the --format=fossil option
48       of the ‘read’ command and written out with the --format=fossil option
49       of the ‘write’. Ignore patterns are not translated in either direction.
50
51       SVN and CVS are supported for read only, not write. For CVS,
52       reposurgeon must be run from within a repository directory (that is, a
53       tree of CVS masters; a CVSROOT is not required). When reading from a
54       CVS top-level directory each module becomes a subdirectory in the
55       reposurgeon representation of the change history. It is also possible
56       to read a repository from within a CVS module subdirectory and lift
57       that individual module.
58
59       In order to deal with version-control systems that do not have
60       fast-export equivalents, reposurgeon can also host extractor code that
61       reads repositories directly. For each version-control system supported
62       through an extractor, reposurgeon uses a small amount of knowledge
63       about the system’s command-line tools to (in effect) replay repository
64       history into an input stream internally. Repositories under systems
65       supported through extractors can be read by reposurgeon, but not
66       modified by it. In particular, reposurgeon can be used to move a
67       repository history from any VCS supported by an extractor to any VCS
68       supported by a normal importer/exporter pair.
69
70       Mercurial repository reading is implemented with an extractor class;
71       writing is handled with hg-git-fast-import. A test extractor exists for
72       git, but is normally disabled in favor of the regular exporter.
73
74       For details on how to operate reposurgeon, see the Repository Editing
75       and <http://www.catb.org/esr/reposurgeon/repository-editing.html>
76       Conversion With Reposurgeon" .
77

REQUIREMENTS

79       reposurgeon relies on importers and exporters associated with the VCSes
80       it supports.
81
82       git
83           Core git supports both export and import.
84
85       bzr
86           Requires bzr plus the bzr-fast-import plugin.
87
88       hg
89           Requires core hg and hg-git-fast-import.
90
91       svn
92           Stock Subversion commands support export and import.
93
94       darcs
95           Stock darcs commands support export.
96
97       CVS
98           Requires cvs-fast-export. Note that the quality of CVS lifts may be
99           poor, with individual lifts requiring serious hand-hacking. This is
100           due to inherent problems with CVS’s file-oriented model.
101
102       RCS
103           Requires cvs-fast-export (yes, that’s not a typo; cvs-fast-export
104           handles RCS collections as well). The caveat for CVS applies.
105
106       bk
107           Versions 7.3 and after have a fast-export command that reposufreon
108           can use.
109

ERROR RETURNS

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

SEE ALSO

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

AUTHOR

117       Eric S. Raymond <esr@thyrsus.com>; see the project page
118       <http://www.catb.org/~esr/reposurgeon>.
119
120
121
122                                  2021-01-12                    REPOSURGEON(1)
Impressum