SourceForge.net provides support for several CVS clients, including TortoiseCVS. TortoiseCVS is a CVS client that runs on the Microsoft Windows platform. TortoiseCVS is integrated with Windows Explorer (Windows Explorer is the file manager in Windows, not the web browser of a similar name, Internet Explorer), rather than a separate stand-alone application. Since most Windows users are comfortable with the Windows Explorer interface, it is often easy for new CVS users to escape the learning curve by using TortoiseCVS.
How does TortoiseCVS differ from other Windows-based CVS clients? TortoiseCVS is designed for simplicity and ease-of-use, with direct access to only the most common CVS operations, and with fewer preference options than other Windows-based CVS clients. TortoiseCVS is designed for interactive use, not for scripting of CVS operations. Other CVS clients are available for Microsoft Windows users. These include WinCvs, a stand-alone graphical CVS client application which includes a more advanced user interface (sometimes desired by seasoned CVS users); and the command-line CVS client included with Cygwin, which matches the interface of the command-line CVS client found on UNIX-based OS platforms, and allows automation of CVS operations in scripts.
SourceForge.net staff recommend the use of the most recent TortoiseCVS release marked "stable", which may be more recent than the version used for these instructions. Stable releases of TortoiseCVS may be downloaded from the TortoiseCVS project on SourceForge.net.
Configuring TortoiseCVS for Developer SSH Authentication
These are the settings that should be used when connecting to the CVS server as a developer for read/write access to the CVS repository. You must be a project member or administrator with CVS access permissions to be able to access CVS in this manner.
If you are not a project member or administrator with CVS access permissions, you may obtain read-only access to the repository via anonymous pserver authentication, but cannot use the instructions presented in this section.
If you have not already done so, you should download and install the TortoiseCVS software.
Before configuring TortoiseCVS, configure an SSH key for authentication to the CVS server.
To configure a source folder, in the Windows Explorer, right-click the folder which will be used for the Source Code and select "Checkout CVS..."
The following settings should be configured to use TortoiseCVS with SSH authentication:
- Protocol: Secure Shell (:ext:)
- Server: PROJECTNAME.cvs.sourceforge.net
- Repository folder: /cvsroot/PROJECTNAME (PROJECTNAME is your project's UNIX name. NOTE: all letters will be lowercase)
- User name: Enter your SourceForge.net username (the same one you use to login to the SourceForge.net website).
- Module: Enter the name of the module you wish to work with.
Make sure that the 'SSH cvs server' field in the 'Tools' tab of the TortoiseCVS preferences is set to 'cvs'.
The first time you try to connect, the PuTTY Security Alert window will appear. You should compare the server's fingerprint to our SSH Host Key Fingerprint Listing. If the fingerprints match, you should click on the 'Yes' button; otherwise click the 'No' button and notify SourceForge.net staff.
If you are asked for a password, you did not properly configure SSH key authentication, Pageant is not running, or your SSH key has not been loaded in to Pageant. SSH key authentication must be configured before CVS access via SSH will function properly.
Configuring TortoiseCVS for Anonymous pserver Authentication
Read-only access to any project CVS repository may be obtained using anonymous pserver-based authentication. Working copies generated in this manner cannot be used to perform write operations (a fresh checkout via SSH authentication would be needed by a developer who wishes to make repository changes). You need not have a SourceForge.net user account to access repositories via anonymous pserver.
To configure a checkout, in the Windows Explorer, right-click the folder which will be used for the Source Code and select "Checkout CVS..."
The following settings should be configured to use TortoiseCVS with pserver authentication:
- Protocol: Password server (:pserver:)
- Server: PROJECTNAME.cvs.sourceforge.net
- Repository folder: /cvsroot/PROJECTNAME (PROJECTNAME is the UNIX name of the project whose repository you wish to access NOTE: all letters will be lowercase).
- User name: anonymous
- Module: Enter the name of the module you wish to work with.
These configuration settings are the only settings needed in order to access a repository for read operations (checkout, update). You should not be prompted for a password when accessing a repository in this manner; if you are prompted for a password, contact SourceForge.net staff for assistance after you have verified that your configuration settings match those provided here.
Configuring TortoiseCVS Around a Firewall
Many users are behind firewalls or proxy servers which block traffic on the TCP ports normally used to access our CVS servers (22 for SSH authentication). We provide SSH access to our CVS servers using port 443 (normally SSL-encrypted HTTP web traffic), to eliminate some of the problems users encounter.
In some cases, proxies or firewalls modify the packets sent on these ports as well, which is not something that can be overcome. For these cases, you should contact your Network Administrator or ISP for further assistance.
These instructions should be followed only if you know you are behind a firewall or proxy which is blocking outbound traffic on port 22.
For developer access to repositories via SSH, from behind a firewall or proxy:
- Install PuTTY and configure PuTTY for an SSH session. The session name and hostname used for this should be 'PROJECTNAME.cvs.sourceforge.net' (where PROJECTNAME is the project's UNIX name). You must also change the connection port for the SSH connection to port 443.
- Download, install and configure TortoiseCVS for developer access normally.
If the standard service ports (TCP 22 for SSH, TCP 2401 for pserver) do not function properly due to a firewall or proxy, and the above workaround also does not work properly, please contact your network administrator or ISP for further assistance.
Basic CVS usage: CVS is a complex tool, designed mainly for developers. Though graphical clients like TortoiseCVS ease the learning curve significantly, it is still important to understand the basics of how CVS works before deciding to use it for your project. Basic information about CVS may be found in the following places:
Basic TortoiseCVS usage: Instructions for using TortoiseCVS may be found in the TortoiseCVS User's Guide.
FIXME - The link to "TortoiseCVS User's Guide" return a non-human readable content. It appears to be a problem with the doc at tortoisecvs.sourceforge.net. May want to decide how best to handle the multiple references to this link in this page.
TortoiseCVS uses the context menu in Windows Explorer for operations and special icons to denote the status of files and directories (are the files in my working copy (sandbox) current, have they been updated locally but are not yet committed?). In general, you will right click inside of a directory and select the operation from the context menu that pops up. The most common options will be on the main menu; some of the less common options will be present under the expanding "CVS" entry on the context menu.
Common read operations (available to everyone):
- Checkout: Follow the instructions in the TortoiseCVS User's Guide in the "Basic Usage of TortoiseCVS" -> "Checking out a Module" section or the "Command Reference for TortoiseCVS" -> "Obtaining a Working Copy: CVS Checkout..." section.
- Update: Follow the instructions in the TortoiseCVS User's Guide in the "Basic Usage of TortoiseCVS" -> "Updating your Sandbox" section or the "Command Reference for TortoiseCVS" -> "Getting Other People's Changes: CVS Update" section.
Common write operations (available to developers via SSH authentication):
- Commit: Follow the instructions in the TortoiseCVS User's Guide in the "Basic Usage of TortoiseCVS" -> "Committing your Changes to the Repository" section or the "Command Reference for TortoiseCVS" -> "Making Your Changes Available to Others: CVS Commit..." section.
- Import: Follow the instructions in the TortoiseCVS User's Guide in the "Advanced Usage of TortoiseCVS" -> "Creating a new Repository or Module" section.
- Add: Follow the instructions in the TortoiseCVS User's Guide in the "Basic Usage of TortoiseCVS" -> "Adding Files and Directories to the Repository" section or the "Command Reference for TortoiseCVS" -> "Adding New Files: CVS Add and CVS Add Contents..." section.
Learning CVS using a local repository: CVS requires some practice to learn. Developers who are new to CVS may wish to create a local CVS repository on their workstation to experiment with TortoiseCVS before making changes to their project CVS repository. The TortoiseCVS project provides instructions on setting-up a local repository.
Troubleshooting Authentication Problems
SourceForge.net provides CVS access both to project members (developers) and to the community (non-developers).
Am I a developer? Developers are listed as members of the project. Developers access the project CVS repository via SSH authentication, allowing them to perform write operations. Users who are not a member of the project team must use anonymous pserver-based authentication to access the repository; they cannot use SSH.
Password for anonymous access: When using anonymous pserver-based authentication, no password should be entered; the username should be set to 'anonymous', not your SourceForge.net username.
Write operations via pserver authentication: pserver-based repository access does not permit write operations. Write operations may be performed using SSH authentication as a developer.
Developer use of passwords: Project developers should use SSH keys to authenticate to the project CVS servers. Use of passwords for developer CVS authentication will be deprecated in the near future.
Issues with SSH keys: Troubleshooting of SSH key usage is covered in our guide to SSH key generation.
Developer CVS access: It is within the discretion of the project administrator to grant CVS write access to project developers. These permissions are shown on the summary page of the Project Admin pages (which may be accessed by all project members). Those developers who have been granted CVS access by the project administrator should access the repository via SSH authentication. Developers who have not been granted CVS access must access the repository via anonymous pserver.
TortoiseCVS is a fully-supported means to access SourceForge.net project CVS repositories. Issues related to the TortoiseCVS software should be directed to the TortoiseCVS project team. Issues related directly to using TortoiseCVS with SourceForge.net should be directed to SourceForge.net staff. Please use the following instructions for issue submission.
Support for TortoiseCVS software bugs may be obtained from the TortoiseCVS project on SourceForge.net as described on the TortoiseCVS Support Page. Before reporting issues to the TortoiseCVS team, you are encouraged to review the following:
- TortoiseCVS User's Guide
- Technical FAQ
- Mailing List archives
- Existing issue reports in the TortoiseCVS Bug Tracker
SourceForge.net staff provides support for usage issues pertaining to the TortoiseCVS client. Please collect the following information specific to this client and then follow the instructions provided for CVS support:
Generate a verbose client progress log and attach it to the Support Request. Change the 'Progress Messages' setting in the TortoiseCVS 'Preferences' to 'Loud' and save the changes. Then, attempt the command that is failing. The output in the Progress dialog that is displayed should be either included directly in the body of the Support Request or attached as a text file.