]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-cvsimport(1) |
2 | ================ | |
f2114060 MU |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-cvsimport - Salvage your data out of another SCM people love to hate |
f2114060 MU |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
353ce815 | 11 | [verse] |
b1889c36 | 12 | 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] |
edbe4466 FL |
13 | [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] |
14 | [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] | |
15 | [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] | |
0455ec03 | 16 | [-r <remote>] [-R] [<CVS_module>] |
f2114060 MU |
17 | |
18 | ||
19 | DESCRIPTION | |
20 | ----------- | |
1187ec99 JK |
21 | *WARNING:* `git cvsimport` uses cvsps version 2, which is considered |
22 | deprecated; it does not work with cvsps version 3 and later. If you are | |
23 | performing a one-shot import of a CVS repository consider using | |
2df85669 | 24 | http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or |
1eba3e51 | 25 | http://www.catb.org/esr/cvs-fast-export/[cvs-fast-export]. |
1187ec99 | 26 | |
2de9b711 | 27 | Imports a CVS repository into Git. It will either create a new |
f2114060 MU |
28 | repository, or incrementally import into an existing one. |
29 | ||
1cd3674a | 30 | Splitting the CVS log into patch sets is done by 'cvsps'. |
f2114060 MU |
31 | At least version 2.1 is required. |
32 | ||
7c98213a HV |
33 | *WARNING:* for certain situations the import leads to incorrect results. |
34 | Please see the section <<issues,ISSUES>> for further reference. | |
35 | ||
a541211e | 36 | You should *never* do any work of your own on the branches that are |
0b444cdb | 37 | created by 'git cvsimport'. By default initial import will create and populate a |
a541211e | 38 | "master" branch from the CVS repository's main branch which you're free |
0b444cdb | 39 | to work with; after that, you need to 'git merge' incremental imports, or |
cbc9be5c AW |
40 | any CVS branches, yourself. It is advisable to specify a named remote via |
41 | -r to separate and protect the incoming branches. | |
42 | ||
a41a32bf MO |
43 | If you intend to set up a shared public repository that all developers can |
44 | read/write, or if you want to use linkgit:git-cvsserver[1], then you | |
45 | probably want to make a bare clone of the imported repository, | |
46 | and use the clone as the shared repository. | |
47 | See linkgit:gitcvs-migration[7]. | |
48 | ||
a541211e | 49 | |
f2114060 MU |
50 | OPTIONS |
51 | ------- | |
7b14b3c5 FL |
52 | -v:: |
53 | Verbosity: let 'cvsimport' report what it is doing. | |
54 | ||
f2114060 MU |
55 | -d <CVSROOT>:: |
56 | The root of the CVS archive. May be local (a simple path) or remote; | |
a6080a0a | 57 | currently, only the :local:, :ext: and :pserver: access methods |
0b444cdb | 58 | are supported. If not given, 'git cvsimport' will try to read it |
407049c5 FL |
59 | from `CVS/Root`. If no such file exists, it checks for the |
60 | `CVSROOT` environment variable. | |
f2114060 | 61 | |
7b14b3c5 FL |
62 | <CVS_module>:: |
63 | The CVS module you want to import. Relative to <CVSROOT>. | |
0b444cdb | 64 | If not given, 'git cvsimport' tries to read it from |
7b14b3c5 FL |
65 | `CVS/Repository`. |
66 | ||
b0921331 | 67 | -C <target-dir>:: |
2de9b711 | 68 | The Git repository to import to. If the directory doesn't |
b0921331 DK |
69 | exist, it will be created. Default is the current directory. |
70 | ||
cbc9be5c | 71 | -r <remote>:: |
2de9b711 | 72 | The Git remote to import this CVS repository into. |
cbc9be5c | 73 | Moves all CVS branches into remotes/<remote>/<branch> |
0b444cdb | 74 | akin to the way 'git clone' uses 'origin' by default. |
cbc9be5c | 75 | |
7b14b3c5 | 76 | -o <branch-for-HEAD>:: |
661c3e9b | 77 | When no remote is specified (via -r) the `HEAD` branch |
2de9b711 | 78 | from CVS is imported to the 'origin' branch within the Git |
661c3e9b MM |
79 | repository, as `HEAD` already has a special meaning for Git. |
80 | When a remote is specified the `HEAD` branch is named | |
0b444cdb | 81 | remotes/<remote>/master mirroring 'git clone' behaviour. |
cbc9be5c AW |
82 | Use this option if you want to import into a different |
83 | branch. | |
7b14b3c5 FL |
84 | + |
85 | Use '-o master' for continuing an import that was initially done by | |
86 | the old cvs2git tool. | |
87 | ||
c1c774e7 SV |
88 | -i:: |
89 | Import-only: don't perform a checkout after importing. This option | |
5f3aa197 | 90 | ensures the working directory and index remain untouched and will |
c1c774e7 SV |
91 | not create them if they do not exist. |
92 | ||
abe05822 | 93 | -k:: |
0e070f99 | 94 | Kill keywords: will extract files with '-kk' from the CVS archive |
abe05822 | 95 | to avoid noisy changesets. Highly recommended, but off by default |
a6080a0a | 96 | to preserve compatibility with early imported trees. |
abe05822 | 97 | |
0d821d4d PA |
98 | -u:: |
99 | Convert underscores in tag and branch names to dots. | |
100 | ||
7b14b3c5 FL |
101 | -s <subst>:: |
102 | Substitute the character "/" in branch names with <subst> | |
f2114060 MU |
103 | |
104 | -p <options-for-cvsps>:: | |
105 | Additional options for cvsps. | |
23f8239b | 106 | The options `-u` and '-A' are implicit and should not be used here. |
df8baa42 JF |
107 | + |
108 | If you need to pass multiple options, separate them with a comma. | |
f2114060 | 109 | |
7b14b3c5 FL |
110 | -z <fuzz>:: |
111 | Pass the timestamp fuzz factor to cvsps, in seconds. If unset, | |
112 | cvsps defaults to 300s. | |
113 | ||
56e5e917 | 114 | -P <cvsps-output-file>:: |
211dcac6 ML |
115 | Instead of calling cvsps, read the provided cvsps output file. Useful |
116 | for debugging or when cvsps is being handled outside cvsimport. | |
117 | ||
a6080a0a | 118 | -m:: |
db4b6582 | 119 | Attempt to detect merges based on the commit message. This option |
3c832a78 | 120 | will enable default regexes that try to capture the source |
a6080a0a | 121 | branch name from the commit message. |
db4b6582 ML |
122 | |
123 | -M <regex>:: | |
124 | Attempt to detect merges based on the commit message with a custom | |
23f8239b | 125 | regex. It can be used with `-m` to enable the default regexes |
8608b334 | 126 | as well. You must escape forward slashes. |
3c832a78 PB |
127 | + |
128 | The regex must capture the source branch name in $1. | |
129 | + | |
130 | This option can be used several times to provide several detection regexes. | |
db4b6582 | 131 | |
7b14b3c5 FL |
132 | -S <regex>:: |
133 | Skip paths matching the regex. | |
fbfd60d6 | 134 | |
ded9f400 ML |
135 | -a:: |
136 | Import all commits, including recent ones. cvsimport by default | |
137 | skips commits that have a timestamp less than 10 minutes ago. | |
eec84962 | 138 | |
eec84962 ML |
139 | -L <limit>:: |
140 | Limit the number of commits imported. Workaround for cases where | |
141 | cvsimport leaks memory. | |
142 | ||
0a43acbe MP |
143 | -A <author-conv-file>:: |
144 | CVS by default uses the Unix username when writing its | |
145 | commit logs. Using this option and an author-conv-file | |
fb2c9841 | 146 | maps the name recorded in CVS to author name, e-mail and |
0ffa154b | 147 | optional time zone: |
3070b603 FD |
148 | + |
149 | --------- | |
ffd97f3a | 150 | exon=Andreas Ericsson <ae@op5.se> |
fb2c9841 | 151 | spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago |
ffd97f3a | 152 | |
3070b603 FD |
153 | --------- |
154 | + | |
0b444cdb | 155 | 'git cvsimport' will make it appear as those authors had |
3070b603 | 156 | their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly |
0ffa154b | 157 | all along. If a time zone is specified, GIT_AUTHOR_DATE will |
fb2c9841 | 158 | have the corresponding offset applied. |
3070b603 | 159 | + |
407049c5 | 160 | For convenience, this data is saved to `$GIT_DIR/cvs-authors` |
0e070f99 | 161 | each time the '-A' option is provided and read from that same |
0b444cdb | 162 | file each time 'git cvsimport' is run. |
3070b603 FD |
163 | + |
164 | It is not recommended to use this feature if you intend to | |
165 | export changes back to CVS again later with | |
0b444cdb | 166 | 'git cvsexportcommit'. |
ffd97f3a | 167 | |
0455ec03 AC |
168 | -R:: |
169 | Generate a `$GIT_DIR/cvs-revisions` file containing a mapping from CVS | |
170 | revision numbers to newly-created Git commit IDs. The generated file | |
171 | will contain one line for each (filename, revision) pair imported; | |
172 | each line will look like | |
173 | + | |
174 | --------- | |
175 | src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7 | |
176 | --------- | |
177 | + | |
178 | The revision data is appended to the file if it already exists, for use when | |
179 | doing incremental imports. | |
180 | + | |
181 | This option may be useful if you have CVS revision numbers stored in commit | |
182 | messages, bug-tracking systems, email archives, and the like. | |
183 | ||
7b14b3c5 FL |
184 | -h:: |
185 | Print a short usage message and exit. | |
186 | ||
f2114060 MU |
187 | OUTPUT |
188 | ------ | |
23f8239b | 189 | If `-v` is specified, the script reports what it is doing. |
f2114060 MU |
190 | |
191 | Otherwise, success is indicated the Unix way, i.e. by simply exiting with | |
192 | a zero exit status. | |
193 | ||
7c98213a HV |
194 | [[issues]] |
195 | ISSUES | |
196 | ------ | |
197 | Problems related to timestamps: | |
198 | ||
6b677a28 | 199 | * If timestamps of commits in the CVS repository are not stable enough |
75fd877e HV |
200 | to be used for ordering commits changes may show up in the wrong |
201 | order. | |
7c98213a | 202 | * If any files were ever "cvs import"ed more than once (e.g., import of |
75fd877e | 203 | more than one vendor release) the HEAD contains the wrong content. |
7c98213a | 204 | * If the timestamp order of different files cross the revision order |
75fd877e HV |
205 | within the commit matching time window the order of commits may be |
206 | wrong. | |
7c98213a HV |
207 | |
208 | Problems related to branches: | |
209 | ||
75fd877e | 210 | * Branches on which no commits have been made are not imported. |
7c98213a | 211 | * All files from the branching point are added to a branch even if |
6b677a28 | 212 | never added in CVS. |
75fd877e HV |
213 | * This applies to files added to the source branch *after* a daughter |
214 | branch was created: if previously no commit was made on the daughter | |
215 | branch they will erroneously be added to the daughter branch in git. | |
7c98213a HV |
216 | |
217 | Problems related to tags: | |
218 | ||
75fd877e | 219 | * Multiple tags on the same revision are not imported. |
7c98213a HV |
220 | |
221 | If you suspect that any of these issues may apply to the repository you | |
f745acb0 | 222 | want to import, consider using cvs2git: |
7c98213a | 223 | |
95f95c99 | 224 | * cvs2git (part of cvs2svn), `http://subversion.apache.org/` |
f2114060 | 225 | |
f2114060 MU |
226 | GIT |
227 | --- | |
9e1f0a85 | 228 | Part of the linkgit:git[1] suite |