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 vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 10/27/2022
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.38.1.220.g9388e93f00
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CVSIMPORT" "1" "10/27/2022" "Git 2\&.38\&.1\&.220\&.g9388e9" "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 \fBhttp://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 \%http://www.catb.org/esr/cvs-fast-export/
 362 .RE