| 1 | git-cvsserver(1) |
| 2 | ================ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-cvsserver - A CVS server emulator for Git |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | |
| 11 | SSH: |
| 12 | |
| 13 | [verse] |
| 14 | export CVS_SERVER="git cvsserver" |
| 15 | 'cvs' -d :ext:user@server/path/repo.git co <HEAD_name> |
| 16 | |
| 17 | pserver (/etc/inetd.conf): |
| 18 | |
| 19 | [verse] |
| 20 | cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver |
| 21 | |
| 22 | Usage: |
| 23 | |
| 24 | [verse] |
| 25 | 'git-cvsserver' [<options>] [pserver|server] [<directory> ...] |
| 26 | |
| 27 | DESCRIPTION |
| 28 | ----------- |
| 29 | |
| 30 | This application is a CVS emulation layer for Git. |
| 31 | |
| 32 | It is highly functional. However, not all methods are implemented, |
| 33 | and for those methods that are implemented, |
| 34 | not all switches are implemented. |
| 35 | |
| 36 | Testing has been done using both the CLI CVS client, and the Eclipse CVS |
| 37 | plugin. Most functionality works fine with both of these clients. |
| 38 | |
| 39 | OPTIONS |
| 40 | ------- |
| 41 | |
| 42 | All these options obviously only make sense if enforced by the server side. |
| 43 | They have been implemented to resemble the linkgit:git-daemon[1] options as |
| 44 | closely as possible. |
| 45 | |
| 46 | --base-path <path>:: |
| 47 | Prepend 'path' to requested CVSROOT |
| 48 | |
| 49 | --strict-paths:: |
| 50 | Don't allow recursing into subdirectories |
| 51 | |
| 52 | --export-all:: |
| 53 | Don't check for `gitcvs.enabled` in config. You also have to specify a list |
| 54 | of allowed directories (see below) if you want to use this option. |
| 55 | |
| 56 | -V:: |
| 57 | --version:: |
| 58 | Print version information and exit |
| 59 | |
| 60 | -h:: |
| 61 | -H:: |
| 62 | --help:: |
| 63 | Print usage information and exit |
| 64 | |
| 65 | <directory>:: |
| 66 | The remaining arguments provide a list of directories. If no directories |
| 67 | are given, then all are allowed. Repositories within these directories |
| 68 | still require the `gitcvs.enabled` config option, unless `--export-all` |
| 69 | is specified. |
| 70 | |
| 71 | LIMITATIONS |
| 72 | ----------- |
| 73 | |
| 74 | CVS clients cannot tag, branch or perform Git merges. |
| 75 | |
| 76 | 'git-cvsserver' maps Git branches to CVS modules. This is very different |
| 77 | from what most CVS users would expect since in CVS modules usually represent |
| 78 | one or more directories. |
| 79 | |
| 80 | INSTALLATION |
| 81 | ------------ |
| 82 | |
| 83 | 1. If you are going to offer CVS access via pserver, add a line in |
| 84 | /etc/inetd.conf like |
| 85 | + |
| 86 | -- |
| 87 | ------ |
| 88 | cvspserver stream tcp nowait nobody git-cvsserver pserver |
| 89 | |
| 90 | ------ |
| 91 | Note: Some inetd servers let you specify the name of the executable |
| 92 | independently of the value of argv[0] (i.e. the name the program assumes |
| 93 | it was executed with). In this case the correct line in /etc/inetd.conf |
| 94 | looks like |
| 95 | |
| 96 | ------ |
| 97 | cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver |
| 98 | |
| 99 | ------ |
| 100 | |
| 101 | Only anonymous access is provided by pserver by default. To commit you |
| 102 | will have to create pserver accounts, simply add a gitcvs.authdb |
| 103 | setting in the config file of the repositories you want the cvsserver |
| 104 | to allow writes to, for example: |
| 105 | |
| 106 | ------ |
| 107 | |
| 108 | [gitcvs] |
| 109 | authdb = /etc/cvsserver/passwd |
| 110 | |
| 111 | ------ |
| 112 | The format of these files is username followed by the encrypted password, |
| 113 | for example: |
| 114 | |
| 115 | ------ |
| 116 | myuser:sqkNi8zPf01HI |
| 117 | myuser:$1$9K7FzU28$VfF6EoPYCJEYcVQwATgOP/ |
| 118 | myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3 |
| 119 | ------ |
| 120 | You can use the 'htpasswd' facility that comes with Apache to make these |
| 121 | files, but only with the -d option (or -B if your system supports it). |
| 122 | |
| 123 | Preferably use the system specific utility that manages password hash |
| 124 | creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or |
| 125 | pwhash in NetBSD) and paste it in the right location. |
| 126 | |
| 127 | Then provide your password via the pserver method, for example: |
| 128 | |
| 129 | ------ |
| 130 | cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name> |
| 131 | ------ |
| 132 | |
| 133 | No special setup is needed for SSH access, other than having Git tools |
| 134 | in the PATH. If you have clients that do not accept the CVS_SERVER |
| 135 | environment variable, you can rename 'git-cvsserver' to `cvs`. |
| 136 | |
| 137 | Note: Newer CVS versions (>= 1.12.11) also support specifying |
| 138 | CVS_SERVER directly in CVSROOT like |
| 139 | |
| 140 | ------ |
| 141 | cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> |
| 142 | ------ |
| 143 | |
| 144 | This has the advantage that it will be saved in your 'CVS/Root' files and |
| 145 | you don't need to worry about always setting the correct environment |
| 146 | variable. SSH users restricted to 'git-shell' don't need to override the default |
| 147 | with CVS_SERVER (and shouldn't) as 'git-shell' understands `cvs` to mean |
| 148 | 'git-cvsserver' and pretends that the other end runs the real 'cvs' better. |
| 149 | -- |
| 150 | 2. For each repo that you want accessible from CVS you need to edit config in |
| 151 | the repo and add the following section. |
| 152 | + |
| 153 | -- |
| 154 | ------ |
| 155 | [gitcvs] |
| 156 | enabled=1 |
| 157 | # optional for debugging |
| 158 | logFile=/path/to/logfile |
| 159 | |
| 160 | ------ |
| 161 | Note: you need to ensure each user that is going to invoke 'git-cvsserver' has |
| 162 | write access to the log file and to the database (see |
| 163 | <<dbbackend,Database Backend>>. If you want to offer write access over |
| 164 | SSH, the users of course also need write access to the Git repository itself. |
| 165 | |
| 166 | You also need to ensure that each repository is "bare" (without a Git index |
| 167 | file) for `cvs commit` to work. See linkgit:gitcvs-migration[7]. |
| 168 | |
| 169 | [[configaccessmethod]] |
| 170 | All configuration variables can also be overridden for a specific method of |
| 171 | access. Valid method names are "ext" (for SSH access) and "pserver". The |
| 172 | following example configuration would disable pserver access while still |
| 173 | allowing access over SSH. |
| 174 | |
| 175 | ------ |
| 176 | [gitcvs] |
| 177 | enabled=0 |
| 178 | |
| 179 | [gitcvs "ext"] |
| 180 | enabled=1 |
| 181 | ------ |
| 182 | -- |
| 183 | 3. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command, |
| 184 | automatically saving it in your 'CVS/Root' files, then you need to set them |
| 185 | explicitly in your environment. CVSROOT should be set as per normal, but the |
| 186 | directory should point at the appropriate Git repo. As above, for SSH clients |
| 187 | _not_ restricted to 'git-shell', CVS_SERVER should be set to 'git-cvsserver'. |
| 188 | + |
| 189 | -- |
| 190 | ------ |
| 191 | export CVSROOT=:ext:user@server:/var/git/project.git |
| 192 | export CVS_SERVER="git cvsserver" |
| 193 | ------ |
| 194 | -- |
| 195 | 4. For SSH clients that will make commits, make sure their server-side |
| 196 | .ssh/environment files (or .bashrc, etc., according to their specific shell) |
| 197 | export appropriate values for GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, |
| 198 | GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL. For SSH clients whose login |
| 199 | shell is bash, .bashrc may be a reasonable alternative. |
| 200 | |
| 201 | 5. Clients should now be able to check out the project. Use the CVS 'module' |
| 202 | name to indicate what Git 'head' you want to check out. This also sets the |
| 203 | name of your newly checked-out directory, unless you tell it otherwise with |
| 204 | `-d <dir-name>`. For example, this checks out 'master' branch to the |
| 205 | `project-master` directory: |
| 206 | + |
| 207 | ------ |
| 208 | cvs co -d project-master master |
| 209 | ------ |
| 210 | |
| 211 | [[dbbackend]] |
| 212 | DATABASE BACKEND |
| 213 | ---------------- |
| 214 | |
| 215 | 'git-cvsserver' uses one database per Git head (i.e. CVS module) to |
| 216 | store information about the repository to maintain consistent |
| 217 | CVS revision numbers. The database needs to be |
| 218 | updated (i.e. written to) after every commit. |
| 219 | |
| 220 | If the commit is done directly by using `git` (as opposed to |
| 221 | using 'git-cvsserver') the update will need to happen on the |
| 222 | next repository access by 'git-cvsserver', independent of |
| 223 | access method and requested operation. |
| 224 | |
| 225 | That means that even if you offer only read access (e.g. by using |
| 226 | the pserver method), 'git-cvsserver' should have write access to |
| 227 | the database to work reliably (otherwise you need to make sure |
| 228 | that the database is up to date any time 'git-cvsserver' is executed). |
| 229 | |
| 230 | By default it uses SQLite databases in the Git directory, named |
| 231 | `gitcvs.<module-name>.sqlite`. Note that the SQLite backend creates |
| 232 | temporary files in the same directory as the database file on |
| 233 | write so it might not be enough to grant the users using |
| 234 | 'git-cvsserver' write access to the database file without granting |
| 235 | them write access to the directory, too. |
| 236 | |
| 237 | The database cannot be reliably regenerated in a |
| 238 | consistent form after the branch it is tracking has changed. |
| 239 | Example: For merged branches, 'git-cvsserver' only tracks |
| 240 | one branch of development, and after a 'git merge' an |
| 241 | incrementally updated database may track a different branch |
| 242 | than a database regenerated from scratch, causing inconsistent |
| 243 | CVS revision numbers. `git-cvsserver` has no way of knowing which |
| 244 | branch it would have picked if it had been run incrementally |
| 245 | pre-merge. So if you have to fully or partially (from old |
| 246 | backup) regenerate the database, you should be suspicious |
| 247 | of pre-existing CVS sandboxes. |
| 248 | |
| 249 | You can configure the database backend with the following |
| 250 | configuration variables: |
| 251 | |
| 252 | Configuring database backend |
| 253 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 254 | |
| 255 | 'git-cvsserver' uses the Perl DBI module. Please also read |
| 256 | its documentation if changing these variables, especially |
| 257 | about `DBI->connect()`. |
| 258 | |
| 259 | gitcvs.dbName:: |
| 260 | Database name. The exact meaning depends on the |
| 261 | selected database driver, for SQLite this is a filename. |
| 262 | Supports variable substitution (see below). May |
| 263 | not contain semicolons (`;`). |
| 264 | Default: '%Ggitcvs.%m.sqlite' |
| 265 | |
| 266 | gitcvs.dbDriver:: |
| 267 | Used DBI driver. You can specify any available driver |
| 268 | for this here, but it might not work. cvsserver is tested |
| 269 | with 'DBD::SQLite', reported to work with |
| 270 | 'DBD::Pg', and reported *not* to work with 'DBD::mysql'. |
| 271 | Please regard this as an experimental feature. May not |
| 272 | contain colons (`:`). |
| 273 | Default: 'SQLite' |
| 274 | |
| 275 | gitcvs.dbuser:: |
| 276 | Database user. Only useful if setting `dbDriver`, since |
| 277 | SQLite has no concept of database users. Supports variable |
| 278 | substitution (see below). |
| 279 | |
| 280 | gitcvs.dbPass:: |
| 281 | Database password. Only useful if setting `dbDriver`, since |
| 282 | SQLite has no concept of database passwords. |
| 283 | |
| 284 | gitcvs.dbTableNamePrefix:: |
| 285 | Database table name prefix. Supports variable substitution |
| 286 | (see below). Any non-alphabetic characters will be replaced |
| 287 | with underscores. |
| 288 | |
| 289 | All variables can also be set per access method, see <<configaccessmethod,above>>. |
| 290 | |
| 291 | Variable substitution |
| 292 | ^^^^^^^^^^^^^^^^^^^^^ |
| 293 | In `dbDriver` and `dbUser` you can use the following variables: |
| 294 | |
| 295 | %G:: |
| 296 | Git directory name |
| 297 | %g:: |
| 298 | Git directory name, where all characters except for |
| 299 | alphanumeric ones, `.`, and `-` are replaced with |
| 300 | `_` (this should make it easier to use the directory |
| 301 | name in a filename if wanted) |
| 302 | %m:: |
| 303 | CVS module/Git head name |
| 304 | %a:: |
| 305 | access method (one of "ext" or "pserver") |
| 306 | %u:: |
| 307 | Name of the user running 'git-cvsserver'. |
| 308 | If no name can be determined, the |
| 309 | numeric uid is used. |
| 310 | |
| 311 | ENVIRONMENT |
| 312 | ----------- |
| 313 | |
| 314 | These variables obviate the need for command-line options in some |
| 315 | circumstances, allowing easier restricted usage through git-shell. |
| 316 | |
| 317 | GIT_CVSSERVER_BASE_PATH:: |
| 318 | This variable replaces the argument to --base-path. |
| 319 | |
| 320 | GIT_CVSSERVER_ROOT:: |
| 321 | This variable specifies a single directory, replacing the |
| 322 | `<directory>...` argument list. The repository still requires the |
| 323 | `gitcvs.enabled` config option, unless `--export-all` is specified. |
| 324 | |
| 325 | When these environment variables are set, the corresponding |
| 326 | command-line arguments may not be used. |
| 327 | |
| 328 | ECLIPSE CVS CLIENT NOTES |
| 329 | ------------------------ |
| 330 | |
| 331 | To get a checkout with the Eclipse CVS client: |
| 332 | |
| 333 | 1. Select "Create a new project -> From CVS checkout" |
| 334 | 2. Create a new location. See the notes below for details on how to choose the |
| 335 | right protocol. |
| 336 | 3. Browse the 'modules' available. It will give you a list of the heads in |
| 337 | the repository. You will not be able to browse the tree from there. Only |
| 338 | the heads. |
| 339 | 4. Pick `HEAD` when it asks what branch/tag to check out. Untick the |
| 340 | "launch commit wizard" to avoid committing the .project file. |
| 341 | |
| 342 | Protocol notes: If you are using anonymous access via pserver, just select that. |
| 343 | Those using SSH access should choose the 'ext' protocol, and configure 'ext' |
| 344 | access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to |
| 345 | "`git cvsserver`". Note that password support is not good when using 'ext', |
| 346 | you will definitely want to have SSH keys setup. |
| 347 | |
| 348 | Alternatively, you can just use the non-standard extssh protocol that Eclipse |
| 349 | offer. In that case CVS_SERVER is ignored, and you will have to replace |
| 350 | the cvs utility on the server with 'git-cvsserver' or manipulate your `.bashrc` |
| 351 | so that calling 'cvs' effectively calls 'git-cvsserver'. |
| 352 | |
| 353 | CLIENTS KNOWN TO WORK |
| 354 | --------------------- |
| 355 | |
| 356 | - CVS 1.12.9 on Debian |
| 357 | - CVS 1.11.17 on MacOSX (from Fink package) |
| 358 | - Eclipse 3.0, 3.1.2 on MacOSX (see Eclipse CVS Client Notes) |
| 359 | - TortoiseCVS |
| 360 | |
| 361 | OPERATIONS SUPPORTED |
| 362 | -------------------- |
| 363 | |
| 364 | All the operations required for normal use are supported, including |
| 365 | checkout, diff, status, update, log, add, remove, commit. |
| 366 | |
| 367 | Most CVS command arguments that read CVS tags or revision numbers |
| 368 | (typically -r) work, and also support any git refspec |
| 369 | (tag, branch, commit ID, etc). |
| 370 | However, CVS revision numbers for non-default branches are not well |
| 371 | emulated, and cvs log does not show tags or branches at |
| 372 | all. (Non-main-branch CVS revision numbers superficially resemble CVS |
| 373 | revision numbers, but they actually encode a git commit ID directly, |
| 374 | rather than represent the number of revisions since the branch point.) |
| 375 | |
| 376 | Note that there are two ways to checkout a particular branch. |
| 377 | As described elsewhere on this page, the "module" parameter |
| 378 | of cvs checkout is interpreted as a branch name, and it becomes |
| 379 | the main branch. It remains the main branch for a given sandbox |
| 380 | even if you temporarily make another branch sticky with |
| 381 | cvs update -r. Alternatively, the -r argument can indicate |
| 382 | some other branch to actually checkout, even though the module |
| 383 | is still the "main" branch. Tradeoffs (as currently |
| 384 | implemented): Each new "module" creates a new database on disk with |
| 385 | a history for the given module, and after the database is created, |
| 386 | operations against that main branch are fast. Or alternatively, |
| 387 | -r doesn't take any extra disk space, but may be significantly slower for |
| 388 | many operations, like cvs update. |
| 389 | |
| 390 | If you want to refer to a git refspec that has characters that are |
| 391 | not allowed by CVS, you have two options. First, it may just work |
| 392 | to supply the git refspec directly to the appropriate CVS -r argument; |
| 393 | some CVS clients don't seem to do much sanity checking of the argument. |
| 394 | Second, if that fails, you can use a special character escape mechanism |
| 395 | that only uses characters that are valid in CVS tags. A sequence |
| 396 | of 4 or 5 characters of the form (underscore (`"_"`), dash (`"-"`), |
| 397 | one or two characters, and dash (`"-"`)) can encode various characters based |
| 398 | on the one or two letters: `"s"` for slash (`"/"`), `"p"` for |
| 399 | period (`"."`), `"u"` for underscore (`"_"`), or two hexadecimal digits |
| 400 | for any byte value at all (typically an ASCII number, or perhaps a part |
| 401 | of a UTF-8 encoded character). |
| 402 | |
| 403 | Legacy monitoring operations are not supported (edit, watch and related). |
| 404 | Exports and tagging (tags and branches) are not supported at this stage. |
| 405 | |
| 406 | CRLF Line Ending Conversions |
| 407 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 408 | |
| 409 | By default the server leaves the `-k` mode blank for all files, |
| 410 | which causes the CVS client to treat them as a text files, subject |
| 411 | to end-of-line conversion on some platforms. |
| 412 | |
| 413 | You can make the server use the end-of-line conversion attributes to |
| 414 | set the `-k` modes for files by setting the `gitcvs.usecrlfattr` |
| 415 | config variable. See linkgit:gitattributes[5] for more information |
| 416 | about end-of-line conversion. |
| 417 | |
| 418 | Alternatively, if `gitcvs.usecrlfattr` config is not enabled |
| 419 | or the attributes do not allow automatic detection for a filename, then |
| 420 | the server uses the `gitcvs.allBinary` config for the default setting. |
| 421 | If `gitcvs.allBinary` is set, then file not otherwise |
| 422 | specified will default to '-kb' mode. Otherwise the `-k` mode |
| 423 | is left blank. But if `gitcvs.allBinary` is set to "guess", then |
| 424 | the correct `-k` mode will be guessed based on the contents of |
| 425 | the file. |
| 426 | |
| 427 | For best consistency with 'cvs', it is probably best to override the |
| 428 | defaults by setting `gitcvs.usecrlfattr` to true, |
| 429 | and `gitcvs.allBinary` to "guess". |
| 430 | |
| 431 | DEPENDENCIES |
| 432 | ------------ |
| 433 | 'git-cvsserver' depends on DBD::SQLite. |
| 434 | |
| 435 | GIT |
| 436 | --- |
| 437 | Part of the linkgit:git[1] suite |