'\" t
.\" Title: git-cvsserver
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 06/01/2011
.\" Manual: Git Manual
.\" Source: Git 1.7.5.4
.\" Language: English
.\"
.TH "GIT\-CVSSERVER" "1" "06/01/2011" "Git 1\&.7\&.5\&.4" "Git Manual"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-cvsserver \- A CVS server emulator for git
.SH "SYNOPSIS"
.sp
SSH:
.sp
.nf
export CVS_SERVER="git cvsserver"
\fIcvs\fR \-d :ext:user@server/path/repo\&.git co <HEAD_name>
.fi
.sp
.sp
pserver (/etc/inetd\&.conf):
.sp
.nf
cvspserver stream tcp nowait nobody /usr/bin/git\-cvsserver git\-cvsserver pserver
.fi
.sp
.sp
Usage:
.sp
.nf
\fIgit\-cvsserver\fR [options] [pserver|server] [<directory> \&...]
.fi
.sp
.SH "OPTIONS"
.sp
All these options obviously only make sense if enforced by the server side\&. They have been implemented to resemble the \fBgit-daemon\fR(1) options as closely as possible\&.
.PP
\-\-base\-path <path>
.RS 4
Prepend
\fIpath\fR
to requested CVSROOT
.RE
.PP
\-\-strict\-paths
.RS 4
Don\(cqt allow recursing into subdirectories
.RE
.PP
\-\-export\-all
.RS 4
Don\(cqt check for
gitcvs\&.enabled
in config\&. You also have to specify a list of allowed directories (see below) if you want to use this option\&.
.RE
.PP
\-V, \-\-version
.RS 4
Print version information and exit
.RE
.PP
\-h, \-H, \-\-help
.RS 4
Print usage information and exit
.RE
.PP
<directory>
.RS 4
You can specify a list of allowed directories\&. If no directories are given, all are allowed\&. This is an additional restriction, gitcvs access still needs to be enabled by the
gitcvs\&.enabled
config option unless
\fI\-\-export\-all\fR
was given, too\&.
.RE
.SH "DESCRIPTION"
.sp
This application is a CVS emulation layer for git\&.
.sp
It is highly functional\&. However, not all methods are implemented, and for those methods that are implemented, not all switches are implemented\&.
.sp
Testing has been done using both the CLI CVS client, and the Eclipse CVS plugin\&. Most functionality works fine with both of these clients\&.
.SH "LIMITATIONS"
.sp
CVS clients cannot tag, branch or perform GIT merges\&.
.sp
\fIgit\-cvsserver\fR maps GIT branches to CVS modules\&. This is very different from what most CVS users would expect since in CVS modules usually represent one or more directories\&.
.SH "INSTALLATION"
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
If you are going to offer CVS access via pserver, add a line in /etc/inetd\&.conf like
.sp
.if n \{\
.RS 4
.\}
.nf
cvspserver stream tcp nowait nobody git\-cvsserver pserver
.fi
.if n \{\
.RE
.\}
.sp
Note: Some inetd servers let you specify the name of the executable independently of the value of argv[0] (i\&.e\&. the name the program assumes it was executed with)\&. In this case the correct line in /etc/inetd\&.conf looks like
.sp
.if n \{\
.RS 4
.\}
.nf
cvspserver stream tcp nowait nobody /usr/bin/git\-cvsserver git\-cvsserver pserver
.fi
.if n \{\
.RE
.\}
.sp
Only anonymous access is provided by pserve by default\&. To commit you will have to create pserver accounts, simply add a gitcvs\&.authdb setting in the config file of the repositories you want the cvsserver to allow writes to, for example:
.sp
.if n \{\
.RS 4
.\}
.nf
[gitcvs]
authdb = /etc/cvsserver/passwd
.fi
.if n \{\
.RE
.\}
.sp
The format of these files is username followed by the crypted password, for example:
.sp
.if n \{\
.RS 4
.\}
.nf
myuser:$1Oyx5r9mdGZ2
myuser:$1$BA)@$vbnMJMDym7tA32AamXrm\&./
.fi
.if n \{\
.RE
.\}
.sp
You can use the
\fIhtpasswd\fR
facility that comes with Apache to make these files, but Apache\(cqs MD5 crypt method differs from the one used by most C library\(cqs crypt() function, so don\(cqt use the \-m option\&.
.sp
Alternatively you can produce the password with perl\(cqs crypt() operator:
.sp
.if n \{\
.RS 4
.\}
.nf
perl \-e \(aqmy ($user, $pass) = @ARGV; printf "%s:%s\en", $user, crypt($user, $pass)\(aq $USER password
.fi
.if n \{\
.RE
.\}
.sp
Then provide your password via the pserver method, for example:
.sp
.if n \{\
.RS 4
.\}
.nf
cvs \-d:pserver:someuser:somepassword <at> server/path/repo\&.git co <HEAD_name>
.fi
.if n \{\
.RE
.\}
.sp
No special setup is needed for SSH access, other than having GIT tools in the PATH\&. If you have clients that do not accept the CVS_SERVER environment variable, you can rename
\fIgit\-cvsserver\fR
to
cvs\&.
.sp
Note: Newer CVS versions (>= 1\&.12\&.11) also support specifying CVS_SERVER directly in CVSROOT like
.sp
.if n \{\
.RS 4
.\}
.nf
cvs \-d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo\&.git" co <HEAD_name>
.fi
.if n \{\
.RE
.\}
.sp
This has the advantage that it will be saved in your
\fICVS/Root\fR
files and you don\(cqt need to worry about always setting the correct environment variable\&. SSH users restricted to
\fIgit\-shell\fR
don\(cqt need to override the default with CVS_SERVER (and shouldn\(cqt) as
\fIgit\-shell\fR
understands
cvs
to mean
\fIgit\-cvsserver\fR
and pretends that the other end runs the real
\fIcvs\fR
better\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
For each repo that you want accessible from CVS you need to edit config in the repo and add the following section\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[gitcvs]
enabled=1
# optional for debugging
logfile=/path/to/logfile
.fi
.if n \{\
.RE
.\}
.sp
Note: you need to ensure each user that is going to invoke
\fIgit\-cvsserver\fR
has write access to the log file and to the database (see
Database Backend\&. If you want to offer write access over SSH, the users of course also need write access to the git repository itself\&.
.sp
You also need to ensure that each repository is "bare" (without a git index file) for
cvs commit
to work\&. See
\fBgitcvs-migration\fR(7)\&.
.sp
All configuration variables can also be overridden for a specific method of access\&. Valid method names are "ext" (for SSH access) and "pserver"\&. The following example configuration would disable pserver access while still allowing access over SSH\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[gitcvs]
enabled=0
[gitcvs "ext"]
enabled=1
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
If you didn\(cqt specify the CVSROOT/CVS_SERVER directly in the checkout command, automatically saving it in your
\fICVS/Root\fR
files, then you need to set them explicitly in your environment\&. CVSROOT should be set as per normal, but the directory should point at the appropriate git repo\&. As above, for SSH clients
\fInot\fR
restricted to
\fIgit\-shell\fR, CVS_SERVER should be set to
\fIgit\-cvsserver\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
export CVSROOT=:ext:user@server:/var/git/project\&.git
export CVS_SERVER="git cvsserver"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
For SSH clients that will make commits, make sure their server\-side \&.ssh/environment files (or \&.bashrc, etc\&., according to their specific shell) export appropriate values for GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL\&. For SSH clients whose login shell is bash, \&.bashrc may be a reasonable alternative\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
Clients should now be able to check out the project\&. Use the CVS
\fImodule\fR
name to indicate what GIT
\fIhead\fR
you want to check out\&. This also sets the name of your newly checked\-out directory, unless you tell it otherwise with
\-d <dir_name>\&. For example, this checks out
\fImaster\fR
branch to the
project\-master
directory:
.sp
.if n \{\
.RS 4
.\}
.nf
cvs co \-d project\-master master
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SH "DATABASE BACKEND"
.sp
\fIgit\-cvsserver\fR uses one database per git head (i\&.e\&. CVS module) to store information about the repository to maintain consistent CVS revision numbers\&. The database needs to be updated (i\&.e\&. written to) after every commit\&.
.sp
If the commit is done directly by using git (as opposed to using \fIgit\-cvsserver\fR) the update will need to happen on the next repository access by \fIgit\-cvsserver\fR, independent of access method and requested operation\&.
.sp
That means that even if you offer only read access (e\&.g\&. by using the pserver method), \fIgit\-cvsserver\fR should have write access to the database to work reliably (otherwise you need to make sure that the database is up\-to\-date any time \fIgit\-cvsserver\fR is executed)\&.
.sp
By default it uses SQLite databases in the git directory, named gitcvs\&.<module_name>\&.sqlite\&. Note that the SQLite backend creates temporary files in the same directory as the database file on write so it might not be enough to grant the users using \fIgit\-cvsserver\fR write access to the database file without granting them write access to the directory, too\&.
.sp
The database can not be reliably regenerated in a consistent form after the branch it is tracking has changed\&. Example: For merged branches, \fIgit\-cvsserver\fR only tracks one branch of development, and after a \fIgit merge\fR an incrementally updated database may track a different branch than a database regenerated from scratch, causing inconsistent CVS revision numbers\&. git\-cvsserver has no way of knowing which branch it would have picked if it had been run incrementally pre\-merge\&. So if you have to fully or partially (from old backup) regenerate the database, you should be suspicious of pre\-existing CVS sandboxes\&.
.sp
You can configure the database backend with the following configuration variables:
.SS "Configuring database backend"
.sp
\fIgit\-cvsserver\fR uses the Perl DBI module\&. Please also read its documentation if changing these variables, especially about DBI\->connect()\&.
.PP
gitcvs\&.dbname
.RS 4
Database name\&. The exact meaning depends on the selected database driver, for SQLite this is a filename\&. Supports variable substitution (see below)\&. May not contain semicolons (;)\&. Default:
\fI%Ggitcvs\&.%m\&.sqlite\fR
.RE
.PP
gitcvs\&.dbdriver
.RS 4
Used DBI driver\&. You can specify any available driver for this here, but it might not work\&. cvsserver is tested with
\fIDBD::SQLite\fR, reported to work with
\fIDBD::Pg\fR, and reported
\fBnot\fR
to work with
\fIDBD::mysql\fR\&. Please regard this as an experimental feature\&. May not contain colons (:)\&. Default:
\fISQLite\fR
.RE
.PP
gitcvs\&.dbuser
.RS 4
Database user\&. Only useful if setting
dbdriver, since SQLite has no concept of database users\&. Supports variable substitution (see below)\&.
.RE
.PP
gitcvs\&.dbpass
.RS 4
Database password\&. Only useful if setting
dbdriver, since SQLite has no concept of database passwords\&.
.RE
.PP
gitcvs\&.dbTableNamePrefix
.RS 4
Database table name prefix\&. Supports variable substitution (see below)\&. Any non\-alphabetic characters will be replaced with underscores\&.
.RE
.sp
All variables can also be set per access method, see above\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBVariable substitution\fR
.RS 4
.sp
In dbdriver and dbuser you can use the following variables:
.PP
%G
.RS 4
git directory name
.RE
.PP
%g
.RS 4
git directory name, where all characters except for alpha\-numeric ones,
\&., and
\-
are replaced with
_
(this should make it easier to use the directory name in a filename if wanted)
.RE
.PP
%m
.RS 4
CVS module/git head name
.RE
.PP
%a
.RS 4
access method (one of "ext" or "pserver")
.RE
.PP
%u
.RS 4
Name of the user running
\fIgit\-cvsserver\fR\&. If no name can be determined, the numeric uid is used\&.
.RE
.RE
.SH "ENVIRONMENT"
.sp
These variables obviate the need for command\-line options in some circumstances, allowing easier restricted usage through git\-shell\&.
.sp
GIT_CVSSERVER_BASE_PATH takes the place of the argument to \-\-base\-path\&.
.sp
GIT_CVSSERVER_ROOT specifies a single\-directory whitelist\&. The repository must still be configured to allow access through git\-cvsserver, as described above\&.
.sp
When these environment variables are set, the corresponding command\-line arguments may not be used\&.
.SH "ECLIPSE CVS CLIENT NOTES"
.sp
To get a checkout with the Eclipse CVS client:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Select "Create a new project \(-> From CVS checkout"
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Create a new location\&. See the notes below for details on how to choose the right protocol\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
Browse the
\fImodules\fR
available\&. It will give you a list of the heads in the repository\&. You will not be able to browse the tree from there\&. Only the heads\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
Pick
\fIHEAD\fR
when it asks what branch/tag to check out\&. Untick the "launch commit wizard" to avoid committing the \&.project file\&.
.RE
.sp
Protocol notes: If you are using anonymous access via pserver, just select that\&. Those using SSH access should choose the \fIext\fR protocol, and configure \fIext\fR access on the Preferences\(->Team\(->CVS\(->ExtConnection pane\&. Set CVS_SERVER to "git cvsserver"\&. Note that password support is not good when using \fIext\fR, you will definitely want to have SSH keys setup\&.
.sp
Alternatively, you can just use the non\-standard extssh protocol that Eclipse offer\&. In that case CVS_SERVER is ignored, and you will have to replace the cvs utility on the server with \fIgit\-cvsserver\fR or manipulate your \&.bashrc so that calling \fIcvs\fR effectively calls \fIgit\-cvsserver\fR\&.
.SH "CLIENTS KNOWN TO WORK"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CVS 1\&.12\&.9 on Debian
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CVS 1\&.11\&.17 on MacOSX (from Fink package)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Eclipse 3\&.0, 3\&.1\&.2 on MacOSX (see Eclipse CVS Client Notes)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
TortoiseCVS
.RE
.SH "OPERATIONS SUPPORTED"
.sp
All the operations required for normal use are supported, including checkout, diff, status, update, log, add, remove, commit\&. Legacy monitoring operations are not supported (edit, watch and related)\&. Exports and tagging (tags and branches) are not supported at this stage\&.
.SS "CRLF Line Ending Conversions"
.sp
By default the server leaves the \fI\-k\fR mode blank for all files, which causes the CVS client to treat them as a text files, subject to end\-of\-line conversion on some platforms\&.
.sp
You can make the server use the end\-of\-line conversion attributes to set the \fI\-k\fR modes for files by setting the gitcvs\&.usecrlfattr config variable\&. See \fBgitattributes\fR(5) for more information about end\-of\-line conversion\&.
.sp
Alternatively, if gitcvs\&.usecrlfattr config is not enabled or the attributes do not allow automatic detection for a filename, then the server uses the gitcvs\&.allbinary config for the default setting\&. If gitcvs\&.allbinary is set, then file not otherwise specified will default to \fI\-kb\fR mode\&. Otherwise the \fI\-k\fR mode is left blank\&. But if gitcvs\&.allbinary is set to "guess", then the correct \fI\-k\fR mode will be guessed based on the contents of the file\&.
.sp
For best consistency with \fIcvs\fR, it is probably best to override the defaults by setting gitcvs\&.usecrlfattr to true, and gitcvs\&.allbinary to "guess"\&.
.SH "DEPENDENCIES"
.sp
\fIgit\-cvsserver\fR depends on DBD::SQLite\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite