man1/git-cvsimport.1

   1 '\" t
   2 .\"     Title: git-cvsimport
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-18
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.1.565.g6531f31ef3
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CVSIMPORT" "1" "2024-09-18" "Git 2\&.46\&.1\&.565\&.g6531f3" "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 .SH "DESCRIPTION"
  42 .sp
  43 \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\&.
  44 .sp
  45 Imports a CVS repository into Git\&. It will either create a new repository, or incrementally import into an existing one\&.
  46 .sp
  47 Splitting the CVS log into patch sets is done by \fIcvsps\fR\&. At least version 2\&.1 is required\&.
  48 .sp
  49 \fBWARNING:\fR for certain situations the import leads to incorrect results\&. Please see the section ISSUES for further reference\&.
  50 .sp
  51 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\&.
  52 .sp
  53 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)\&.
  54 .SH "OPTIONS"
  55 .PP
  56 \-v
  57 .RS 4
  58 Verbosity: let
  59 \fIcvsimport\fR
  60 report what it is doing\&.
  61 .RE
  62 .PP
  63 \-d <CVSROOT>
  64 .RS 4
  65 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,
  66 \fIgit cvsimport\fR
  67 will try to read it from
  68 \fBCVS/Root\fR\&. If no such file exists, it checks for the
  69 \fBCVSROOT\fR
  70 environment variable\&.
  71 .RE
  72 .PP
  73 <CVS\-module>
  74 .RS 4
  75 The CVS module you want to import\&. Relative to <CVSROOT>\&. If not given,
  76 \fIgit cvsimport\fR
  77 tries to read it from
  78 \fBCVS/Repository\fR\&.
  79 .RE
  80 .PP
  81 \-C <target\-dir>
  82 .RS 4
  83 The Git repository to import to\&. If the directory doesn\(cqt exist, it will be created\&. Default is the current directory\&.
  84 .RE
  85 .PP
  86 \-r <remote>
  87 .RS 4
  88 The Git remote to import this CVS repository into\&. Moves all CVS branches into remotes/<remote>/<branch> akin to the way
  89 \fIgit clone\fR
  90 uses
  91 \fIorigin\fR
  92 by default\&.
  93 .RE
  94 .PP
  95 \-o <branch\-for\-HEAD>
  96 .RS 4
  97 When no remote is specified (via \-r) the
  98 \fBHEAD\fR
  99 branch from CVS is imported to the
 100 \fIorigin\fR
 101 branch within the Git repository, as
 102 \fBHEAD\fR
 103 already has a special meaning for Git\&. When a remote is specified the
 104 \fBHEAD\fR
 105 branch is named remotes/<remote>/master mirroring
 106 \fIgit clone\fR
 107 behaviour\&. Use this option if you want to import into a different branch\&.
 108 .sp
 109 Use
 110 \fI\-o master\fR
 111 for continuing an import that was initially done by the old cvs2git tool\&.
 112 .RE
 113 .PP
 114 \-i
 115 .RS 4
 116 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\&.
 117 .RE
 118 .PP
 119 \-k
 120 .RS 4
 121 Kill keywords: will extract files with
 122 \fI\-kk\fR
 123 from the CVS archive to avoid noisy changesets\&. Highly recommended, but off by default to preserve compatibility with early imported trees\&.
 124 .RE
 125 .PP
 126 \-u
 127 .RS 4
 128 Convert underscores in tag and branch names to dots\&.
 129 .RE
 130 .PP
 131 \-s <subst>
 132 .RS 4
 133 Substitute the character "/" in branch names with <subst>
 134 .RE
 135 .PP
 136 \-p <options\-for\-cvsps>
 137 .RS 4
 138 Additional options for cvsps\&. The options
 139 \fB\-u\fR
 140 and
 141 \fI\-A\fR
 142 are implicit and should not be used here\&.
 143 .sp
 144 If you need to pass multiple options, separate them with a comma\&.
 145 .RE
 146 .PP
 147 \-z <fuzz>
 148 .RS 4
 149 Pass the timestamp fuzz factor to cvsps, in seconds\&. If unset, cvsps defaults to 300s\&.
 150 .RE
 151 .PP
 152 \-P <cvsps\-output\-file>
 153 .RS 4
 154 Instead of calling cvsps, read the provided cvsps output file\&. Useful for debugging or when cvsps is being handled outside cvsimport\&.
 155 .RE
 156 .PP
 157 \-m
 158 .RS 4
 159 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\&.
 160 .RE
 161 .PP
 162 \-M <regex>
 163 .RS 4
 164 Attempt to detect merges based on the commit message with a custom regex\&. It can be used with
 165 \fB\-m\fR
 166 to enable the default regexes as well\&. You must escape forward slashes\&.
 167 .sp
 168 The regex must capture the source branch name in $1\&.
 169 .sp
 170 This option can be used several times to provide several detection regexes\&.
 171 .RE
 172 .PP
 173 \-S <regex>
 174 .RS 4
 175 Skip paths matching the regex\&.
 176 .RE
 177 .PP
 178 \-a
 179 .RS 4
 180 Import all commits, including recent ones\&. cvsimport by default skips commits that have a timestamp less than 10 minutes ago\&.
 181 .RE
 182 .PP
 183 \-L <limit>
 184 .RS 4
 185 Limit the number of commits imported\&. Workaround for cases where cvsimport leaks memory\&.
 186 .RE
 187 .PP
 188 \-A <author\-conv\-file>
 189 .RS 4
 190 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:
 191 .sp
 192 .if n \{\
 193 .RS 4
 194 .\}
 195 .nf
 196         exon=Andreas Ericsson <ae@op5\&.se>
 197         spawn=Simon Pawn <spawn@frog\-pond\&.org> America/Chicago
 198 .fi
 199 .if n \{\
 200 .RE
 201 .\}
 202 .sp
 203 \fIgit cvsimport\fR
 204 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\&.
 205 .sp
 206 For convenience, this data is saved to
 207 \fB$GIT_DIR/cvs\-authors\fR
 208 each time the
 209 \fI\-A\fR
 210 option is provided and read from that same file each time
 211 \fIgit cvsimport\fR
 212 is run\&.
 213 .sp
 214 It is not recommended to use this feature if you intend to export changes back to CVS again later with
 215 \fIgit cvsexportcommit\fR\&.
 216 .RE
 217 .PP
 218 \-R
 219 .RS 4
 220 Generate a
 221 \fB$GIT_DIR/cvs\-revisions\fR
 222 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
 223 .sp
 224 .if n \{\
 225 .RS 4
 226 .\}
 227 .nf
 228 src/widget\&.c 1\&.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7
 229 .fi
 230 .if n \{\
 231 .RE
 232 .\}
 233 .sp
 234 The revision data is appended to the file if it already exists, for use when doing incremental imports\&.
 235 .sp
 236 This option may be useful if you have CVS revision numbers stored in commit messages, bug\-tracking systems, email archives, and the like\&.
 237 .RE
 238 .PP
 239 \-h
 240 .RS 4
 241 Print a short usage message and exit\&.
 242 .RE
 243 .SH "OUTPUT"
 244 .sp
 245 If \fB\-v\fR is specified, the script reports what it is doing\&.
 246 .sp
 247 Otherwise, success is indicated the Unix way, i\&.e\&. by simply exiting with a zero exit status\&.
 248 .SH "ISSUES"
 249 .sp
 250 Problems related to timestamps:
 251 .sp
 252 .RS 4
 253 .ie n \{\
 254 \h'-04'\(bu\h'+03'\c
 255 .\}
 256 .el \{\
 257 .sp -1
 258 .IP \(bu 2.3
 259 .\}
 260 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\&.
 261 .RE
 262 .sp
 263 .RS 4
 264 .ie n \{\
 265 \h'-04'\(bu\h'+03'\c
 266 .\}
 267 .el \{\
 268 .sp -1
 269 .IP \(bu 2.3
 270 .\}
 271 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\&.
 272 .RE
 273 .sp
 274 .RS 4
 275 .ie n \{\
 276 \h'-04'\(bu\h'+03'\c
 277 .\}
 278 .el \{\
 279 .sp -1
 280 .IP \(bu 2.3
 281 .\}
 282 If the timestamp order of different files cross the revision order within the commit matching time window the order of commits may be wrong\&.
 283 .RE
 284 .sp
 285 Problems related to branches:
 286 .sp
 287 .RS 4
 288 .ie n \{\
 289 \h'-04'\(bu\h'+03'\c
 290 .\}
 291 .el \{\
 292 .sp -1
 293 .IP \(bu 2.3
 294 .\}
 295 Branches on which no commits have been made are not imported\&.
 296 .RE
 297 .sp
 298 .RS 4
 299 .ie n \{\
 300 \h'-04'\(bu\h'+03'\c
 301 .\}
 302 .el \{\
 303 .sp -1
 304 .IP \(bu 2.3
 305 .\}
 306 All files from the branching point are added to a branch even if never added in CVS\&.
 307 .RE
 308 .sp
 309 .RS 4
 310 .ie n \{\
 311 \h'-04'\(bu\h'+03'\c
 312 .\}
 313 .el \{\
 314 .sp -1
 315 .IP \(bu 2.3
 316 .\}
 317 This applies to files added to the source branch
 318 \fBafter\fR
 319 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\&.
 320 .RE
 321 .sp
 322 Problems related to tags:
 323 .sp
 324 .RS 4
 325 .ie n \{\
 326 \h'-04'\(bu\h'+03'\c
 327 .\}
 328 .el \{\
 329 .sp -1
 330 .IP \(bu 2.3
 331 .\}
 332 Multiple tags on the same revision are not imported\&.
 333 .RE
 334 .sp
 335 If you suspect that any of these issues may apply to the repository you want to import, consider using cvs2git:
 336 .sp
 337 .RS 4
 338 .ie n \{\
 339 \h'-04'\(bu\h'+03'\c
 340 .\}
 341 .el \{\
 342 .sp -1
 343 .IP \(bu 2.3
 344 .\}
 345 cvs2git (part of cvs2svn),
 346 \fBhttps://subversion\&.apache\&.org/\fR
 347 .RE
 348 .SH "GIT"
 349 .sp
 350 Part of the \fBgit\fR(1) suite
 351 .SH "NOTES"
 352 .IP " 1." 4
 353 cvs2git
 354 .RS 4
 355 \%http://cvs2svn.tigris.org/cvs2git.html
 356 .RE
 357 .IP " 2." 4
 358 cvs-fast-export
 359 .RS 4
 360 \%https://gitlab.com/esr/cvs-fast-export
 361 .RE