1REPOSURGEON(1) REPOSURGEON(1)
2
6 reposurgeon - surgical operations on repositories
7
9 reposurgeon [command...]
10
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 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 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 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 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 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 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 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 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 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 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
79 reposurgeon relies on importers and exporters associated with the VCSes
80 it supports.
81 git
83 Core git supports both export and import.
84 bzr
86 Requires bzr plus the bzr-fast-import plugin.
87 hg
89 Requires core hg and hg-git-fast-import.
90 svn
92 Stock Subversion commands support export and import.
93 darcs
95 Stock darcs commands support export.
96 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 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 bk
107 Versions 7.3 and after have a fast-export command that reposufreon
108 can use.
109
111 Returns 1 if the last command executed threw an error, 0 otherwise.
112
114 bzr(1), cvs(1), darcs(1), git(1), hg(1), rcs(1), src(1), svn(1), bk(1).
115
117 Eric S. Raymond <esr@thyrsus.com>; see the project page
118 <http://www.catb.org/~esr/reposurgeon>.
119 2021-06-11 REPOSURGEON(1)