summaryrefslogtreecommitdiff
path: root/Documentation/git-cvsserver.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-cvsserver.txt')
-rw-r--r--Documentation/git-cvsserver.txt173
1 files changed, 123 insertions, 50 deletions
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index 785779e221..472f5cbd07 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -3,7 +3,7 @@ git-cvsserver(1)
NAME
----
-git-cvsserver - A CVS server emulator for git
+git-cvsserver - A CVS server emulator for Git
SYNOPSIS
--------
@@ -22,7 +22,7 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
Usage:
[verse]
-'git cvsserver' [options] [pserver|server] [<directory> ...]
+'git-cvsserver' [options] [pserver|server] [<directory> ...]
OPTIONS
-------
@@ -60,7 +60,7 @@ unless '--export-all' was given, too.
DESCRIPTION
-----------
-This application is a CVS emulation layer for git.
+This application is a CVS emulation layer for Git.
It is highly functional. However, not all methods are implemented,
and for those methods that are implemented,
@@ -72,19 +72,16 @@ plugin. Most functionality works fine with both of these clients.
LIMITATIONS
-----------
-Currently cvsserver works over SSH connections for read/write clients, and
-over pserver for anonymous CVS access.
+CVS clients cannot tag, branch or perform Git merges.
-CVS clients cannot tag, branch or perform GIT merges.
-
-'git-cvsserver' maps GIT branches to CVS modules. This is very different
+'git-cvsserver' 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.
INSTALLATION
------------
-1. If you are going to offer anonymous CVS access via pserver, add a line in
+1. If you are going to offer CVS access via pserver, add a line in
/etc/inetd.conf like
+
--
@@ -101,7 +98,39 @@ looks like
cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
------
-No special setup is needed for SSH access, other than having GIT tools
+
+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:
+
+------
+
+ [gitcvs]
+ authdb = /etc/cvsserver/passwd
+
+------
+The format of these files is username followed by the crypted password,
+for example:
+
+------
+ myuser:$1Oyx5r9mdGZ2
+ myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./
+------
+You can use the 'htpasswd' facility that comes with Apache to make these
+files, but Apache's MD5 crypt method differs from the one used by most C
+library's crypt() function, so don't use the -m option.
+
+Alternatively you can produce the password with perl's crypt() operator:
+-----
+ perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password
+-----
+
+Then provide your password via the pserver method, for example:
+------
+ cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name>
+------
+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 'git-cvsserver' to `cvs`.
@@ -131,9 +160,9 @@ with CVS_SERVER (and shouldn't) as 'git-shell' understands `cvs` to mean
Note: you need to ensure each user that is going to invoke 'git-cvsserver' has
write access to the log file and to the database (see
<<dbbackend,Database Backend>>. If you want to offer write access over
-SSH, the users of course also need write access to the git repository itself.
+SSH, the users of course also need write access to the Git repository itself.
-You also need to ensure that each repository is "bare" (without a git index
+You also need to ensure that each repository is "bare" (without a Git index
file) for `cvs commit` to work. See linkgit:gitcvs-migration[7].
[[configaccessmethod]]
@@ -152,7 +181,7 @@ allowing access over SSH.
3. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command,
automatically saving it in your 'CVS/Root' 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
+ directory should point at the appropriate Git repo. As above, for SSH clients
_not_ restricted to 'git-shell', CVS_SERVER should be set to 'git-cvsserver'.
+
--
@@ -168,7 +197,7 @@ allowing access over SSH.
shell is bash, .bashrc may be a reasonable alternative.
5. Clients should now be able to check out the project. Use the CVS 'module'
- name to indicate what GIT 'head' you want to check out. This also sets the
+ name to indicate what Git 'head' 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 'master' branch to the
`project-master` directory:
@@ -181,11 +210,10 @@ allowing access over SSH.
Database Backend
----------------
-'git-cvsserver' uses one database per git head (i.e. CVS module) to
-store information about the repository for faster access. The
-database doesn't contain any persistent data and can be completely
-regenerated from the git repository at any time. The database
-needs to be updated (i.e. written to) after every commit.
+'git-cvsserver' 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.
If the commit is done directly by using `git` (as opposed to
using 'git-cvsserver') the update will need to happen on the
@@ -197,13 +225,25 @@ the pserver method), 'git-cvsserver' 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 'git-cvsserver' is executed).
-By default it uses SQLite databases in the git directory, named
+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
'git-cvsserver' write access to the database file without granting
them write access to the directory, too.
+The database can not be reliably regenerated in a
+consistent form after the branch it is tracking has changed.
+Example: For merged branches, 'git-cvsserver' only tracks
+one branch of development, and after a 'git merge' 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.
+
You can configure the database backend with the following
configuration variables:
@@ -251,14 +291,14 @@ Variable substitution
In `dbdriver` and `dbuser` you can use the following variables:
%G::
- git directory name
+ Git directory name
%g::
- git directory name, where all characters except for
+ 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)
%m::
- CVS module/git head name
+ CVS module/Git head name
%a::
access method (one of "ext" or "pserver")
%u::
@@ -266,6 +306,21 @@ In `dbdriver` and `dbuser` you can use the following variables:
If no name can be determined, the
numeric uid is used.
+ENVIRONMENT
+-----------
+
+These variables obviate the need for command-line options in some
+circumstances, allowing easier restricted usage through git-shell.
+
+GIT_CVSSERVER_BASE_PATH takes the place of the argument to --base-path.
+
+GIT_CVSSERVER_ROOT specifies a single-directory whitelist. The
+repository must still be configured to allow access through
+git-cvsserver, as described above.
+
+When these environment variables are set, the corresponding
+command-line arguments may not be used.
+
Eclipse CVS Client Notes
------------------------
@@ -283,7 +338,7 @@ To get a checkout with the Eclipse CVS client:
Protocol notes: If you are using anonymous access via pserver, just select that.
Those using SSH access should choose the 'ext' protocol, and configure 'ext'
access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to
-"'git cvsserver'". Note that password support is not good when using 'ext',
+"`git cvsserver`". Note that password support is not good when using 'ext',
you will definitely want to have SSH keys setup.
Alternatively, you can just use the non-standard extssh protocol that Eclipse
@@ -304,6 +359,43 @@ Operations supported
All the operations required for normal use are supported, including
checkout, diff, status, update, log, add, remove, commit.
+
+Most CVS command arguments that read CVS tags or revision numbers
+(typically -r) work, and also support any git refspec
+(tag, branch, commit ID, etc).
+However, CVS revision numbers for non-default branches are not well
+emulated, and cvs log does not show tags or branches at
+all. (Non-main-branch CVS revision numbers superficially resemble CVS
+revision numbers, but they actually encode a git commit ID directly,
+rather than represent the number of revisions since the branch point.)
+
+Note that there are two ways to checkout a particular branch.
+As described elsewhere on this page, the "module" parameter
+of cvs checkout is interpreted as a branch name, and it becomes
+the main branch. It remains the main branch for a given sandbox
+even if you temporarily make another branch sticky with
+cvs update -r. Alternatively, the -r argument can indicate
+some other branch to actually checkout, even though the module
+is still the "main" branch. Tradeoffs (as currently
+implemented): Each new "module" creates a new database on disk with
+a history for the given module, and after the database is created,
+operations against that main branch are fast. Or alternatively,
+-r doesn't take any extra disk space, but may be significantly slower for
+many operations, like cvs update.
+
+If you want to refer to a git refspec that has characters that are
+not allowed by CVS, you have two options. First, it may just work
+to supply the git refspec directly to the appropriate CVS -r argument;
+some CVS clients don't seem to do much sanity checking of the argument.
+Second, if that fails, you can use a special character escape mechanism
+that only uses characters that are valid in CVS tags. A sequence
+of 4 or 5 characters of the form (underscore (`"_"`), dash (`"-"`),
+one or two characters, and dash (`"-"`)) can encode various characters based
+on the one or two letters: `"s"` for slash (`"/"`), `"p"` for
+period (`"."`), `"u"` for underscore (`"_"`), or two hexadecimal digits
+for any byte value at all (typically an ASCII number, or perhaps a part
+of a UTF-8 encoded character).
+
Legacy monitoring operations are not supported (edit, watch and related).
Exports and tagging (tags and branches) are not supported at this stage.
@@ -311,19 +403,16 @@ CRLF Line Ending Conversions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default the server leaves the '-k' mode blank for all files,
-which causes the cvs client to treat them as a text files, subject
-to crlf conversion on some platforms.
+which causes the CVS client to treat them as a text files, subject
+to end-of-line conversion on some platforms.
-You can make the server use `crlf` attributes to set the '-k' modes
-for files by setting the `gitcvs.usecrlfattr` config variable.
-In this case, if `crlf` is explicitly unset ('-crlf'), then the
-server will set '-kb' mode for binary files. If `crlf` is set,
-then the '-k' mode will explicitly be left blank. See
-also linkgit:gitattributes[5] for more information about the `crlf`
-attribute.
+You can make the server use the end-of-line conversion attributes to
+set the '-k' modes for files by setting the `gitcvs.usecrlfattr`
+config variable. See linkgit:gitattributes[5] for more information
+about end-of-line conversion.
Alternatively, if `gitcvs.usecrlfattr` config is not enabled
-or if the `crlf` attribute is unspecified for a filename, then
+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 '-kb' mode. Otherwise the '-k' mode
@@ -339,22 +428,6 @@ Dependencies
------------
'git-cvsserver' depends on DBD::SQLite.
-Copyright and Authors
----------------------
-
-This program is copyright The Open University UK - 2006.
-
-Authors:
-
-- Martyn Smith <martyn@catalyst.net.nz>
-- Martin Langhoff <martin@catalyst.net.nz>
-
-with ideas and patches from participants of the git-list <git@vger.kernel.org>.
-
-Documentation
---------------
-Documentation by Martyn Smith <martyn@catalyst.net.nz>, Martin Langhoff <martin@catalyst.net.nz>, and Matthias Urlichs <smurf@smurf.noris.de>.
-
GIT
---
Part of the linkgit:git[1] suite