"Fossies" - the Fresh Open Source Software Archive

Member "git-2.23.0.windows.1/Documentation/git-cvsserver.txt" (16 Aug 2019, 15570 Bytes) of package /windows/misc/git-2.23.0.windows.1.zip:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "git-cvsserver.txt": 2.23.0-rc1_vs_2.23.0-rc2.

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