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