CVS is a version control system. A version control system maintains an organized set of all the versions of files that are made over time. Version control systems allow people to go back to previous revisions of individual files, and to compare any two revisions to view the changes between them. In this way, version control keeps a historically accurate and retrievable log of a file's revisions.
More importantly, version control systems help several people (even in geographically disparate locations) work together on a development project over the Internet or private network by merging their changes into the same source repository. It ensures that two people cannot inadvertently edit the same file at the same time and interfere with each other.
CVS achieves this by maintaining a history of the files of a project as a series of changes. It stamps each change with the time it was made and the user name of the person who made it. Usually, the person provides a bit of text describing why they made the change as well. Given that information, CVS can help developers answer questions like:
Who made a given change?
When did they make it?
Why did they make it?
What other changes did they make at the same time?
Overview of Using CVS
CVS operates on Projects and the files within those projects. FreeBMD has five projects:
UKGEN-Dev
Contains development utilities
UKGEN-FreeBMD
Contains the FreeBMD sources
UKGEN-FreeBMD-Images
Contains the source for the image servers (which contain images of scans)
UKGEN-FreeCEN
Contains the FreeCEN sources
UKGEN-FreeREG
Contains the FreeREG sources
Each of these projects has a repository on the development machine which contains the source files and directories of the project (and the history of changes).
To begin working on one of these projects you first obtain your own working copy of the files and directories in the repository of the project. The process is known as checking out the project repository.
You make your contribution to the project by modifying these files and creating new ones.
This part of the cycle doesn't involve CVS directly. You modify your working copies of project files using a file editor on your local machine. You can save your edited files to test how your changes affect the particular project module you are working in without affecting anyone else's work on those same project files. Nothing you do affects other project participants until you merge your changes into the project repository.
You test and tweak your latest changes in your own workspace to make sure these work without breaking or corrupting the overall project.
Finally, you contribute back or check in your changes to the project repository, merging your work with the most recent working version.
Committing your changes to merge with other developers' work is the most powerful aspect of CVS. If a file that you have changed has also been changed by someone else, CVS checks to ensure that the two sets of changes do not conflict. If they do, it will warn you and you will need to resolve the conflicts possibly by liaising with the person who made the other changes.
This copy-modify-merge cycle is repeated throughout the life of the project by all contributing developers. CVS enables everyone to work on project files simultaneously, to stay up to date on the latest changes contributed by others, and to test how their own changes affect the overall project without interrupting other developers' cycles.
Preparing to use CVS
This section describes the steps you need to take in order to use CVS for the first time. If you have already done this you can skip to the next section.
In order to use CVS to amend the files of a project you will need three things:
The cvs client side software to install on your machine. There are a number of clients available but in this tutorial we will only discuss wincvs which uses a DOS interface (see the section on Using DOS Commands if you are unfamiliar with this). Do an internet search for "cvs client" for other available software which may be easier to use. One such
client that has been used is TortoiseCVS - see below
for more information including problems using TortoiseCVS.
Communications software for communicating securely with the FreeBMD development machine using the SSH protocol. Again there are a number of packages that will do this but we will describe one, PuTTY. Installing a using PuTTY is described here.
A text editor to edit the files. There is a large choice from the simple Window Notepad and Wordpad to very sophisticated editors that understand the structure of different languages (e.g. html).
Having acquired and installed the above you will then need to do the following:
Decide where you want to hold your working copy of the project files. You should create a new folder on your hard drive for this; whilst the naming and location of this folder is arbitrary, a reasonable default would be 'freebmd' located under c:\ (i.e. c:\freebmd). We will refer to this directory as <freebmd> and where this occurs you need to replace <freebmd> with your own location (e.g. c:\freebmd).
Create working copy of the project files (the project repository) on your own machine as described here.
You are now ready to change project files!
Using CVS to edit files
There are two ways you can use CVS - which one you use depends on the kind of changes you will be making. The commands that you use, and the way that you use them, depends on which method you will be using so please following the links below. In the section following this one we will describe the commands in more detail.
Changes are made by developers working alone - this is the method used for source and web page changes. More than one developer may edit the same file and CVS merges the changes.
A file is normally only edited by one person at a time, or multiple editors will co-operate on the changes - this is the method used for district map changes.
CVS commands
The following is a summary of the CVS commands. Make sure you understand which mode you are using, Independent or Co-operative, as described above.
Important notes:
To issue one of the following commands your current directory must be the directory that contains your working copy of the repository (i.e. the directory we refer to as <freebmd>, e.g. c:\freebmd) or a directory beneath it.
If you do not specify a filename with one of the following commands the command applies to all files in your current directory and all directories beneath it.
cvs commit
Commit your changes into the repository (it is good practice to first run cvs diff (see below) and check that the changes being committed are what you intended). You will be presented with a page (probably in Notepad) to enter a short description of the changes you have made to a file (no need to put name or date, they are available automatically). Save the changes and close the file to complete the commit. You also do a commit after adding or removing a file; again a short description of why the file was added or removed should be provided.
cvs update
Get the latest version of a file from the repository. Your modifications to a file are never lost when you use update. If no newer revision exists, running update has no effect. If you have edited the file, and a newer revision is available, CVS will merge all changes into your working copy and will indicate if there are conflicts.
cvs status
Find the latest revision in the repository and compare it with yours. When you use status, one of a number of messages will be output. The following are the ones you are most likely to see:
Up-to-date: The file is identical with the latest revision in the repository.
Locally Modified: You have edited the file, and not yet committed your changes.
Unknown: CVS doesn't know anything about this file. For example, you have created a new file and have not run add.
cvs editors
Find out who is working on a file (Co-operative mode only).
cvs edit
Register that you will be editing a file (Co-operative mode only).
Every so often it is worthwhile doing a general update to get the latest copies from the repository, especially new files. Only changed or new files will be downloaded. To do such an update use the following when in directory <freebmd>
cd UKGEN-FreeBMD cvs update -AdP
to update the UKGEN-FreeBMD project (or other project as appropriate).
Adding a new file
If you need to add a new file to the project create the file in your working copy of the repository and then use the cvs add command - but see below if it is a binary file. The file will not actually be added to the repository until you do a commit on it.
Creating a new executable file
Creating an executable file does not cause CVS to mark the file as executable (since Windows does not have the concept of execute permission on a file). However, an automatic process has been installed in the CVS repository to take care of this in most cases. If the file has a shebang first line (i.e. starting with #!) and does not have at least one execute bit set then it will be marked as "executable for all". In other circumstances the execute bits will need to be set manually on the file in the repository; send an email to the tech mailing list if you do not know how to do this.
Binary files
Binary files (e.g. image files such as .gif) are handled specially by CVS. It doesn't try to report differences when you commit a new version, for example.
If you create a binary file, use the -kb option on the add command, thus
cvs add -kb file
However there is a problem! When you do the first commit on the file CVS puts the whole of the binary in the commit mail message. Therefore, the socially responsible thing to do, unless the binary file is small, is to make the first commit a dummy file and then commit the real file as a second commit.
Creating a new directory
To add a directory, first create it in your working copy of the repository and then do a cvs add. Unlike for a file you do not do a commit ... the directory is added to repository immediately. If you need to add a directory at the top level of the UKGEN-FreeBMD repository it must be added to the conf/webserv_directories file otherwise it will not be deployed in the handoff.
Getting a previous revision
To get a previous revision of a file use
cvs update -r revision -p file
which will cause revision of file to be piped to standard output. The command above will display the revision of the file - but you probably want to store it somewhere! So do this:
cvs update -r revision -p file > DestFile
where DestFile is the file name you want the revision stored in.
Abandoning local edits
Under certain circumstances you may want to abandon edits you have done and revert to the current version in the repository. To do this type
cvs update -C file
Note that your existing version will be copied to a version with a name starting in .#
Reverting to a previous version
Sometimes you will want to revert the source of a module back to a previous revision, for example when changes have been committed that are later found to be not required. There is no revert command in cvs but it is reasonably simple to do a reversion on a single file. First you need to find the current revision (referred to as currentrev below) which you can do using the following:
cvs status filename
You can then feed the value of currentrev found into the following in order to revert to the revision oldrev:
The second update above merges the changes between currentrev and oldrev (the one you want to go back to) into your working directory version which means that the version in your working directory becomes the same as oldrev.
Deleting a file
To remove a file from a project, you must first remove the BMD_LIVE tag using
cvs tag -d BMD_LIVE file
after which you can then remove the file itself (if you do not remove the BMD_LIVE tag, deleting the file will not remove the file from the website). To remove the file itself first delete the file in your working repository, and then use the cvs remove command to mark it for deletion. (Note, however, that with TortoiseCVS these two operations are merged into one, just select the file, right click and select Delete). Next use the cvs commit command on the file specifying in the message why the file is being deleted. The file will be removed immediately from your working repository and from the website at the next handoff.
Committing a file marked with cvs remove does not destroy the file's history. It simply adds a new revision, which is marked as "non-existent". The repository still has records of the file's prior contents, and can recall them as needed - for example, by cvs diff or cvs log.
The documentation for CVS 1.11 is available from www.cvshome.org. Although this is a later version of CVS than the one you will be using, this documentation represents a valuable source of information, although it is not the easiest manual in the world to use!
Abbreviations
Although there are abbreviations for the commands it is probably best to avoid them, at least initially. For historical reasons the abbreviation for commit is ci whereas the abbreviation co is used for checkout, so one can get confused!
As stated above connection with the server is done using the ssh protocol. The recommended software
to do this is PuTTY although there is other software that can be used.
Install PuTTY
Download PuTTY from the PuTTY download site. Choose Windows installer from the options offered.
Restart your machine (in order to get Pageant running in the background).
Generate key
To generate the correct key run PuTTYgen from the program menu.
Select SSH2-RSA and a key length of at least 1024 (use the default if compliant).
Click Generate. Input randomness as directed.
Enter the passphrase (password) you want to use with this mechanism twice. Choose an secure password that only you will know, and if you write it down make sure it is secure.
Click on Save Public Key; this can be anywhere but typically in a folder called .ssh in <freebmd> (i.e. c:\freebmd\.ssh). The filename can be anything but conventionally it is yourname.pub
Click on Save Private Key; typically same place as public key and named yourname.ppk; you need to use this for input to Pageant.
Send your public key, yourname.pub, to together with the projects that you will be involved in.
Do not send your private key (yourname.ppk) to anyone. Treat it as a password.
A login will be set up for you on the FreeBMD development machine. You will receive an e-mail message notifying you of your login name (referred to below as username) and password for trac.
You will be set you up to be mailed with all CVS commits for the projects you are interested in. This will enable you to keep track of the changes being made.
Create a PuTTY saved session
Run putty and set up the following parameters (in the Session section)
Host Name
test.freebmd.org.uk
Port
22
Connection type
SSH
Saved sessions (box)
cvs
Expand the Connection settings by clicking on the "+" next to "Connection" (unless already expanded) and then click on Data
Auto login username
username (your server username which is likely to be different from your FreeBMD username)
Now click on SSH (under Connection) and ensure the following setting
SSH protocol version
2
Now expand the SSH section by clicking on the plus (+) next to "SSH", then click on Auth and ensure the following settings
Bypass authentication entirely
Unchecked
Attempt authentication using Pageant
Checked
Allow agent forwarding
Checked
Click on Session and then click on Save.
Exit by clicking on Cancel.
Create a session
Run pageant. In the task bar at the bottom of the screen a computer with a hat on will appear. Right click on this and select Add key. Navigate to your private key file (this will be cvs-home\.ssh\yourname.ppk) and click on Open. Type your passphrase when prompted.
Note that the security of FreeBMD is now dependent on the security of your machine. Ensure you have a secure logon and timeout. Close your machine when not using it.
You can now run cvs to interact with the server as described previously.
You will need to run pageant and enter your passphrase every time you restart your machine or login to your machine. If you don't you will get the message "No supported authentication methods available".
Using DOS Commands
All of the CVS commands mentioned in this tutorial are executed at the command prompt in a DOS window.
If you are unfamiliar with DOS you should find this section helpful:
The file system on any disk begins with the root (top-level) directory, represented as a backslash. Thus C:\ represents the root directory on the C: drive. Each additional nested directory can be represented as another element in the path, with a backslash used to separate each one. C:\Windows\System\Colour means that the Colour folder is in the System folder in the Windows folder on the C: drive.
To open a DOS window in Windows 98, click on Start - Programs - Ms-DOS Prompt. In Windows XP, Start - All Programs - Accessories - Command Prompt.
When you open a DOS window you should see a command prompt such as C:\>. The first letter indicates which drive is currently in use - the 'active' drive.
If you want to change to a different directory, say to the colour directory, you would type cd c:\system\colour and press 'Enter'. The command prompt will then change to c:\system\colour>, showing that you are now in the colour directory.
Note: File names for the CVS repository, on UNIX, are case sensitive. Therefore, to make things simple for yourself always treat the file names in CVS as case sensitive.
Environment Variables
Each time a DOS window is created an environment is provided to store information (variables) accessible to DOS commands and your applications. Whenever you use CVS the following environment variables have to be set:
set home=<freebmd>, e.g. set home=c:/freebmd (this lets CVS know that freebmd is the 'home' directory in which the files are to be stored). Note: The forward slashes are intentional.
Set cvs_rsh=plink.exe (this lets CVS know that you want to use PuTTY - to use a different ssh
package change the value here).
Path=%path%;c:\program files\cvs (assuming you have put cvs.exe in c:\program files\cvs)
Path=%path%;c:\program files\PuTTY (assuming you have put the PuTTY executales in c:\program files\PuTTY)
Whilst you could do this each time you used CVS it is much more convenient to
have them set automatically for each DOS session you run and this can be done
in the following way:
Right click on My Computer (or My PC) - Properties - Advanced - Environment variables
Under User variables for <username> use New to add
the variables HOME, CVS_RSH and PATH. If there is already a PATH
variable in the User variables for <username> box, click on it and use Edit. Add
"c:\program files\cvs" to the end of the list (if the list is on a single line
precede it with a semi-colon.)
Finally click on OK and the next time you open a DOS box the
environment variables will already have been set.
Windows 98 has a System Configuration Utility (\Windows\System\msconfig.exe), which allows you to set environment variables.
Click on the Autoexec.bat tab and
look for a 'PATH' command. If there is one, click on edit and add your PATH command to the end of the existing one. If you don't see a PATH command, click on new and add the command. Add the HOME and CVS_RSH variables here as well.
Installing CVS
Download the Windows client from
http://ftp.gnu.org/non-gnu/cvs/binary/stable/x86-woe/, choosing the latest version. Extract
the files from the zip file downloaded to c:\Program Files\cvs (or some other location of your
choice - but the rest of the instructions assume you have chosen this location).
Populating your working copy of the repository
Before you can edit any files you need to download the source files into your working copy of the repository.
Open a DOS window and navigate to the 'Home' directory <freebmd>, e.g. cd c:\freebmd.
Note:cvs (as in cvs:/home...) is the PuTTY session name created for the purpose of using CVS as described here.
The next stage takes some time, and you may think nothing is happening. Be patient! There are a lot of files to download. Eventually the files in the repository will start to download into your home directory. The download will be complete when you are returned to the DOS command prompt.
During the download process a folder called UKDGEN-FreeBMD (or as appropriate for other projects) will be created inside the home directory, and will hold all the downloaded project files and folders.
TortoiseCVS
One client that has been used to access CVS is TortoiseCVS. However, this software
appears to be no longer under development or support. Furthermore, since the
installation of new versions of the secure protocol SSH on the servers, access
to CVS from TortoiseCVS has stopped working. A workaround for this is as follows:
create a saved session cvs in PuTTY as described above (unless you already have such a
saved session)
set up TortoiseCVS Preferences to use this saved session (by convention this is called 'cvs') , that is
SSH application (:ext: only):
set to point to PuTTY's plink.exe e.g. C:\Program Files (x86)\PuTTY\plink.exe
SSH parameters (:ext: only):
-load cvs
SSH cvs server (:ext: and :ssh:):
cvs
either edit each Root file in the CVS directory in each folder of your repository to use :ext: instead of :ssh: or (probably the easier option)
download a new version of the repository either as
described above but using a new "Home" folder or
using TortoiseCVS as follows:
Create a new 'Home' folder in Windows Explorer
Right click on the folder, select CVS -> Make New Module
Enter :ext:username@test.freebmd.org.uk:/home/cvs into CVSROOT on TortoiseCVS Make New Module Screen (substitute your server username)
Click Fetch list to get a list of modules
Select UKGEN-FreeBMD module
Click OK - this will download a copy of the repository to your PC.
What is CVS? you involved in and then paste your public key here...)
together with the projects that you will be involved in.
Do not send your private key (yourname.ppk) to anyone. Treat it as a password.
