CVS - Version Control for Source Code for sourceforge.net

Overview

CVS is a tool which allows development teams to safely coordinate and track software source code changes.
While CVS is a powerful tool for managing software changes, the SourceForge.net File Release System is a better way to distribute releases to end-users. CVS and the FRS are complementary tools; CVS allows you to distribute the latest development source code within your team, and coordinate the influx of changes to that source code.
CVS is a complex tool. We encourage all new developers to practice CVS commands locally before using SourceForge.net CVS servers for the first time. Instructions on configuring a local CVS repository for testing are provided in CVS client configuration instructions.
The SourceForge.net CVS service offering is segmented in to two separate services: Developer CVS (which allows write access) and anonymous read-only CVS access. For security purposes, all developer CVS access is provided via SSH-based authentication and is available only to authorized project members. Anonymous CVS service is subject to a sync delay. Web-based access is also provided to CVS repository data for all users.
SourceForge.net encourages projects to adopt a revision control system as a way to improve coordination of collaborative team-based development. Project CVS repositories are not bound by quotas. CVS does have some functional limitations which should be considered before use on your development project.
Connection Information

A list of supported CVS clients and configuration information is provided in Recommended User Software Configuration.
As a reminder, only Open Source licensed software may be hosted on SourceForge.net provided services, including CVS.
The following configuration settings are used to access a SourceForge.net-hosted CVS repository:

·         Hostname: PROJECTNAME.cvs.sourceforge.net (PROJECTNAME is the project's UNIX name)

·         Port: 2401 (anonymous :pserver: authentication) or 22 (developer :ext: authentication via SSH)

·         Protocol: :pserver: for anonymous CVS, or :ext: for developers (with SSH for external authentication; export CVS_RSH=ssh)

·         Repository Path: /cvsroot/PROJECTNAME (PROJECTNAME is the project's UNIX name)

·         Username: 'anonymous' for anonymous CVS access or your SourceForge.net username for developer CVS access.

·         Password: There is no password for anonymous CVS access (just hit the enter key when prompted for one). You must generate a SSH key for developer authentication.

Firewalls and proxy servers may present a problem in using CVS. Workaround may be possible using this alternate configuration for developer (but not anonymous) access; contact your ISP or network administrator for assistance if you are having issues with anonymous or developer access and these workarounds do not function for your environment:

·         Hostname: PROJECTNAME.cvs.sourceforge.net (PROJECTNAME is the project's UNIX name)

·         Port: 443

CVS Documentation
CVS is a complex tool.
The document you are reading now is meant to be an introduction to CVS as applied to SourceForge.net. Full reference materials exist, with extensive detail on how to use CVS.
We recommend that all users new to CVS read one of the following:

·         The CVS Manual (the Cederqvist)

·         Open Source Development with CVS (The CVS Book)

CVS Terminology

The following is a list of common terms used throughout the SourceForge.net CVS documentation:

·         CVS client: Software run by a CVS user to access the CVS server.

·         CVS repository: The CVS server stores a copy of the software and data that the project has uploaded. The server retains both the most recent version and every historical version (past changes). This copy of the software and data uploaded by the project is a CVS repository. Each project hosted on SourceForge.net has its own CVS repository.

·         Project UNIX name: The unique name the project founder selected when registering a project for hosting on SourceForge.net. This value can be located on the project summary page (e.g. https://www.sf.net/projects/PROJECTNAME/) to the right of the phrase, "Project UNIX name:".

·         module: The toplevel directories in a CVS repository are called modules. A CVS repository can contain multiple modules. Each module lives independently within the CVS repository. A module is created using the CVS import command. An alias for a module can be created using the 'modules' file.

·         working copy: Though the CVS repository stores every version of every file that has been uploaded to the repository, when you retrieve data from the CVS repository using your CVS client, only one version of each file is saved to your hard drive. The copy of the data you get from the CVS server is called a "working copy", obtained using the "checkout" command. When you checkout your working copy, you will specify which module you wish to retrieve; only the files and directories located in that module will be placed in your working copy.

Most other terms can be found in the "Guide to CVS commands" or "Index" of the CVS manual.
Using CVS

To quickly begin using CVS:

1.    Refer to the "A Day With CVS" section of Open Source Development with CVS. It covers most commands in a step-wise manner that is very helpful.

2.    Read this document.

3.    If you are a developer, generate and post a SSH key for CVS usage.

4.    Install and configure an appropriate CVS client for your platform.

5.    If you are creating a new repository, ask for an import of your existing CVS or RCS repository, or create a module.

6.    Checkout a working copy of the repository.

Importing Data into CVS

SourceForge.net supplies a fresh CVS repository to each project upon approval, containing the basic CVS control files. There are several ways to add data to a CVS repository:
Create a new module from local files: Refer to the "Starting a New Project" section of Open Source Development with CVS.
Create a new module, keeping history from a previous CVS or RCS repository: Build an archive of the content to be extracted into the repository, in either .zip, .tar.gz or .tar.bz2 format. Upload the archive to the project's group directory on the shell server. Make sure the file is not world-writeable:

# Login to the shell server and run the following command

# Replace FILENAME with the full path to the archive file uploaded earlier

chmod 0664 FILENAME

Once the file has been uploaded, submit a Support Request indicating the project UNIX name, the desired module name (if the toplevel directory isn't the module name) and the full path to the repository archive on the shell server.
Add a directory tree with files to an existing module: Refer to the "Starting a New Project" section of Open Source Development with CVS. If the content is destined for a subdirectory in a module of the repository, append the directory name after the module name. For example, if the module name is 'src' and the directory to be created under 'src' is 'documentation', use 'src/documentation' for the module name (denoted as projname in Open Source Development with CVS).
Move or copy content from one project's CVS repository/module to another: Create a Support Request asking for the content to be moved or copied.
Sync Delay

SourceForge.net maintains two pools of CVS data; one for developer CVS access, rsync and ViewVC and one for anonymous (:pserver:). Data is synchronized between the developer data pool and the other data pool periodically. Currently, there is a delay of at most 1 hour (with 10 minutes being typical) between the developer and anonymous CVS data pools.
SourceForge.net CVS Environment

SourceForge.net currently runs the 1.11.x series of CVS software. Regular version upgrades occur based on testing of new releases and security needs.
Interactive shell access to the CVS servers is not provided.
The SourceForge.net CVS Environment does not support the following common CVS features:

·         PreservePermissions: disabled to prevent loss of team or public access to repository.

·         Symbolic Links (symlinks): Handling of symbolic links in CVS is not mature, symlink support is disabled to reduce support overhead.

·         -t and -f cvswrappers options: Not supported by the version of CVS SourceForge.net uses (support existed in 1.10.x, but was dropped in 1.11.x).

Pre- and Post-Commit Scripts

CVS is capable of running server-side scripts prior to writing commit changes to a repository, or in logging those changes immediately after a commit. cvs_acls and syncmail are installed and maintained in a centralized location on the CVS server by SourceForge.net staff. To install and use a script:

1.    Checkout a copy of the 'CVSROOT' module, which is present by default in all CVS repositories.

2.    Set the permissions on the script locally to be as needed on the CVS server. CVS does not allow you to change permissions post-commit.

3.    Add the script to be run before or after the commit to the 'CVSROOT' module.

4.    Modify the 'checkoutlist' file in the 'CVSROOT' module to include the filename of the script on a single line by itself.

5.    Commit the changes to the repository.

6.    Modify either the 'commitinfo' or 'loginfo' file to include a line referencing the script to be run either before or after commit, respectively.

7.    Perform a commit to test the functionality of the script.

The CVS server supports the following scripting languages:

·         Shell scripts (/bin/bash; /bin/tcsh; /bin/zsh; /bin/ksh)

·         Perl (/usr/bin/perl)

·         Python 2.x (/usr/bin/python)

·         Ruby (/usr/bin/ruby)

·         Tcl (/usr/bin/tcl)

Commit Notifications via Email (syncmail)

CVS syncmail can be configured to email a log after every commit. SourceForge.net maintains a central install of the cvs syncmail script. Mail can be sent to SourceForge.net mail aliases or SourceForge.net-hosted mailing lists from the CVS server.
To configure syncmail using our recommended configuration do the following:

1.    Checkout a copy of the CVSROOT module

2.    Modify the 'loginfo' file per the values defined below

3.    Commit the loginfo changes back to the repository

# This line sends all changes to the CVSROOT module to the user specified

# by USERNAME. It is recommended that someone be watching this module

# as it shouldn't need to be modified very often.

CVSROOT /cvsroot/sitedocs/CVSROOT/cvstools/syncmail %{sVv} USERNAME@users.sourceforge.net

# This sends mail to a mailing list, defined by the PROJECTNAME-LISTNAME

# value. Any changes to any modules in the project will thus generate an

# email message to the mailing list specified.

DEFAULT /cvsroot/sitedocs/CVSROOT/cvstools/syncmail %{sVv} PROJECTNAME-LISTNAME@lists.sourceforge.net

Refer to the CVS Manual and syncmail sources for additional configuration options.
Permissions

Read access cannot be restricted: This limitation is imposed to ensure all code is available to the public per the spirit of the Open Source Definition. No means is provided nor supported to restrict anonymous access to a project's CVS repository.
Access for project developers: Developer CVS access is only provided to project members who have been granted 'Allow access to CVS repository (developer access)' on the developer permissions page. Project administrators can enable/disable CVS access entirely to a project developer with this setting. Developers without this enabled will have to use anonymous CVS access.
Fine-grained write permissions: cvs_acls is centrally installed and maintained on the CVS server by SourceForge.net staff. cvs_acls allows for per-module or per-directory or per-branch restriction of any CVS write operations that require a commit. cvs_acls does not block a user from creating a new module; the only way to do that is to block CVS access entirely. To configure cvs_acls:

1.    Checkout a copy of the 'CVSROOT' module

2.    Create a file with the name 'avail' in the 'CVSROOT' module with the contents as described below

3.    Edit the 'checkoutlist' file and add an entry for 'avail' on its own line, without quotes

4.    Commit the changes to the repository

5.    Edit the 'commitinfo' file and add the entry as described below

6.    Commit the change to enable cvs_acls

The cvs_acls script contains a list of instructions in how to format the avail file. We recommend you read the instructions and do the following to ensure you maintain access to the repository:

unavail

avail|YOUR_USERNAME

YOUR_USERNAME should be your SourceForge.net username, lowercase, as normal. Add a blank line at the end of the 'avail' file, cvs_acls expects a blank line at the end.
Add the following to the 'commitinfo' file after any existing text, as described above:

ALL /cvsroot/sitedocs/CVSROOT/cvstools/cvs_acls

Web-based Repository Browsing (ViewCVS)

ViewCVS provides a graphical interface for browsing a CVS repository using a web browser. This allows individuals to view CVS content without the use of a CVS client. It supports common actions such as viewing the contents of a file in CVS, viewing the diff between different file revisions, syntax highlighting and line based annotations (blame). This service is provided for every SourceForge.net project and may be accessed using the 'CVS' link on the project summary page.
Rsync

Rsync access to the developer CVS content is provided, allowing projects and other users direct access to the raw CVS repository data, much like the deprecated nightly tarball service. The use of rsync means that there will no longer be a delay between what is in the repository and the data that a user can download for backups or major code refactoring. Rsync can be used to copy an entire project's repository (replace PROJECTNAME with the project UNIX name):

$ rsync -av rsync://PROJECTNAME.cvs.sourceforge.net/cvsroot/PROJECTNAME/* .

Note that you cannot rsync the entire cvsroot rsync module for performance reasons.
Nightly Tarballs

Nightly tarballs have been deprecated. Use rsync instead.
Repository Mirroring

The SourceForge.net CVS repository can be mirrored using rsync. Other repository mirroring tools are not supported. Mirroring an external repository on SourceForge.net services is not supported.
Repository Upkeep and Management

File and Directory Deletion: CVS provides no mechanism to fully delete a file or directory from the CVS repository. If a file or directory needs to be removed, a Support Request will need to be submitted. As interactive access is not provided, a project cannot delete or move content without intervention. A specific file revision (based on CVS revision identifiers) can be removed using the CVS admin command's '-o' option.
Repository Restructuring: File and directory deletions, moves or renames can be requested by submitting a Support Request. The changes can either be provided as a task list or in the form of a bash shell script. Larger repository restructuring tasks can be done by downloading a copy of the repository via rsync and modifying its content as necessary. The modifications can then be imported into the repository replacing its current content.
CVS Admin Command Usage: The CVS admin command can perform many useful operations. Some of these include: removal of a commit message, removal of a specific file revision and excluding keyword expansion. It is highly recommended that the CVS manual's description of the admin command be read prior to running it.
Backups: Project's are responsible for backing-up their CVS repository. Projects may retrieve a copy of their repository via rsync to regularly create an offsite backup.
Restore: SourceForge.net staff will manually restore your repository to a prior state if provided a viable backup of your repository (projects are responsible for generating and supplying their own backups). Replacement repository data should be supplied as if you were to "Create a new module keeping history from a previous CVS or RCS repository".
CVS Limitations

Binary File Handling: CVS is designed to work with text-based data. Changes to text-based data are captured as diffs. CVS does not keep diffs of binary data changes, and instead keeps full copies of each revision. This will increase the size of nightly tarballs and the on-server storage of the repository. We discourage the storage of binary data on our CVS servers as result. Before committing a binary file to CVS, read the "Handling binary files" section of the CVS manual.
File and Directory Deletion/Moves: CVS does not provide the means to remotely move or remove files or directories. SourceForge.net does not provide direct shell access to repositories. Requests for file moves/removes need to be submitted to SourceForge.net staff for manual processing.
Case Sensitivity in File and Directory Names: SourceForge.net CVS servers are running a version of the Linux operating system. On SourceForge.net CVS servers, filenames are case-sensitive; a file with the name of 'filename' is distinctly separate from a file with the name of 'Filename'. This is in direct contrast with the case insensitivity of operating systems such as Microsoft Windows. Windows would treat both of those filenames as the same file. Users of case insensitive operating systems should be careful with their filenames. This can prevent access to data in your repository for some users. Should conflicting filenames be committed into the repository, a Support Request will need to be filed.
File Permissions: CVS has no reliable mechanism for the remote control of file permissions. This comes in to play most frequently when storing executable files (such as scripts) within CVS. Permissions are defined at time of file add/commit. Manual intervention is required to change file permissions after-the-fact.
File Naming Limitations: File and directory names should not contain spaces; not all platforms handle spaces well. Commonly-reserved filenames should also be avoided. Some reserved filenames follow (treat all as if they are case insensitive, don't use them with a different case):

·         Windows: con, aux, com, com1 - com9, prn, lpt1 - lpt3, nul, a: - z:, clock$

·         CVS: core, CVS

Support

SourceForge.net provides support for recommended CVS clients. Other clients are unsupported; you should seek support from the vendor or user community if using a client not on our recommendation list.
Before reporting an issue to SourceForge.net staff, do the following:

·         Ensure you are using and have properly configured a supported CVS client

·         Read through this document to see if the operation can be completed by a project member

·         Read through the CVS documentation

·         If using a command-line CVS client for developer CVS access, you must: export CVS_RSH=ssh

·         If accessing CVS via SSH authentication, you must have permissions. Use anonymous pserver access otherwise.

If unable to resolve the issue yourself, contact SourceForge.net staff by submitting a Support Request with this information:

·         Operating System and Version

·         CVS Client and Version

·         SSH Client and Version (if applicable)

·         The full output of the command, including the execution of the command itself and any of its output

·         Any additional troubleshooting information collected as per the Support section in the CVS client configuration instructions

·         A screenshot, if possible

·         A brief description of the attempted operation

·         What you believe may be causing the issue