Documentation/git-cvsserver.txt

   1 git-cvsserver(1)
   2 ================
   3
   4 NAME
   5 ----
   6 git-cvsserver - A CVS server emulator for git
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 export CVS_SERVER=git-cvsserver
  12 'cvs' -d :ext:user@server/path/repo.git co <HEAD_name>
  13
  14 DESCRIPTION
  15 -----------
  16
  17 This application is a CVS emulation layer for git.
  18
  19 It is highly functional. However, not all methods are implemented,
  20 and for those methods that are implemented,
  21 not all switches are implemented.
  22
  23 Testing has been done using both the CLI CVS client, and the Eclipse CVS
  24 plugin. Most functionality works fine with both of these clients.
  25
  26 LIMITATIONS
  27 -----------
  28
  29 Currently cvsserver works over SSH connections for read/write clients, and
  30 over pserver for anonymous CVS access.
  31
  32 CVS clients cannot tag, branch or perform GIT merges.
  33
  34 git-cvsserver maps GIT branches to CVS modules. This is very different
  35 from what most CVS users would expect since in CVS modules usually represent
  36 one or more directories.
  37
  38 INSTALLATION
  39 ------------
  40
  41 1. If you are going to offer anonymous CVS access via pserver, add a line in
  42    /etc/inetd.conf like
  43 +
  44 --
  45 ------
  46    cvspserver stream tcp nowait nobody git-cvsserver pserver
  47
  48 ------
  49 Note: Some inetd servers let you specify the name of the executable
  50 independently of the value of argv[0] (i.e. the name the program assumes
  51 it was executed with). In this case the correct line in /etc/inetd.conf
  52 looks like
  53
  54 ------
  55    cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
  56
  57 ------
  58 No special setup is needed for SSH access, other than having GIT tools
  59 in the PATH. If you have clients that do not accept the CVS_SERVER
  60 env variable, you can rename git-cvsserver to cvs.
  61 --
  62 2. For each repo that you want accessible from CVS you need to edit config in
  63    the repo and add the following section.
  64 +
  65 --
  66 ------
  67    [gitcvs]
  68         enabled=1
  69         # optional for debugging
  70         logfile=/path/to/logfile
  71
  72 ------
  73 Note: you need to ensure each user that is going to invoke git-cvsserver has
  74 write access to the log file and to the database (see
  75 <<dbbackend,Database Backend>>. If you want to offer write access over
  76 SSH, the users of course also need write access to the git repository itself.
  77
  78 [[configaccessmethod]]
  79 All configuration variables can also be overriden for a specific method of
  80 access. Valid method names are "ext" (for SSH access) and "pserver". The
  81 following example configuration would disable pserver access while still
  82 allowing access over SSH.
  83 ------
  84    [gitcvs]
  85         enabled=0
  86
  87    [gitcvs "ext"]
  88         enabled=1
  89 ------
  90 --
  91 3. On the client machine you need to set the following variables.
  92    CVSROOT should be set as per normal, but the directory should point at the
  93    appropriate git repo. For example:
  94 +
  95 --
  96 For SSH access, CVS_SERVER should be set to git-cvsserver
  97
  98 Example:
  99
 100 ------
 101      export CVSROOT=:ext:user@server:/var/git/project.git
 102      export CVS_SERVER=git-cvsserver
 103 ------
 104 --
 105 4. For SSH clients that will make commits, make sure their .bashrc file
 106    sets the GIT_AUTHOR and GIT_COMMITTER variables.
 107
 108 5. Clients should now be able to check out the project. Use the CVS 'module'
 109    name to indicate what GIT 'head' you want to check out. Example:
 110 +
 111 ------
 112      cvs co -d project-master master
 113 ------
 114
 115 [[dbbackend]]
 116 Database Backend
 117 ----------------
 118
 119 git-cvsserver uses one database per git head (i.e. CVS module) to
 120 store information about the repository for faster access. The
 121 database doesn't contain any persitent data and can be completly
 122 regenerated from the git repository at any time. The database
 123 needs to be updated (i.e. written to) after every commit.
 124
 125 If the commit is done directly by using git (as opposed to
 126 using git-cvsserver) the update will need to happen on the
 127 next repository access by git-cvsserver, independent of
 128 access method and requested operation.
 129
 130 That means that even if you offer only read access (e.g. by using
 131 the pserver method), git-cvsserver should have write access to
 132 the database to work reliably (otherwise you need to make sure
 133 that the database if up-to-date all the time git-cvsserver is run).
 134
 135 By default it uses SQLite databases in the git directory, named
 136 `gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates
 137 temporary files in the same directory as the database file on
 138 write so it might not be enough to grant the users using
 139 git-cvsserver write access to the database file without granting
 140 them write access to the directory, too.
 141
 142 You can configure the database backend with the following
 143 configuration variables:
 144
 145 Configuring database backend
 146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 147
 148 git-cvsserver uses the Perl DBI module. Please also read
 149 its documentation if changing these variables, especially
 150 about `DBI->connect()`.
 151
 152 gitcvs.dbname::
 153         Database name. The exact meaning depends on the
 154         used database driver, for SQLite this is a filename.
 155         Supports variable substitution (see below). May
 156         not contain semicolons (`;`).
 157         Default: '%Ggitcvs.%m.sqlite'
 158
 159 gitcvs.dbdriver::
 160         Used DBI driver. You can specify any available driver
 161         for this here, but it might not work. cvsserver is tested
 162         with 'DBD::SQLite', reported to work with
 163         'DBD::Pg', and reported *not* to work with 'DBD::mysql'.
 164         Please regard this as an experimental feature. May not
 165         contain double colons (`:`).
 166         Default: 'SQLite'
 167
 168 gitcvs.dbuser::
 169         Database user. Only useful if setting `dbdriver`, since
 170         SQLite has no concept of database users. Supports variable
 171         substitution (see below).
 172
 173 gitcvs.dbpass::
 174         Database password.  Only useful if setting `dbdriver`, since
 175         SQLite has no concept of database passwords.
 176
 177 All variables can also be set per access method, see <<configaccessmethod,above>>.
 178
 179 Variable substitution
 180 ^^^^^^^^^^^^^^^^^^^^^
 181 In `dbdriver` and `dbuser` you can use the following variables:
 182
 183 %G::
 184         git directory name
 185 %g::
 186         git directory name, where all characters except for
 187         alpha-numeric ones, `.`, and `-` are replaced with
 188         `_` (this should make it easier to use the directory
 189         name in a filename if wanted)
 190 %m::
 191         CVS module/git head name
 192 %a::
 193         access method (one of "ext" or "pserver")
 194 %u::
 195         Name of the user running git-cvsserver.
 196         If no name can be determined, the
 197         numeric uid is used.
 198
 199 Eclipse CVS Client Notes
 200 ------------------------
 201
 202 To get a checkout with the Eclipse CVS client:
 203
 204 1. Select "Create a new project -> From CVS checkout"
 205 2. Create a new location. See the notes below for details on how to choose the
 206    right protocol.
 207 3. Browse the 'modules' available. It will give you a list of the heads in
 208    the repository. You will not be able to browse the tree from there. Only
 209    the heads.
 210 4. Pick 'HEAD' when it asks what branch/tag to check out. Untick the
 211    "launch commit wizard" to avoid committing the .project file.
 212
 213 Protocol notes: If you are using anonymous access via pserver, just select that.
 214 Those using SSH access should choose the 'ext' protocol, and configure 'ext'
 215 access on the Preferences->Team->CVS->ExtConnection pane. Set CVS_SERVER to
 216 'git-cvsserver'. Note that password support is not good when using 'ext',
 217 you will definitely want to have SSH keys setup.
 218
 219 Alternatively, you can just use the non-standard extssh protocol that Eclipse
 220 offer. In that case CVS_SERVER is ignored, and you will have to replace
 221 the cvs utility on the server with git-cvsserver or manipulate your `.bashrc`
 222 so that calling 'cvs' effectively calls git-cvsserver.
 223
 224 Clients known to work
 225 ---------------------
 226
 227 - CVS 1.12.9 on Debian
 228 - CVS 1.11.17 on MacOSX (from Fink package)
 229 - Eclipse 3.0, 3.1.2 on MacOSX (see Eclipse CVS Client Notes)
 230 - TortoiseCVS
 231
 232 Operations supported
 233 --------------------
 234
 235 All the operations required for normal use are supported, including
 236 checkout, diff, status, update, log, add, remove, commit.
 237 Legacy monitoring operations are not supported (edit, watch and related).
 238 Exports and tagging (tags and branches) are not supported at this stage.
 239
 240 The server should set the '-k' mode to binary when relevant, however,
 241 this is not really implemented yet. For now, you can force the server
 242 to set '-kb' for all files by setting the `gitcvs.allbinary` config
 243 variable. In proper GIT tradition, the contents of the files are
 244 always respected. No keyword expansion or newline munging is supported.
 245
 246 Dependencies
 247 ------------
 248
 249 git-cvsserver depends on DBD::SQLite.
 250
 251 Copyright and Authors
 252 ---------------------
 253
 254 This program is copyright The Open University UK - 2006.
 255
 256 Authors:
 257
 258 - Martyn Smith    <martyn@catalyst.net.nz>
 259 - Martin Langhoff <martin@catalyst.net.nz>
 260
 261 with ideas and patches from participants of the git-list <git@vger.kernel.org>.
 262
 263 Documentation
 264 --------------
 265 Documentation by Martyn Smith <martyn@catalyst.net.nz>, Martin Langhoff <martin@catalyst.net.nz>, and Matthias Urlichs <smurf@smurf.noris.de>.
 266
 267 GIT
 268 ---
 269 Part of the gitlink:git[7] suite