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