Before you can do anything, you must tell CVS the location of the repository you'll be accessing. This isn't a concern if you already have a working copy checked out – any working copy knows what repository it came from, so CVS can automatically deduce the repository for a given working copy. However, let's assume you don't have a working copy yet, so you need to tell CVS explicitly where to go. This is done with the -d global option (the -d stands for "directory", an abbreviation for which there is a historical justification, although -r for "repository" might have been better), followed by the path to the repository. For example, assuming the repository is on the local machine in /usr/local/cvs (a fairly standard location):
floss$ cvs -d /usr/local/cvs command
In many cases, however, the repository is on another machine and must therefore be reached over the network. CVS provides a choice of network access methods; which one you'll use depends mostly on the security needs of the repository machine (hereinafter referred to as "the server"). Setting up the server to allow various remote access methods is covered in Repository Administration; here we'll deal only with the client side.
Fortunately, all the remote access methods share a common invocation syntax. In general, to specify a remote repository as opposed to a local one, you just use a longer repository path. You first name the access method, delimited on each side by colons, followed by the username and the server name (joined with an @ sign), another separator colon, and finally the path to the repository directory on the server.
Let's look at the pserver access method, which stands for "password-authenticated server":
floss$ cvs -d :pserver:email@example.com:/usr/local/cvs login (Logging in to firstname.lastname@example.org) CVS password: (enter your CVS password here) floss$
The long repository path following -d told CVS to use the pserver access method, with the username jrandom, on the server cvs.foobar.com, which has a CVS repository in /usr/local/cvs. There's no requirement that the hostname be "cvs.something.com" by the way; that's a common convention, but it could just as easily have been:
floss$ cvs -d :pserver:email@example.com:/usr/local/cvs command
The command actually run was login, which verifies that you are authorized to work with this repository. It prompts for a password, then contacts the server to verify the password. Following Unix custom, cvs login returns silently if the login succeeds; it shows an error message if it fails (for instance, because the password is incorrect).
You only have to log in once from your local machine to a given CVS server. After a successful login, CVS stores the password in your home directory, in a file called .cvspass. It consults that file every time a repository is contacted via the pserver method, so you only have to run login the first time you access a given CVS server from a particular client machine. Of course, you can rerun cvs login anytime if the password changes.
Note: pserver is currently the only access method requiring an initial login like this; with the others, you can start running regular CVS commands immediately.
Once you've stored the authentication information in your .cvspass file, you can run other CVS commands using the same command-line syntax:
floss$ cvs -d :pserver:firstname.lastname@example.org:/usr/local/cvs command
Getting pserver to work in Windows may require an extra step. Windows doesn't have the Unix concept of a home directory, so CVS doesn't know where to put the .cvspass file. You'll have to specify a location. It's normal to designate the root of the C: drive as the home directory:
C:\WINDOWS> set HOME=C: C:\WINDOWS> cvs -d :pserver:email@example.com:/usr/local/cvs login (Logging in to firstname.lastname@example.org) CVS password: (enter password here) C:\WINDOWS>
Any folder in the file system will suffice. You may want to avoid network drives, though, because the contents of your .cvspass file would then be visible to anyone with access to the drive.
In addition to pserver, CVS supports the ext method (which uses an external connection program, such as rsh or ssh), kserver (for the Kerberos security system version 4), and gserver (which uses the GSSAPI, or Generic Security Services API, and also handles Kerberos versions 5 and higher). These methods are similar to pserver, but each has its own idiosyncrasies.
Of these, the
ext method is probably the most commonly used. If
you can log into the server with rsh or ssh, you can use the
method. You can test it like this:
floss$ rsh -l jrandom cvs.foobar.com Password: enter your login password here
Okay, let's assume you successfully logged in and logged out of the server with rsh, so now you're back on the original client machine:
floss$ CVS_RSH=rsh; export CVS_RSH floss$ cvs -d :ext:email@example.com:/usr/local/cvs command
The first line sets (in Unix Bourne shell syntax) the CVS_RSH environment variable to rsh, which tells CVS to use the rsh program to connect. The second line can be any CVS command; you will be prompted for your password so CVS can log into the server.
If you're in C shell rather than in Bourne shell, try this:
floss% setenv CVS_RSH rsh
and for Windows, try this:
C:\WINDOWS> set CVS_RSH=rsh
The rest of the tour will use the Bourne syntax; translate for your environment as necessary.
To use ssh (the Secure Shell) instead of rsh, just set the CVS_RSH variable appropriately:
floss$ CVS_RSH=ssh; export CVS_RSH
Don't get thrown by the fact that the variable's name is CVS_RSH but you're setting its value to ssh. There are historical reasons for this (the catch-all Unix excuse, I know). CVS_RSH can point to the name of any program capable of logging you into the remote server, running commands, and receiving their output. After rsh, ssh is probably the most common such program, although there are probably others. Note that this program must not modify its data stream in any way. This disqualifies the Windows NT rsh, because it converts (or attempts to convert) between the DOS and Unix line-ending conventions. You'd have to get some other rsh for Windows or use a different access method.
The gserver and kserver methods are not used as often as the others and are not covered here. They're quite similar to what we've covered so far; see the Cederqvist for details.
If you only use one repository and don't want to type -d repos each time, just set the CVSROOT environment variable (which perhaps should have been named CVSREPOS, but it's too late to change that now):
floss$ CVSROOT=/usr/local/cvs floss$ export CVSROOT floss$ echo $CVSROOT /usr/local/cvs floss$
floss$ CVSROOT=:pserver:firstname.lastname@example.org:/usr/local/cvs floss$ export CVSROOT floss$ echo $CVSROOT :pserver:email@example.com:/usr/local/cvs floss$
The rest of this tour assumes that you've set CVSROOT to point to your repository, so the examples will not show the -d option. If you need to access many different repositories, you should not set CVSROOT and should just use -d repos when you need to specify the repository.