| blob | dc0ab91cfbeec979113735ca8ba8e37717cc8f81 |
1 '\" t
2 .\" Title: git-cvsimport
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2024-04-10
6 .\" Manual: Git Manual
7 .\" Source: Git 2.44.0.568.g436d4e5b14
8 .\" Language: English
9 .\"
10 .TH "GIT\-CVSIMPORT" "1" "2024\-04\-10" "Git 2\&.44\&.0\&.568\&.g436d4e" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-cvsimport \- Salvage your data out of another SCM people love to hate
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit cvsimport\fR [\-o <branch\-for\-HEAD>] [\-h] [\-v] [\-d <CVSROOT>]
36 [\-A <author\-conv\-file>] [\-p <options\-for\-cvsps>] [\-P <file>]
37 [\-C <git\-repository>] [\-z <fuzz>] [\-i] [\-k] [\-u] [\-s <subst>]
38 [\-a] [\-m] [\-M <regex>] [\-S <regex>] [\-L <commit\-limit>]
39 [\-r <remote>] [\-R] [<CVS\-module>]
40 .fi
41 .sp
42 .SH "DESCRIPTION"
43 .sp
44 \fBWARNING:\fR \fBgit cvsimport\fR uses cvsps version 2, which is considered deprecated; it does not work with cvsps version 3 and later\&. If you are performing a one\-shot import of a CVS repository consider using \m[blue]\fBcvs2git\fR\m[]\&\s-2\u[1]\d\s+2 or \m[blue]\fBcvs\-fast\-export\fR\m[]\&\s-2\u[2]\d\s+2\&.
45 .sp
46 Imports a CVS repository into Git\&. It will either create a new repository, or incrementally import into an existing one\&.
47 .sp
48 Splitting the CVS log into patch sets is done by \fIcvsps\fR\&. At least version 2\&.1 is required\&.
49 .sp
50 \fBWARNING:\fR for certain situations the import leads to incorrect results\&. Please see the section ISSUES for further reference\&.
51 .sp
52 You should \fBnever\fR do any work of your own on the branches that are created by \fIgit cvsimport\fR\&. By default initial import will create and populate a "master" branch from the CVS repository\(cqs main branch which you\(cqre free to work with; after that, you need to \fIgit merge\fR incremental imports, or any CVS branches, yourself\&. It is advisable to specify a named remote via \-r to separate and protect the incoming branches\&.
53 .sp
54 If you intend to set up a shared public repository that all developers can read/write, or if you want to use \fBgit-cvsserver\fR(1), then you probably want to make a bare clone of the imported repository, and use the clone as the shared repository\&. See \fBgitcvs-migration\fR(7)\&.
55 .SH "OPTIONS"
56 .PP
57 \-v
58 .RS 4
59 Verbosity: let
60 \fIcvsimport\fR
61 report what it is doing\&.
62 .RE
63 .PP
64 \-d <CVSROOT>
65 .RS 4
66 The root of the CVS archive\&. May be local (a simple path) or remote; currently, only the :local:, :ext: and :pserver: access methods are supported\&. If not given,
67 \fIgit cvsimport\fR
68 will try to read it from
69 \fBCVS/Root\fR\&. If no such file exists, it checks for the
70 \fBCVSROOT\fR
71 environment variable\&.
72 .RE
73 .PP
74 <CVS\-module>
75 .RS 4
76 The CVS module you want to import\&. Relative to <CVSROOT>\&. If not given,
77 \fIgit cvsimport\fR
78 tries to read it from
79 \fBCVS/Repository\fR\&.
80 .RE
81 .PP
82 \-C <target\-dir>
83 .RS 4
84 The Git repository to import to\&. If the directory doesn\(cqt exist, it will be created\&. Default is the current directory\&.
85 .RE
86 .PP
87 \-r <remote>
88 .RS 4
89 The Git remote to import this CVS repository into\&. Moves all CVS branches into remotes/<remote>/<branch> akin to the way
90 \fIgit clone\fR
91 uses
92 \fIorigin\fR
93 by default\&.
94 .RE
95 .PP
96 \-o <branch\-for\-HEAD>
97 .RS 4
98 When no remote is specified (via \-r) the
99 \fBHEAD\fR
100 branch from CVS is imported to the
101 \fIorigin\fR
102 branch within the Git repository, as
103 \fBHEAD\fR
104 already has a special meaning for Git\&. When a remote is specified the
105 \fBHEAD\fR
106 branch is named remotes/<remote>/master mirroring
107 \fIgit clone\fR
108 behaviour\&. Use this option if you want to import into a different branch\&.
109 .sp
110 Use
111 \fI\-o master\fR
112 for continuing an import that was initially done by the old cvs2git tool\&.
113 .RE
114 .PP
115 \-i
116 .RS 4
117 Import\-only: don\(cqt perform a checkout after importing\&. This option ensures the working directory and index remain untouched and will not create them if they do not exist\&.
118 .RE
119 .PP
120 \-k
121 .RS 4
122 Kill keywords: will extract files with
123 \fI\-kk\fR
124 from the CVS archive to avoid noisy changesets\&. Highly recommended, but off by default to preserve compatibility with early imported trees\&.
125 .RE
126 .PP
127 \-u
128 .RS 4
129 Convert underscores in tag and branch names to dots\&.
130 .RE
131 .PP
132 \-s <subst>
133 .RS 4
134 Substitute the character "/" in branch names with <subst>
135 .RE
136 .PP
137 \-p <options\-for\-cvsps>
138 .RS 4
139 Additional options for cvsps\&. The options
140 \fB\-u\fR
141 and
142 \fI\-A\fR
143 are implicit and should not be used here\&.
144 .sp
145 If you need to pass multiple options, separate them with a comma\&.
146 .RE
147 .PP
148 \-z <fuzz>
149 .RS 4
150 Pass the timestamp fuzz factor to cvsps, in seconds\&. If unset, cvsps defaults to 300s\&.
151 .RE
152 .PP
153 \-P <cvsps\-output\-file>
154 .RS 4
155 Instead of calling cvsps, read the provided cvsps output file\&. Useful for debugging or when cvsps is being handled outside cvsimport\&.
156 .RE
157 .PP
158 \-m
159 .RS 4
160 Attempt to detect merges based on the commit message\&. This option will enable default regexes that try to capture the source branch name from the commit message\&.
161 .RE
162 .PP
163 \-M <regex>
164 .RS 4
165 Attempt to detect merges based on the commit message with a custom regex\&. It can be used with
166 \fB\-m\fR
167 to enable the default regexes as well\&. You must escape forward slashes\&.
168 .sp
169 The regex must capture the source branch name in $1\&.
170 .sp
171 This option can be used several times to provide several detection regexes\&.
172 .RE
173 .PP
174 \-S <regex>
175 .RS 4
176 Skip paths matching the regex\&.
177 .RE
178 .PP
179 \-a
180 .RS 4
181 Import all commits, including recent ones\&. cvsimport by default skips commits that have a timestamp less than 10 minutes ago\&.
182 .RE
183 .PP
184 \-L <limit>
185 .RS 4
186 Limit the number of commits imported\&. Workaround for cases where cvsimport leaks memory\&.
187 .RE
188 .PP
189 \-A <author\-conv\-file>
190 .RS 4
191 CVS by default uses the Unix username when writing its commit logs\&. Using this option and an author\-conv\-file maps the name recorded in CVS to author name, e\-mail and optional time zone:
192 .sp
193 .if n \{\
194 .RS 4
195 .\}
196 .nf
197 exon=Andreas Ericsson <ae@op5\&.se>
198 spawn=Simon Pawn <spawn@frog\-pond\&.org> America/Chicago
199 .fi
200 .if n \{\
201 .RE
202 .\}
203 .sp
204 \fIgit cvsimport\fR
205 will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly all along\&. If a time zone is specified, GIT_AUTHOR_DATE will have the corresponding offset applied\&.
206 .sp
207 For convenience, this data is saved to
208 \fB$GIT_DIR/cvs\-authors\fR
209 each time the
210 \fI\-A\fR
211 option is provided and read from that same file each time
212 \fIgit cvsimport\fR
213 is run\&.
214 .sp
215 It is not recommended to use this feature if you intend to export changes back to CVS again later with
216 \fIgit cvsexportcommit\fR\&.
217 .RE
218 .PP
219 \-R
220 .RS 4
221 Generate a
222 \fB$GIT_DIR/cvs\-revisions\fR
223 file containing a mapping from CVS revision numbers to newly\-created Git commit IDs\&. The generated file will contain one line for each (filename, revision) pair imported; each line will look like
224 .sp
225 .if n \{\
226 .RS 4
227 .\}
228 .nf
229 src/widget\&.c 1\&.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7
230 .fi
231 .if n \{\
232 .RE
233 .\}
234 .sp
235 The revision data is appended to the file if it already exists, for use when doing incremental imports\&.
236 .sp
237 This option may be useful if you have CVS revision numbers stored in commit messages, bug\-tracking systems, email archives, and the like\&.
238 .RE
239 .PP
240 \-h
241 .RS 4
242 Print a short usage message and exit\&.
243 .RE
244 .SH "OUTPUT"
245 .sp
246 If \fB\-v\fR is specified, the script reports what it is doing\&.
247 .sp
248 Otherwise, success is indicated the Unix way, i\&.e\&. by simply exiting with a zero exit status\&.
249 .SH "ISSUES"
250 .sp
251 Problems related to timestamps:
252 .sp
253 .RS 4
254 .ie n \{\
255 \h'-04'\(bu\h'+03'\c
256 .\}
257 .el \{\
258 .sp -1
259 .IP \(bu 2.3
260 .\}
261 If timestamps of commits in the CVS repository are not stable enough to be used for ordering commits changes may show up in the wrong order\&.
262 .RE
263 .sp
264 .RS 4
265 .ie n \{\
266 \h'-04'\(bu\h'+03'\c
267 .\}
268 .el \{\
269 .sp -1
270 .IP \(bu 2.3
271 .\}
272 If any files were ever "cvs import"ed more than once (e\&.g\&., import of more than one vendor release) the HEAD contains the wrong content\&.
273 .RE
274 .sp
275 .RS 4
276 .ie n \{\
277 \h'-04'\(bu\h'+03'\c
278 .\}
279 .el \{\
280 .sp -1
281 .IP \(bu 2.3
282 .\}
283 If the timestamp order of different files cross the revision order within the commit matching time window the order of commits may be wrong\&.
284 .RE
285 .sp
286 Problems related to branches:
287 .sp
288 .RS 4
289 .ie n \{\
290 \h'-04'\(bu\h'+03'\c
291 .\}
292 .el \{\
293 .sp -1
294 .IP \(bu 2.3
295 .\}
296 Branches on which no commits have been made are not imported\&.
297 .RE
298 .sp
299 .RS 4
300 .ie n \{\
301 \h'-04'\(bu\h'+03'\c
302 .\}
303 .el \{\
304 .sp -1
305 .IP \(bu 2.3
306 .\}
307 All files from the branching point are added to a branch even if never added in CVS\&.
308 .RE
309 .sp
310 .RS 4
311 .ie n \{\
312 \h'-04'\(bu\h'+03'\c
313 .\}
314 .el \{\
315 .sp -1
316 .IP \(bu 2.3
317 .\}
318 This applies to files added to the source branch
319 \fBafter\fR
320 a daughter branch was created: if previously no commit was made on the daughter branch they will erroneously be added to the daughter branch in git\&.
321 .RE
322 .sp
323 Problems related to tags:
324 .sp
325 .RS 4
326 .ie n \{\
327 \h'-04'\(bu\h'+03'\c
328 .\}
329 .el \{\
330 .sp -1
331 .IP \(bu 2.3
332 .\}
333 Multiple tags on the same revision are not imported\&.
334 .RE
335 .sp
336 If you suspect that any of these issues may apply to the repository you want to import, consider using cvs2git:
337 .sp
338 .RS 4
339 .ie n \{\
340 \h'-04'\(bu\h'+03'\c
341 .\}
342 .el \{\
343 .sp -1
344 .IP \(bu 2.3
345 .\}
346 cvs2git (part of cvs2svn),
347 \fBhttps://subversion\&.apache\&.org/\fR
348 .RE
349 .SH "GIT"
350 .sp
351 Part of the \fBgit\fR(1) suite
352 .SH "NOTES"
353 .IP " 1." 4
354 cvs2git
355 .RS 4
356 \%http://cvs2svn.tigris.org/cvs2git.html
357 .RE
358 .IP " 2." 4
359 cvs-fast-export
360 .RS 4
361 \%https://gitlab.com/esr/cvs-fast-export
362 .RE