git-cvsimport.1 (10403B)
- '\" t
- .\" Title: git-cvsimport
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-CVSIMPORT" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- git-cvsimport \- Salvage your data out of another SCM people love to hate
- .SH "SYNOPSIS"
- .sp
- .nf
- \fIgit cvsimport\fR [\-o <branch\-for\-HEAD>] [\-h] [\-v] [\-d <CVSROOT>]
- [\-A <author\-conv\-file>] [\-p <options\-for\-cvsps>] [\-P <file>]
- [\-C <git\-repository>] [\-z <fuzz>] [\-i] [\-k] [\-u] [\-s <subst>]
- [\-a] [\-m] [\-M <regex>] [\-S <regex>] [\-L <commit\-limit>]
- [\-r <remote>] [\-R] [<CVS\-module>]
- .fi
- .SH "DESCRIPTION"
- .sp
- \fBWARNING:\fR \fBgit\fR \fBcvsimport\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\&.
- .sp
- Imports a CVS repository into Git\&. It will either create a new repository, or incrementally import into an existing one\&.
- .sp
- Splitting the CVS log into patch sets is done by \fIcvsps\fR\&. At least version 2\&.1 is required\&.
- .sp
- \fBWARNING:\fR for certain situations the import leads to incorrect results\&. Please see the section ISSUES for further reference\&.
- .sp
- 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\&.
- .sp
- 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)\&.
- .SH "OPTIONS"
- .PP
- \-v
- .RS 4
- Verbosity: let
- \fIcvsimport\fR
- report what it is doing\&.
- .RE
- .PP
- \-d <CVSROOT>
- .RS 4
- 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,
- \fIgit cvsimport\fR
- will try to read it from
- \fBCVS/Root\fR\&. If no such file exists, it checks for the
- \fBCVSROOT\fR
- environment variable\&.
- .RE
- .PP
- <CVS\-module>
- .RS 4
- The CVS module you want to import\&. Relative to <CVSROOT>\&. If not given,
- \fIgit cvsimport\fR
- tries to read it from
- \fBCVS/Repository\fR\&.
- .RE
- .PP
- \-C <target\-dir>
- .RS 4
- The Git repository to import to\&. If the directory doesn\(cqt exist, it will be created\&. Default is the current directory\&.
- .RE
- .PP
- \-r <remote>
- .RS 4
- The Git remote to import this CVS repository into\&. Moves all CVS branches into remotes/<remote>/<branch> akin to the way
- \fIgit clone\fR
- uses
- \fIorigin\fR
- by default\&.
- .RE
- .PP
- \-o <branch\-for\-HEAD>
- .RS 4
- When no remote is specified (via \-r) the
- \fBHEAD\fR
- branch from CVS is imported to the
- \fIorigin\fR
- branch within the Git repository, as
- \fBHEAD\fR
- already has a special meaning for Git\&. When a remote is specified the
- \fBHEAD\fR
- branch is named remotes/<remote>/master mirroring
- \fIgit clone\fR
- behaviour\&. Use this option if you want to import into a different branch\&.
- .sp
- Use
- \fI\-o master\fR
- for continuing an import that was initially done by the old cvs2git tool\&.
- .RE
- .PP
- \-i
- .RS 4
- 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\&.
- .RE
- .PP
- \-k
- .RS 4
- Kill keywords: will extract files with
- \fI\-kk\fR
- from the CVS archive to avoid noisy changesets\&. Highly recommended, but off by default to preserve compatibility with early imported trees\&.
- .RE
- .PP
- \-u
- .RS 4
- Convert underscores in tag and branch names to dots\&.
- .RE
- .PP
- \-s <subst>
- .RS 4
- Substitute the character "/" in branch names with <subst>
- .RE
- .PP
- \-p <options\-for\-cvsps>
- .RS 4
- Additional options for cvsps\&. The options
- \fB\-u\fR
- and
- \fI\-A\fR
- are implicit and should not be used here\&.
- .sp
- If you need to pass multiple options, separate them with a comma\&.
- .RE
- .PP
- \-z <fuzz>
- .RS 4
- Pass the timestamp fuzz factor to cvsps, in seconds\&. If unset, cvsps defaults to 300s\&.
- .RE
- .PP
- \-P <cvsps\-output\-file>
- .RS 4
- Instead of calling cvsps, read the provided cvsps output file\&. Useful for debugging or when cvsps is being handled outside cvsimport\&.
- .RE
- .PP
- \-m
- .RS 4
- 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\&.
- .RE
- .PP
- \-M <regex>
- .RS 4
- Attempt to detect merges based on the commit message with a custom regex\&. It can be used with
- \fB\-m\fR
- to enable the default regexes as well\&. You must escape forward slashes\&.
- .sp
- The regex must capture the source branch name in $1\&.
- .sp
- This option can be used several times to provide several detection regexes\&.
- .RE
- .PP
- \-S <regex>
- .RS 4
- Skip paths matching the regex\&.
- .RE
- .PP
- \-a
- .RS 4
- Import all commits, including recent ones\&. cvsimport by default skips commits that have a timestamp less than 10 minutes ago\&.
- .RE
- .PP
- \-L <limit>
- .RS 4
- Limit the number of commits imported\&. Workaround for cases where cvsimport leaks memory\&.
- .RE
- .PP
- \-A <author\-conv\-file>
- .RS 4
- 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:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- exon=Andreas Ericsson <ae@op5\&.se>
- spawn=Simon Pawn <spawn@frog\-pond\&.org> America/Chicago
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- \fIgit cvsimport\fR
- 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\&.
- .sp
- For convenience, this data is saved to
- \fB$GIT_DIR/cvs\-authors\fR
- each time the
- \fI\-A\fR
- option is provided and read from that same file each time
- \fIgit cvsimport\fR
- is run\&.
- .sp
- It is not recommended to use this feature if you intend to export changes back to CVS again later with
- \fIgit cvsexportcommit\fR\&.
- .RE
- .PP
- \-R
- .RS 4
- Generate a
- \fB$GIT_DIR/cvs\-revisions\fR
- 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
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- src/widget\&.c 1\&.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- The revision data is appended to the file if it already exists, for use when doing incremental imports\&.
- .sp
- This option may be useful if you have CVS revision numbers stored in commit messages, bug\-tracking systems, email archives, and the like\&.
- .RE
- .PP
- \-h
- .RS 4
- Print a short usage message and exit\&.
- .RE
- .SH "OUTPUT"
- .sp
- If \fB\-v\fR is specified, the script reports what it is doing\&.
- .sp
- Otherwise, success is indicated the Unix way, i\&.e\&. by simply exiting with a zero exit status\&.
- .SH "ISSUES"
- .sp
- Problems related to timestamps:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- 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\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- 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\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- If the timestamp order of different files cross the revision order within the commit matching time window the order of commits may be wrong\&.
- .RE
- .sp
- Problems related to branches:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Branches on which no commits have been made are not imported\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- All files from the branching point are added to a branch even if never added in CVS\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- This applies to files added to the source branch
- \fBafter\fR
- 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\&.
- .RE
- .sp
- Problems related to tags:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Multiple tags on the same revision are not imported\&.
- .RE
- .sp
- If you suspect that any of these issues may apply to the repository you want to import, consider using cvs2git:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- cvs2git (part of cvs2svn),
- \fBhttps://subversion\&.apache\&.org/\fR
- .RE
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite
- .SH "NOTES"
- .IP " 1." 4
- cvs2git
- .RS 4
- \%http://cvs2svn.tigris.org/cvs2git.html
- .RE
- .IP " 2." 4
- cvs-fast-export
- .RS 4
- \%https://gitlab.com/esr/cvs-fast-export
- .RE