Configuration management with cvs and open source tools

Coffee Affiliate Revenue Advertising
Cooking Tips Blogging, RSS & Feeds Branding
Recipes & Food and Drink Domain Name Business Management
Wine & Spirits E-Book Business Ethics
Elder Care E-commerce Careers, Jobs & Employment
Babies & Toddler Email Marketing Customer Service
Pregnancy Ezine Marketing Marketing
Acne Ezine Publishing Networking
Aerobics & Cardio Forums & Boards Network Marketing
Alternative Medicine Internet Marketing Pay-Per-Click Advertising
Beauty Tips Online Auction Presentation
Depression Search Engine Optimization Public Relations
Diabetes Spam Blocking Sales
Exercise & Fitness Streaming Audio & Online Sales Management
Hair Loss Music Sales Telemarketing
Medicine Traffic Building Sales Training
Meditation Video Streaming Small Business
Muscle Building & Bodybuilding Web Design Strategic Planning
Nutrition Web Development Entrepreneur
Nutritional Supplements Web Hosting Negotiation Tips
Weight Loss Web Site Promotion Team Building
Yoga Broadband Internet Top Quick Tips
Martial Arts VOIP Book Marketing
Finding Happiness Computer Hardware Leadership
Inspirational Data Recovery & Backup Positive Attitude Tips
Breast Cancer Internet Security Goal Setting
Mesothelioma & Cancer Software Innovation
Fitness Equipment Success
Nutritional Supplements Time Management
Weight Loss Public Speaking
Get Organized - Organization

Mobile & Cell Phone Book Reviews
Credit Video Conferencing College & University
Currency Trading Satellite TV Psychology
Debt Consolidation Dating Science Articles
Debt Relief Relationships Religion
Loan Game Personal Technology
Insurance Casino & Gambling Humanities
Investing Humor & Entertainment Language
Mortgage Refinance Music & MP3 Philosophy
Personal Finance Photography Poetry
Real Estate Golf Book Reviews
Taxes Attraction Medicine
Stocks & Mutual Fund Motorcycle Coaching
Structured Settlements Fashion & Style Creativity
Leases & Leasing Crafts & Hobbies Dealing with Grief & Loss
Wealth Building Home Improvement Motivation
Home Security Interior Design & Decorating Spirituality
Landscaping & Gardening Stress Management
Pets Article Writing
Marriage & Wedding Writing
Holiday Political
Fishing Copywriting
Aviation & Flying Parenting
Cruising & Sailing Divorce
Outdoors
Vacation Rental

Configuration Management with CVS
and Open Source Tools

Derek Clifford

Configuration Management with CVS and Open Source Tools
By Derek Clifford

Version 0.90

Copyright © 2002,2003Derek Clifford.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.2 or any later version published by the Free
Software Foundation; with no Invariant Sections, no Front-Cover
Texts, and no Back-Cover Texts.
A copy of the license is included in the appendix entitled "GNU
Free Documentation License".

The Author

Derek Clifford is a director of Micro Logic Consultants, a
consultancy specialising in configuration management, design and
rollout of standard configurations, and general Windows and unix
support.
Contact email: derek@mlc-consultants.co.uk

Contents

Contents
Contents........................................................................................................................iii
Tables ...........................................................................................................................vi
Figures.........................................................................................................................vii
Screenshots..................................................................................................................vii
Introduction ................................................................................................................... 1
Typographical Conventions....................................................................................... 2
Glossary..................................................................................................................... 2
Planning for Installation ................................................................................................ 5
Configuration ............................................................................................................ 5
Sizing......................................................................................................................... 7
Code Organisation..................................................................................................... 7
Times and Timezones................................................................................................ 7
Installation................................................................................................................... 11
Unix Systems........................................................................................................... 11
Common Steps ........................................................................................................ 11
Client/Server Mode ................................................................................................. 12
Troubleshooting ...................................................................................................... 13
Windows Systems ................................................................................................... 14
CVSNT Differences ................................................................................................ 15
Connection and Authentication ................................................................................... 17
Password Server ...................................................................................................... 17
Remote Shell ........................................................................................................... 18
Secure Shell............................................................................................................. 18
GSSAPI ................................................................................................................... 20
Kerberos 4 ............................................................................................................... 20
The Repository ............................................................................................................ 21
Modifying the Repository Files............................................................................... 30
How CVS Uses the CVSROOT Files...................................................................... 30
Hanging Locks ........................................................................................................ 32
The User Environment ................................................................................................ 33
Environment Variables............................................................................................ 34
Format of CVS Commands ......................................................................................... 37
Revisions ................................................................................................................. 37
Tags ......................................................................................................................... 38
Setting up the Repository ............................................................................................ 39
Importing From Other Repositories ........................................................................ 41
Adding a Directory Structure .................................................................................. 41
Adding and Removing Files.................................................................................... 41
Development ............................................................................................................... 43
Obtaining a Working Copy ..................................................................................... 43
Making Changes...................................................................................................... 45
The annotate Command........................................................................................... 51
Customised Logging................................................................................................ 51
The Diff Command ................................................................................................. 52

iii


Checkout –p............................................................................................................. 52
Abandoning Changes .............................................................................................. 52
Keyword Substitution.............................................................................................. 53
Binary Files ............................................................................................................. 53
Sticky Options ......................................................................................................... 54
Exclusive Locks ...................................................................................................... 54
Strange Files ............................................................................................................ 55
Revisions, Releases and Branches............................................................................... 57
Working on a Branch .............................................................................................. 59
Merging a branch..................................................................................................... 60
Backing Out a Change............................................................................................. 61
The Vendor Branch ................................................................................................. 61
Source Distribution and Mirror Sites .......................................................................... 63
Windows Problems...................................................................................................... 65
Front Ends ................................................................................................................... 67
WinCVS .................................................................................................................. 67
gcvs ......................................................................................................................... 68
Cervisia ................................................................................................................... 69
CVSIn...................................................................................................................... 70
Lincvs ...................................................................................................................... 70
EMACS ................................................................................................................... 71
VIM ......................................................................................................................... 71
Build Systems.............................................................................................................. 73
Make........................................................................................................................ 75
Jam .......................................................................................................................... 75
Cook ........................................................................................................................ 75
Odin......................................................................................................................... 75
Visualising the Source Tree......................................................................................... 77
Diff and Merge Programs............................................................................................ 79
Windows Programs ................................................................................................. 79
Unix Programs......................................................................................................... 81
Anonymous CVS......................................................................................................... 83
Problem Tracking ........................................................................................................ 85
CVStrac ................................................................................................................... 85
Bugzilla/CVSZilla ................................................................................................... 87
Administrative Tasks................................................................................................... 89
Backup..................................................................................................................... 89
Tidying up the Repository ....................................................................................... 89
CVS Defaults........................................................................................................... 90
Reset the Default Branch......................................................................................... 90
Other Utilities .............................................................................................................. 91
Appendix A Environment Variables ........................................................................... 93
Appendix B CVS Command Reference ...................................................................... 95
Global Options ........................................................................................................ 95
Admin Commands................................................................................................. 108

iv

Contents

Data Formats ......................................................................................................... 110
Other Date Formats ............................................................................................... 111
Alternate Command Names .................................................................................. 111
Appendix C - Customisation ..................................................................................... 113
modules ................................................................................................................. 113
commitinfo ............................................................................................................ 114
loginfo ................................................................................................................... 114
verifymsg............................................................................................................... 114
Appendix D - Common Tasks................................................................................... 115
Add a directory to a module .................................................................................. 115
Add a file to a module ........................................................................................... 115
Back out a change.................................................................................................. 115
Checkout a branch ................................................................................................. 115
Checkout a module................................................................................................ 116
Commit a module .................................................................................................. 116
Create a branch...................................................................................................... 116
Exclusive lock ....................................................................................................... 116
Merge a branch...................................................................................................... 116
Remove a file ........................................................................................................ 116
Remove a directory ............................................................................................... 116
Return the working directory to the current revision............................................. 117
Tag a Release ........................................................................................................ 117
Update a working directory ................................................................................... 117
Appendix E – Resources ........................................................................................... 119
Appendix F – GNU Free Documentation Licence .................................................... 121
Index.......................................................................................................................... 129

v


Tables
Table 1 CVS Supported Platforms .................................................................................. 11
Table 2 CVSNT passwd options ..................................................................................... 15
Table 3 Connection Methods .......................................................................................... 34
Table 4 History Logging Options.................................................................................... 50
Table 5 Keywords ........................................................................................................... 53
Table 6 Environment Variables....................................................................................... 94
Table 7 Common Global Options.................................................................................... 95
Table 8 Client Global Options......................................................................................... 96
Table 9 Server Global Options ........................................................................................ 96
Table 10 add command options....................................................................................... 97
Table 11 annotate command options ............................................................................... 97
Table 12 checkout command options .............................................................................. 98
Table 13 commit command options ................................................................................ 98
Table 14 diff common command options........................................................................ 98
Table 15 diff formatting options...................................................................................... 99
Table 16 edit command options ...................................................................................... 99
Table 17 edit actions ..................................................................................................... 100
Table 18 editors command options................................................................................ 100
Table 19 export command options ................................................................................ 100
Table 20 history commandoptions ................................................................................ 101
Table 21 history output.................................................................................................. 102
Table 22 import command options................................................................................ 102
Table 23 import output .................................................................................................. 102
Table 24 log command options ..................................................................................... 103
Table 25 log command date specification ..................................................................... 103
Table 26 log command revision specification ............................................................... 103
Table 27 rdiff command options ................................................................................... 104
Table 28 relese command option................................................................................... 104
Table 29 release command output................................................................................. 105
Table 30 remove command options .............................................................................. 105
Table 31 rtag command options .................................................................................... 105
Table 32 status command options ................................................................................. 105
Table 33 tag command options...................................................................................... 106
Table 34 unedit command options ................................................................................ 106
Table 35 update command options................................................................................ 107
Table 36 update command output ................................................................................. 107
Table 37 watch command options................................................................................. 107
Table 38 watch command actions ................................................................................. 108
Table 39 watchers command options ............................................................................ 108
Table 40 keyword substitution flags.............................................................................. 108
Table 41 admin command options ................................................................................ 109
Table 42 Data Formats .................................................................................................. 110

vi

Contents

Table 43 Other Date Formats ........................................................................................ 111
Table 44 Alternate Command Names ........................................................................... 111
Table 45 modules file options ....................................................................................... 113
Table 46 commitinfo file options .................................................................................. 114
Table 47 loginfo file options ......................................................................................... 114
Table 48 verifymsg file options..................................................................................... 114

Figures
Figure 1 Some Possible CVS Configurations.................................................................... 9
Figure 2 Some Possible CVS Configurations.................................................................. 10
Figure 3 Creating a Branch ............................................................................................. 59

Screenshots
Screenshot 1 The newly initialised repository................................................................. 23
Screenshot 2 Checking out a module .............................................................................. 44
Screenshot 3 Checking out a subdirectory with a regular module................................... 45
Screenshot 4 Checking out a subdirectory with an alias module .................................... 45
Screenshot 5 The CVSup GUI ........................................................................................ 64
Screenshot 6 The WinCVS GUI...................................................................................... 68
Screenshot 7 The gcvs GUI............................................................................................. 68
Screenshot 8 The cervisia GUI........................................................................................ 69
Screenshot 9 The TortoiseCVS GUI ............................................................................... 70
Screenshot 10 the CVSIn add-in toolbar for Visual Studio............................................. 70
Screenshot 11 The LinCVS GUI..................................................................................... 71
Screenshot 12 Cvsmenu adds CVS functions to vim ...................................................... 71
Screenshot 13 The gvim plugin Displays the CVS menu................................................ 72
Screenshot 14 The Display from CVSgraph ................................................................... 78
Screenshot 15 The WinCVS Graphical Display.............................................................. 78
Screenshot 16 The CSDiff Diff Format Display ............................................................. 80
Screenshot 17 CSDiff Handles MS Word Files .............................................................. 80
Screenshot 18 The WinMerge Display............................................................................ 81
Screenshot 19 xxdiff shows the differences reported by a standard diff program........... 81
Screenshot 20 The CVStrac Problem Ticket ................................................................... 86
Screenshot 21 CVStrac displays the changes made to a file ........................................... 86
Screenshot 22 Part of Bugzilla's Problem Report............................................................ 87
Screenshot 23 Bugzilla's Query Form ............................................................................. 88

vii

Introduction

0
Introduction
Various organisations have very different ideas about configuration management, and
the tools used to ensure a reliable and reproducible development process. Sophisticated
configuration management tools can cost upwards of £50,000, require ongoing support,
and are probably only accessible to the largest organisations. Although the capabilities of
these tools ease the job of a configuration manager and the developers, there is still a
level of organisation necessary to support the CM process. Undoubtedly, in a
development environment, the disciplines of CM can lead to increased efficiency and
reduced costs. With CVS, an open source product, these disciplines can be implemented
by any size of organisation.
Source code control systems have been common as part of a Unix system from very
early days, starting with SCCS (Source Code Control System), and later RCS (Revision
Control System).
SCCS, was initially developed in 1972 by Marc Rochkind at Bell Telephone
Laboratories, and RCS by Walter F. Tichy at Purdue University in the 1980s. These
systems are still in use in various guises. Both of these are very conservative in their
behaviour, avoiding the problems of concurrent update of files by explicitly locking a
file for the exclusive use of a single developer. CVS on the other hand provides for
simultaneous update of a file by many users, and relies on being able to merge the
changes back into a single file. Although this is not always possible, because of the
normal ways of organising the writing and debugging of code where it is unlikely for
more than one developer to be working on the same section of code, the occasions when
manual intervention is required to merge changes is relatively rare, and generally does
not prove a problem.

1


The original version of CVS was a set of shell scripts which relied on RCS, written by
Dick Grune in 1985. Later these scripts were converted into C by Brian Berliner. Since
then the C version has been taken over by GNU, and the system no longer relies on RCS,
although the RCS file format is still used.
Since the program became open source, many contributors have provided additional
software to enhance CVS.

Typographical Conventions
<entityname> is used to indicate a generic term such as a filename
[] is used to indicate optional arguments
| is used where alternative arguments are possible
Fixed pitch is used in examples of computer output
Fixed Bold is used for commands typed by the user
denotes the command is continued on the next line
# is the Unix prompt character

Glossary
branch A parallel development code stream, originating in a certain revision
of the trunk or another branch.
checkin The process of returning changes made by a developer in his local
work area to the repository.
commit
checkout The process of obtaining a working copy of one or more files and
directories from the repository and placing it in the user’s work area.
conflict A situation found during a merge, where two or more changes to a file
cannot be resolved automatically, and manual intervention to resolve
the conflict is required.
head
tip The highest revision in the trunk or on a branch. By default this
revision will be returned on checkout.
merge The process of integrating changes to the code made by an individual
developer back into the repository. This can lead to the detection of
conflicts which must be dealt with manually.
repository The central store of the project code which holds all the information
required to recreate all the revisions which have existed. This may be
used to refer to the complete repository, the repository for a single
project, or the archive file of a single file.
revision CVS uses the word revision, rather than version (which is often used to
denote a release of a software product. It refers to individual

2

Introduction

committed files, and each revision is denoted by a number such as 1.2,
or for more complex situations, where branching has been performed
1.2.2.5.
sandbox,
work area The local directory structure where a developer modifies copies of the
code held in the repository.
trunk The main development code stream.

3

Planning for Installation

1
Configuration
CVS can be configured on many machine architectures and systems, and is suitable for
all sizes of project, from the single developer to a development requiring hundreds of
contributors. The machine architectures in use will determine to some extent how CVS is
configured, but there are always several alternatives to consider. CVS is available in
both client/server and local forms for both Unix and Windows. Thus it is possible to run
the system using a local client, allowing only one user under Windows, but many on
Unix, using a local client accessing a networked shared filesystem, or in full client-
server mode with several protocols available for communication. There is no restriction
on mixing Unix and Windows systems, so a popular configuration would be to use
Windows workstations accessing data on a Unix server over the network. Traditionally
the CVS client was a command-line interface, and at least the configuration manager
will still need to use this from time to time, but now graphical client software is available
for both Unix and Windows, and it is likely that this will be a better choice for
developers.
There are many possibilities for configuring CVS, here are some examples:
Single user on a Windows System running CVS in local mode
Single/Multiple users on a Unix system running CVS in local mode
Multiple Windows systems accessing a network share on a Windows NT/200
server in local mode

5


Multiple Windows users accessing a network share on a Unix system serviced
by SAMBA in local mode
Multiple Unix systems accessing an NFS share on a Unix Server in local mode
Multiple Unix systems accessing a Unix server through one of CVS’s remote
protocols in client/server mode
Multiple Windows systems accessing a Unix system through one of CVS’s
remote protocols in client server mode
Multiple Windows systems accessing a Windows NT/200 system using a
remote communications protocol in client/server mode
Additionally, in many of these configurations, workstations could be a mixture of
Windows and Unix clients.
Because there is a defined protocol for CVS client/server communication, it should be
possible to mix any client with any server, although the Windows NT server requires its
own client, as commands have been added to allow users to be set up.
There are two main considerations in choosing the method of using CVS, the
organisation of the developers, and of course their number and locations, and the
requirements for security. Where more than a few developers are involved, or developers
use windows workstations supporting a single user, the organisation is much more likely
to favour a client/server setup than a local one. Where development (or even
distribution) occurs across multiple sites, or over a large multipurpose network, some
attention must be given to the communication protocols used between clients and server.
The alternatives available are:
Remote Shell Command
Although this may be the simplest system to set up, it offers little security, and
almost certainly will be blocked by a firewall. No explicit login verification is
required.
Secure Shell Command
Offers public/private key pair validation, and encryption, and can easily be used
through firewalls.
Password Server
Where some level of security validation is required, the CVS system can run
with a password server, but the passwords are not effectively encoded therefore
the security offered is weak. For this reason many installations encourage the
use of a different set of passwords from the developers’ main login passwords.
GSSAPI
A generic security protocol interfacing to network security systems such as
Kerberos 5
Kerberos

6


A protocol allowing the use of Kerberos 4 (which does not support GSSAPI)
for authentication.
The diagrams give some idea of the configurations possible with local and client/server
CVS.

Sizing
Estimating the amount of disk space required for a development is never an easy task. If
you are converting an existing project to CVS, then the initial code size is known.
Depending on the amount of further development envisaged, it is probably wise to allow
up to three times the existing code size for future expansion of text files, as only
incremental changes are added to the files. Binary files, however can consume large
amounts of space, as each revision must be stored in its entirety, so its size and the
number of revisions it will go through must be estimated. With, say, a word processing
format design document it may be evident how many versions will be required over the
life of the project, but in many cases one can only guess, and obviously it is best to
overestimate the disk space required.
For configurations where CVS runs locally, each developer using the server will also
need a working directory, sufficiently large to hold the section of code on which he is
currently working, plus any other components of the project required to compile and test.
On a Unix system space can be conserved by using links to parts of the code or libraries
not immediately being worked on, but this is not possible on Windows systems. Where
CVS is operating in client/server mode no space is required on the server for the client
systems.
As far as the memory (physical+swap space) is concerned, CVS requires up to 2MB for
each concurrent checkout, and up to ten times the size of a file for checkin. Multiplying
these figures by the
number of concurrent activities expected should give an indication of the memory
requirement, although this is usually quite modest.

Code Organisation
Some thought needs to be given to how the code will be arranged in the repository.
When a developer checks out a set of files, it should be easy for him to retrieve a
complete set of files for compilation and test, but if the code is organised so that he
needs to check out more than the minimum amount required this will give rise to extra
network traffic, further requirements for client-side disk space, and increase the
likelihood of conflicts being reported on checkin.

Times and Timezones
Since CVS determines whether a file has been updated by comparing its modification
time with the time at which it was checked out, if the clocks on client and server differ it

7


is possible to obtain false results. Consideration should be given to having the hosts
synchronise their clocks by access to a time server. Projects distributed across timezones
are correctly catered for by Unix systems, but there are some issues with Windows
clients.

8


Single Windows User with Local Repository

Single or Multiple Unix Users with Local Repository

Shared Network Drive

Windows NT Server or Unix Server
Running SAMBA

Multiple Windows Users in Local Mode using a Network Shared Drive

Figure 1 Some Possible CVS Configurations

9


NFS Shared Network
Drive

Unix File Server

Multiple Unix Systems in Local Mode Using a Network Shared Drive

Pserver or SSH
Communication

Pserver
Communication

Internet

SSH or Pserver over
VPN Communication

Remote repository with mixed clients distributed locally and remotely

Figure 2 Some Possible CVS Configurations

10

Installation

2
Installation
Unix Systems
CVS is available in several flavours, and as source for compilation where no binary
exists for the required architecture. The program is available from
http://www.cvshome.org/downloads.html, and the main selection of machines supported
is shown in Table 1, although there are various other ports of CVS, and the souce code is
available for compilation on other architectures.

Platform Architecture
Win32 x86
Linux x86
Unix: IBM AIX 4.3 RS/6000
Unix: BSDI BSD/OS 4.0.1 x86
Unix: HP HP-UX B.10.20 A HP 9000/820
Unix: Sun SunOS 5.6 (aka Solaris 2.6) SPARC
Unix: SGI IRIX 6.5 MIPS R12000
Table 1 CVS Supported Platforms

Common Steps
The files are downloaded as tar or gnu-zipped tarfiles and should be expanded in a
directory under the source tree:

11


#cd /usr/src/cvs
#tar –xvzf cvs-1.11.1p1.tar.gz
Moving into the cvs directory the system is built with the commands:

#cd cvs-1.11.1p1
#./configure
#make
#make install
This will install the CVS binaries in the default location for the architecture of the
machine used, and to use CVS in local mode, the only additional step is to make sure the
CVS binary location is in the path.

Client/Server Mode
Depending on the type of communication chosen between client and server, various
switches may be needed to configure the makefiles for compilation. To enable GSSAPI
it is necessary to run configure with:

#./configure –with-gssapi –enable-encryption
and to enable Kerberos 4:

#./configure –with-krb4 –enable-encryption
In both these cases, the generation of the encrypting code is optional. CVS in
client/server mode is usually started up with inetd, and the following changes are
required in /etc/services and /etc/inetd.conf:

/etc/services
cvspserver 2401/tcp

/etc/inetd.conf
cvspserver stream tcp nowait root /usr/bin/cvs cvs –f
–allow-root=/usr/cvsroot pserver
or, with tcpwrappers in use:

cvspserver stream tcp nowait root /usr/sbin/tcpd
/usr/bin/cvs –allow-root=/usr/cvsroot pserver
(Note that the command may have to be typed on a single line, without the continuation
character)
The –f switch disables the interpretation of ~/.cvsrc, which may contain options
inappropriate for the CVS program running as a daemon, and the allow-root switch
restrict access to clients requesting this base directory for the repository. Multiple
instances of the allow-root switch are allowed, but some implementations of inetd
restrict the length of the command which can be entered on the command line. In this

12

Installation

case it is possible to cause inetd to invoke a script containing the desired command. 2401
is the default port for CVS operating in pserver mode.
Where xinetd is used to start up network services the following must be entered into the
file /etc/xinetd.d/cvspserver:

service cvspserver
{
port = 2401
socket_type = stream
protocol = tcp
wait = no
user = root
passenv = PATH
server = /usr/bin/cvs
server_args = -f –allow-root=/usr/cvsroot pserver
}
For the kserver connection method pserver should be replaced in the above with kserver
for Kerberos 4, and the port number for kserver is by default 1999.
In order to test the installation the location of the CVS repository needs to be set in the
environment variable CVSROOT, and this may be done in the shell’s initialisation
script. For systems running CVS on the local host, only the location of the repository
need be specified:
For csh:
setenv CVSROOT /usr/cvs
For bash:
export CVSROOT=/usr/cvs
In client/server mode a connection string is specified of the form:
:<connection method>:<username>@<hostname>:<repository path>
For example:

:pserver:cvsuser@cvshost:/usr/local/cvs

Troubleshooting
Most problems in setting up CVS will be found with client/server systems, and may be
caused by a failure to start up the server, incorrect environment settings, or a failure to
authenticate the user. To determine the cause it is possible to log the communication
between client and server. By setting the environment variable CVS_CLIENT_LOG on
the client machine all messages sent by the client will be logged in
$CVS_CLIENT_LOG.in, and messages received from the server in the corresponding
.out file. An example of a log file is shown below.

13


ok
M Checking in ChangeLog;
M /usr/local/cvs/cvssources/doc/ChangeLog,v <-- ChangeLog
M new revision: 1.7; previous revision: 1.6
M done
Mode u=rw,g=r,o=r
Checked-in ./
/usr/local/cvs/cvssources/doc/ChangeLog
/ChangeLog/1.7///
M Checking in cvs.texinfo;
M /usr/local/cvs/cvssources/doc/cvs.texinfo,v <-- cvs.texinfo
M new revision: 1.4; previous revision: 1.3
M done
Mode u=rw,g=r,o=r
Checked-in ./

Windows Systems
www.cvshome.org provides a Windows CVS system which can run as a client or locally.
A windows server system (CVSNT) is available from www.cvsnt.org. A CVS
client/local system also forms part of the Cygwin distribution of Unix tools for Windows
(www.cygwin.com).
Installation of the client and local systems is simply a matter of extracting the CVS
binary from the zip file and putting it in a suitable directory in the path.
The Windows NT CVS server runs on both Windows NT and Windows 2000 as a
service. After unzipping the file, executing the binary starts the installation program,
which runs through the setup.
There are a few differences between the organisation of programs and files from the
Unix setup, and it is useful to avoid spaces in path and filenames.
The directory to be used for temporary file by CVS must be accessible with full control
to all users. Because of the way Windows handles users’ personal files, the files must be
located in an area where all users can see them, and not in any special folders personal to
a user. It is suggested that the repository and temporary directory are created within the
disk root directory, and that the program is not installed in the Program Files directory,
as it contains a space in the path.
The installation of CVSNT often cannot set the path correctly to include the CVSNT
program, so this may have to be added manually in the system section of the
environment variables settings.
CVSNT is controlled by a control panel applet, and this must be used to specify the
location of the repository and temporary directories, to start and stop the service and to
select options. The admin files of the repository may also be created through the applet.
CVSNT and the CVS client installed with it support a further system of client/server
communication, known as ntserver. By default a CVSROOT string such as:

14

Installation

:ntserver:<user>@<hostname>:/cvs
will connect using this protocol. CVSNT also supports pserver and GSSAPI
connections, using the connect strings:
:pserver:<user>@<hostname>:/cvs
:sspi:<user>@<hostname>:/cvs
The ntserver and SSPI connection methods both use the system authentication to validate
users, while pserver works in the normal way using the passwd file. A further command
has been added to CVSNT to manage users and passwords, which can only be used by
users with administrative rights:
cvs passwd [options] <username>

Option Description
-a Add user
-D <domain> Use the domain password
-R Remove alias to user
-r <username> Alias the username to this real account
-x Disable User
-X Delete User

Table 2 CVSNT passwd options

CVSNT Differences
CVSNT supports unicode in the UCS-2 and UTF-8 forms. UCS-2 files should be marked
with the option –ku, as they are translated to UTF-8 on commit.
The admin –l command for exclusive locks is not supported, but some support for such
locks is provided by the edit –c and commit –c options.
Users of other domains may login by specifying the domain in the connect string:
:<connection method>:<domain><username>@<hostname>:<repository path>

15

Connection and Authentication

3
Where a central repository is used from remote client machines, some thought must be
given to security in order to maintain both confidentiality and the integrity of the code
base. This has always been a relatively poorly supported aspect of CVS, the original
pserver communication system transmitting passwords in almost clear text, and offering
no encryption of data during transmission.

Password Server
The CVS password server, although only offering weak security and no encryption of
data, can be useful because of it’s ability to provide aliases for usernames, which can be
used to control access to various parts of the repository. Connection is made using a
connect string such as:

cvs –d :pserver:[<username>|<alias>]@<hostname>:
<repository path> <command>
Passwords or aliases are searched for in the passwd file in the CVSROOT directory, and
are held as standard Unix encoded strings. If the user is not found in this file, then an
attempt is made to authenticate the user using the system passwords if SystemAuth is set
to yes in the config file.
Passwords are stored on the client machine in a very simply encoded form and
transmitted in the same manner.

17


Remote Shell
CVS allows the remote shell to be selected to run the CVS program remotely on the
repository host. Connection by this method can be achieved with:

export CVS_RSH=/usr/bin/rsh
export CVS_SERVER=/usr/bin/cvs
cvs –d :ext:<username>@<hostname>:/usr/local/cvs <command>
Permission to run a remote shell must be set up in the .rhosts file of the user’s account on
the remote host, and it may be necessary to set up /etc/hosts.allow and /etc hosts.deny.
This method offers only weak authentication, and no encryption of data during
transmission. The remote shell requires actual usernames registered on the remote host
to be used, and cannot support the aliases available with pserver.

Secure Shell
The pserver connection method is almost always set up to use aliases as passwords, to
avoid compromising the main login password of the users, but this offers very little
security, and all data is transmitted in plain text. An improvement in security can be
obtained by using the secure shell for communication. In this case the ext method of
communication is used, specifying the client program to use for communication as the
secure shell client. A typical connection string would be:

export CVS_RSH=/usr/bin/ssh
export CVS_SERVER=/usr/bin/cvs
cvs –d :ext:cvsuser@oppenheimer:/usr/local/cvs <command>
To set up the secure shell (this example assumes openssh is used), the host machine for
the CVS repository must be running the secure shell daemon, and port 22 must be open.
Since SSH uses a public/private key pair, and all data passed is encrypted, it is safe to
open this port on the firewall. To set up the communication between the client and server
a key pair is generated using ssh-keygen on the client machine:
ssh-keygen –t rsa
the only argument required is the type of keypair to be generated, which here is specified
as a key pair generated using the RSA algorithm, although the length of the key can be
varied between 512 and 2048 bits using the –b switch.
The ssh-keygen dialogue asks for a passphrase which is used in generating the key pair:

ssh-keygen –t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/cvsuser/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in
/home/cvsuser/.ssh/id_rsa.pub.

18


The key fingerprint is:
fc:24:23:dc:06:3f:5c:f4:0b:6d:9b:c5:1e:52:74:b2 cvsuser@bohr
The public key generated here (/home/cvsuser/.ssh/id_rsa.pub) must now be transmitted
to the CVS host, and added to the ~/.ssh/authorized_keys file of the user which will be
used to access CVS. This does not have to be the same user which is used on the client
machine.
At the first attempt to connect with ssh the system will report that the identity of the
remote host cannot be confirmed, and will display the key fingerprint of the host. This
should be verified, and if confirmed the system will add the remote hosts key to the list
of known hosts, and the message will not occur again.
If the environment variable CVS_RSH is set to point to the SSH client, then CVS will
invoke the remote CVS program through an ssh shell. This will normally ask the user
each time for a password, which may become tedious. To overcome this, the client
user’s private key is added to the environment using ssh-agent:

ssh-agent $SHELL
causes a shell to be spawned by ssh-agent, and adding keys with:

ssh-add ~/.ssh/id_rsa
adds the user’s private key to the environment. To confirm the identity of the user, SSH
requests the passphrase used to generate the key. Once the private key is available in the
user’s environment no further requests for passwords will be made when typing cvs
commands.
There are two configuration variables for SSH which may need setting for CVS use. The
configuration file for the SSH client is usually found in /etc/ssh_config, and that for the
server daemon in /etc/shd_config. On the client side the parameter:

FallBackToRsh=no
will prevent the system reverting to the insecure rsh remote shell if the SSH daemon
cannot be contacted.
SSH by default uses low numbered ports for its communication, which may give
problems with some firewalls. Setting:

UsePrivilegedPort=no
in the shd_config file will allow SSH to use high numbered ports, which should
overcome these problems.
Unlike the pserver method of connection, using SSH or rsh the CVS system on the
repositoty host does not have to be set up to run as a server as the program to run on the
remote machine, specified in the CVS_SERVER environment variable, is started by the
remote shell.

19


GSSAPI
GSSAPI (Generic Security Services Application Programming Interface) is a common
API for client/server authentication. It is supported by version 5 and above of Kerberos,
a network authentication protocol designed by MIT, which provides strong
authentication for client/server applications by using secret-key cryptography.
The GSSAPI is handled by the same mechanism as the password server, provided the
system has been built to support the protocol.
Connecting via GSSAPI is achieved by obtaining a ticket with the principal name
specified as cvs/<hostname>, and connecting with the connect string:
:gserver:<username>@<hostname>:<repository path>
Having set up strong authentication, other forms of authentication should be prevented.
This can be achieved by setting SystemAuth=no in the config file, and by creating an
empty passwd file in the CVSROOT directory.
Note that, although the user will be authenticated at login, the message streams are
neither authenticated nor encrypted by default, and it is necessary to specify the global
options –a (authentication) and –x (encryption) if this is required. The .cvsrc file can be
used to set these options as default for each user.

Kerberos 4
The earlier version 4 of Kerberos, which does not support GSSAPI is also supported by
CVS. For this setup the CVS server must be started up by the command:
cvs kserver
and will listen by default on port 1999. The mechanism for authentication is to obtain a
ticket for access to the host machine and to connect with a string of the form:
:kserver:<username>@<hostname>:<repository path>
Again authentication of the message streams and encryption are not enabled by default.

20

The Repository

4
The Repository
The repository comprises a file for each file in the code tree, containing the complete
history of changes made to a file, and allowing any version to be retrieved. These files
bear the same name as the file in the source, but have the suffix ‘,v’ added to the name.
The format of these files follows the syntax used in the earlier code management system
RCS. Although it should never be necessary to edit one of these files directly, it is
interesting to look at the format of the files. Some sections of a typical RCS file are
shown here.
Starting with some general information on the file, the current revision (head) is
recorded, and linked to previous versions with the next command, also recording any
branches. The system works on negative deltas – that is the full text of the current
revision is recorded, together with the actions required to revert to earlier revisions.
Changes are recorded as additions and deletions of lines, a modification to a line always
being recorded as a deletion follwed by an addition.

head 1.6;
access;
symbols
cvssrc-1-0patch:1.4.0.2
cvssrc-1-0:1.4
Import:1.1.1.1
mlc:1.1.1;
locks; strict;
comment @# @;

21


The preamble to the file shows the revision number of the head of the main trunk, in this
case 1.6, and lists the symbolic tags associated with particular revisions of the file. The
access field was used in RCS to specify an access list of users who may update the file,
but this feature is obsolete in CVS and should not be used even though the commands
still exist to update this field. The specification of strict locks (the default) is normal in
CVS, and this requires even the owner of the file to follow the normal checkout/commit
sequence for updating the file. A comment may be added to the file.

1.6
date 2002.11.24.11.20.31; author cvsuser; state Exp;
branches;
next 1.5;

1.5
date 2002.11.23.12.12.50; author cvsuser; state Exp;
branches;
next 1.4;
A section exists for each revision of the file, specifying the revision number, date of last
update and the user updating the file. The state of the file is shown here as experimental.
These records are chained together through the branches and next fields, the next field
giving the previous revision on the current branch or trunk.

1.6
log
@This is a log message
@
text
@
2001-04-28 Derek Price <dprice@@collab.net>

* Makefile.in: Regenerated using AM 1.4e as of today at
18:10 -0400.
* CVSvn.texi: Regenerated.

2001-03-31 Larry Jones <larry.jones@@sdrc.com>

* cvsclient.texi (Dates, Requests): Add rannotate and
rlog.
The text of the current revision at the head of the tree is held in full, making the system
more efficient as the most likely text which a user will retrieve is this version.

1.5
log
@Corrected spelling
@
text
@d6 1
a6 1

22

The Repository

2001-03-30 Larry Jones <larry.jones@@sdrc.com>
@
For each earlier version the deltas are recorded. Here the log message is held, together
with the modifications made. in the text field the fact that 1 line was deleted at line 6
(@d6 1) and that a line was added in the same place (a6 1) together with the text added
is recorded.
The location of the repository is usually defined by the environment variable
CVSROOT, but this may be overridden by the use of the –d switch to CVS, thus
allowing several different repositories to reside on the same server. As developers need
write access to the repository to create lock files, security is a problem. A new repository
can be set up with the command:

#cvs –d <repository root path> init
or, if CVSROOT has been set up with:
#cvs init
Initialising a repository creates the directory tree shown in Screenshot 1.

Screenshot 1 The newly initialised repository

23


The init command creates an empty repository at the location specified, which contains
only the CVS administration files. Most of these files are created read-only, but the
directory CVSROOT, and the files val-tags and history must be writeable by all cvs
users. In fact the CVSROOT directory contains both working copies of the admin files,
and a repository of them CVS stores the changes made to all files in files with the suffix
,v. Thus for almost all of the files there is an archive file such as taginfo,v together with
the working copy of the file named taginfo. Having created the repository, it is necessary
to change the ownership of the files so that users do not need root permissions. A useful
security policy as a minimum should allow for a group of administrators, and one or
more groups of users. Where more than one group of developers are working on
different projects, it is advisable to grant write permissions in the repositories through
group membership, so that the different groups can only access the files they are
working on.
An alternative to using groups when using the pserver authentication method is to set up
users with an alias, which is also useful to protect users’ logon passwords where weak
security is used to transfer passwords. An example is given in the section describing the
passwd file.
Several of the admin files control how CVS works, and there are other files which may
be added to the directory to modify the behaviour of CVS.

checkoutlist
CVS treats the admin files in the same way as all other files in the repository. When an
admin file is edited it should be done by checking the file out, editing it, and committing
it to the repository. CVS however needs a current working copy of the admin files, so it
then automatically extracts the latest version of the files. Where other files have been
added, such as a password file, these files need to be listed in the checkoutlist file so that
CVS treats them as admin files. The format is the filename, followed by an error
message to display if the file cannot be checked out.

commitinfo
When a file is committed (checked back into the repository) it is possible to check or
modify the file by running a script or program. For example a C “beautifier” could be
made to run on C source code files, or checks could be made that the file contained
certain information fields. The commitinfo file contains lines with value pairs
representing a normal expression to match the directory to which the change is being
committed, and the path to a program to run if the match is true. In addition the patterns
ALL and DEFAULT can be used to run a program for all files (in addition to actions
specified by a pattern match), or any file for which a specific match is not found.
The specified program is run with arguments specifying the repository directory and the
list of files being committed. If the program does not return a zero exit code the commit
is aborted.

24

The Repository

config
Several parameters controlling the behaviour of CVS can be specified in the config file.
SystemAuth=[yes|no]
Specifies whether CVS pserver should attempt to authorise a user using the system user
database if the user cannot be authorised by the CVSROOT/passwd file.
LockDir=<path>
For security reasons it may be desirable to cause lock files to be written to another
directory so that users do not need to have write access to the repository.
TopLevelAdmin=[yes|no]
This causes an additional directory CVS to be created at the top level in a developer’s
work area, recording the location in the repository of the checked out modules. It is
useful when more than one module is being worked on as it removes the need for the
user to specify the location in the repository.
LogHistory=[all|option string]
Selects the messages which are logged in the history file. The options are:
T rtag
O checkout
F release
E export
W working copy deleted during update
G merge required and successfully completed
C merge required, but conflicts detected
M file modified
A file added
R file removed
An example of usage is:
LogHistory=TMAR
ReReadLogAfterVerify=[always|stat]
This parameter causes the log entry to be reread after running the verifymsg script,
which may be used to modify the log message. The parameters cause this to be
performed always, or only on status change.

cvsignore
Contains a list of files, specified by patterns, which CVS should ignore. The patterns are
shell style patterns and not regular expressions, thus usually only the wild character “?”
and wildcard “*” are used. No comments are allowed in this file. This file is useful and
will reduce the redundant information written to the log file. When compilations are
performed in the working directory, for example a large number of intermediate files
will be generated which are not part of the code repository. On a commit CVS will
report the existence of each of these files, unless they are specified in cvsignore.

25


cvswrappers
This file allows default options for CVS file operations to be specified. The lines in this
file contain a shell style pattern defining a file type followed by the keyword substitution
switch –k and the options required, or the update method switch –m. followed by the
keywords MERGE or COPY.
An example of keyword substitution is:
*.doc –k ‘b’
which will cause all files ending with the extension doc to be treated as binary files,
preventing keyword expansion and newline conversion. if –m COPY is given, then no
attempt will be made to merge files where a conflict exists, rather the developer must
choose one file or the other, or resolve the conflict manually.
The switches –t and –f may be used to specify to and from filters respectively.

history
This file, if it exists, is used to record activity against the repository, which may be
displayed with the CVS history command. the recording of activity may be turned off by
removing this file.

loginfo
The loginfo file follows the format of the commitinfo file, including the special matching
strings ALL and DEFAULT. This file is used to process commit log messages, any
program specified receiving the log message as an argument, and the special values s, V
and v representing the filename, pre-commit version and post-commit version if
specified. These arguments are specified by using the % character, for example %s. If
multiple parameters are to be passed, they must be specified in curly brackets. Thus the
loginfo line:
ANY mail –s %{sVv} developers@hostname
will present sendmail with arguments:
/usr/local/cvs/project file1,1.6,1.7 file2,4.1,4.2 …
the final three arguments being repeated for each file in the log message.

modules
The modules file allows parts of the code repository to be referred to by more simple
names. The file contains lines of the form:
<module name> <options> <directory> <files> …
Three types of command are available:
Alias Modules

26

The Repository

This is the simplest form of command and simply refers to the set of files defined by the
directory by a symbolic name. The command:
drivers –a serial floppy
will cause a checkout or commit using the alias drivers to operate on the files in the
directories serial and floppy. Any intermediate directories in the specified paths are
processed. An alias module may exclude directories by preceding their names with the
“!” character.
Regular Modules
The command:
<module name> [options] <directory> [files]
will cause all operations on <module name> to process the files and directories
specified, but any intermediate directories in the path specified will be ignored, and the
files will be stored under the directory <module name>. If files are specified, only those
files listed will be operated on.
Modules can refer to other modules by preceding the module name with an ampersand:
<module name> [options] &<module1> &<module2> …
will process CVS commands referring to <module name> and produce a tree of the
specified modules under the directory <module name>.
Options available with the last two constructs are:
-d <name> override the default working directory with name
-e <program> run this program when files are exported from the module
-i <program> > run this program when files are committed to the module
-t <program> > run this program when files are tagged in the module with rtag (but not
tag)
-u <program> > run this program when files are updated in the module’s top-level
directory
-s <status> Assign a status to the module
-l causes the top level only of a directory to be acted on.
The e, and i options pass the module name to the program as an argument, while the u
and i options passes the full path to the module within the repository. The t option passes
both the module name and the symbolic tag

notify
CVS provides a facility to watch the actions performed on a file or set of files. When an
operation is taken on a watched file, the notify file is consulted to decide on the action to
take. Each line in the notify file contains a regular expression to match a filename
followed by a command to execute. In the command the special variable %s specifies the
user watching the file. The system then looks up the value in the users file. The default
file contains the command:
ALL mail %s –s “CVS notification”

27


(although it is commented out).

rcsinfo
When a commit or import is actioned, CVS uses this file to determine the log message
editor template to use. Each line in the file is a regular expression to match the module
directory, followed by the file to use as a template. the patterns ALL and DEFAULT are
supported. The message editor template is a text prototype which is displayed initially in
the log message entry box.

taginfo
When tag or rtag commands are executed, CVS searches this file for a pattern match on
the module directory, and executes the selected program or script. The special pattern
ALL is also recognised. The program is called with the tag, the operation being
performed (add for tag, del for tag –d and mov for tag –f), the module directory, and the
filename and version number for each file being tagged. The operation is aborted if a
non-zero return code is given.

verifymsg
This file determines whether log messages should be validated. The special pattern
DEFAULT is supported, but ALL is not. The file determines the script or program which
checks for the correct content of the log message. The program is called with a full path
to a file containing the full log message. An example is given in the CVS distribution, of
a script which checks that a Bug ID has been entered in the correct format. If the script
exits with a non-zero return code the operation is aborted.

#!/bin/sh
#
# bugid.verify filename
#
# Verify that the log message contains a valid bugid
# on the first line.
#
if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
exit 0
else
echo "No BugId found."
exit 1
fi

passwd (not created by default)
The security offered by CVS, particularly when running the password server, is rather
weak, and to avoid compromising the users’ main login passwords it is common to
specify passwords solely for use with CVS. The format of the passwd fle is similar to a

28

The Repository

Unix password file, each entry specifying the username and password separated by
colons. A further argument allows an alias for the user to be specified for the pserver
authentication method, so many users in a group may run with a single CVS user
identity. An example file would be:

anonymous:
alice:12aswQHN5Fd
edward:4ewHjf409jHt:cvsuser
william:7DFSe4l67G:cvsuser
In this example the user anonymous can access the repository without using a password
(he should obviously be restricted to read-only access), while the users alice, edward and
william be allowed access via their passwords, but william and edward will both access
the repository with the identity cvsuser. Passwords are encrypted in the standard Unix
way, and may be pasted from a password file, or generated by a utility such as htpasswd.
The pserver alias can also be used to allow groups of developers access only to the
project on which they are working. In the case below, two groups of developers would
login to CVS by using the alias set up in the password file. Here bob and joe can access
project1, as the repository is set up to allow access only to this alias, while wiliam and
mary can only login as project2 for access to a separate project. The users project1 and
project2 must exist on the repository host. Although the alias is now used to login to cvs,
actions are still recorded against the actual username, so the development can still be
traced accurately.

bob:2Q3c1Z:project1
joe:A2cvER4:project1
william:UYT65No:project2
mary:5FRE3scD:project2

readers (not created by default)
This file can restrict certain users to read-only access of the repository. The format of the
file is a list of usernames, listed one per line.

users (not created by default)
The users file maps user names to their email addresses for notification messages, when
their email location is not the server running CVS.

writers (not created by default)
Users listed in this file, if it exists will be granted read/write access to the repository. If,
however a user is also listed in the readers file, the access will be restricted to read-only.
If the writers file exists, any user not listed in it will be restricted to read access, even
though they are not listed in the readers file.

29


editinfo
This file may exist in the repository, but is now obsolete.

Modifying the Repository Files
The files in CVSROOT, with a few exceptions, should only be modified using CVS
itself. The CVSROOT directory is different from other repository directories in that it
contains the archive files and also a working copy of the files. When a commit of the
CVSROOT module is performed, CVS also checks out a new working copy of the
checked-in files. The message:
cvs server Rebuilding administrative files
is displayed. The files passwd, users, readers and writers may be modified initially
directly, then added to the repository. They should be included in the administrative file
list by adding them to the checkoutlist file.

How CVS Uses the CVSROOT Files
When running locally CVS will always have immediate access to the working copy of
these files, but the most common use of CVS in all but the smallest developments will be
in client/server mode. This means that various items of data stored in these
administrative files need to be accessible on the client system. CVS achieves this by
creating a directory named CVS in each module that is checked out into the user’s
working area. It is important to understand this, as some of the information is simply
copied when a module is checked out, and if changed subsequently, will not change on
the client system until the module is checked out again. The CVS directory contains
several files, the most important ones being:

Base
If a file is being watched the original copy of the file is stored in Base, so that an unedit
command can restore the original file in the user’s working directory, even if the client
cannot communicate with the server.

Baserev
Holds the revision number for the files stored in base in the format:
B<filename>/<revision>/<reserved field>
The file Baserev,tmp may also appear during update of the Baserev file.

Entries
This file contains a list of the files and subdirectories in the working directory. there are
two types of entry, those starting with the ‘/’ character which specify a file, and entries

30

The Repository

starting with D which specify subdirectories. A single entry starting with D and
containing no information indicates that the working directory contains no
subdirectories.
The format of a file entry is:

/name/revision/timestamp[+conflict]/options/tagdate
The optional conflict field indicates the time when the file was written with a conflict
marker. The options field records any sticky options associated with the file, for example
that the file is treated as a binary file, and the tagdate gives the sticky date or tag name
preceded by D or T.
Although the file is maintained automatically by CVS the contents can be useful to
identify the last revisions of files, and whether a file has been updated since checkout.

Entries.Log
This provides a method of modifying the information in the Entries file without
modifying it directly. The system, whenever it refers to the Entries file also takes
account of any updates in the Entries.Log file. The format of commands in the file is the
character A (for add) or R (for remove) followed by a space and a line in the same
format as the Entries file. By convention a program processing the Enries file should
read the file, check for the existence of Entries.Log, apply the changes and delete
Entries.Log.

Entries.Backup
A temporary file used when updating the Entries file. The system writes the new Entries
file to Entries.Backup, then deletes the Entries file and renames Entries.Backup.

Entries.Static
If this file exists it indicates that only parrt of a module or subdirectory was checked out.
CVS cannot create files in this directory, as it cannot check for the existence of the file in
the repository. Updating the working directory to include all the files causes the file to be
deleted.

Notify
Notify stores notifications required by watches which have not yet been sent to the
server. The file Notify.tmp may also appear during update of this file.

Root
Contains the location of the root of the CVS repository.

31


Repository
Contains the directory within the repository from which the current directory was
checked out. The path may be absolute, or relative to the repository root.

Checkin.prog Update.prog
A local copy of the names of the programs to run on checkin and update.

Tag
Contains any sticky tags or dates for the directory in question. Branch tags are marked
with a T, non-branch tags with an N, and dates with a D. where individual files have
sticky tags these override the tags in the Tag file.

Template
The template for log messages.

Hanging Locks
Although CVS normally does not lock files on checkout, allowing multiple users to work
on a file simultaneously, it does lock the files in order to ensure the atomicity of
commands. It does this by placing files with names starting with #cvs.rfl, #cvs.wfl and
#cvs.lock (for read lock, write lock and a lock of the whole directory respectively) in the
directories being operated on. When CVS has a lock, some operations may have to wait.
CVS will retry the operation every 30 seconds, until it succeeds, but a power failure or
other system crash may leave locks present in the repository, and these may have to be
removed by hand.

32

The User Environment

5
Whether CVS is run locally or in one of the client/server modes, there are some
requirements for the user environment, and further enhancements which can make use of
CVS easier. Each user requires a working directory (frequently called a sandbox in CVS
terms) to which the modules under development may be checked out. Although any
directory could be used, there are some files which can be set up in the sandbox to
control the operation of CVS.

.cvsignore
This files specifies files to be ignored by CVS, and is normally used to ignore the results
of compilation such as object and any other intermediate files. Although these files may
be specified in the CVSROOT directory of the repository, they can also be specified in
the user’s home directory, and in individual directories in the working area. The
specifications in .cvsignore in the home directory are global, but .cvsignore files in
individual directories are only valid for the directory containing the .cvsignore file.
These definitions are added to definitions in the repository and the environment variable
CVSIGNORE. Placing a ‘!’ character in a .cvsignore file resets the file list, and can be
useful for storing a file of a type which is normally ignored.

.cvswrappers
May contain sticky options for files which are not specified in the repository
cvswrappers file.

33


Environment Variables
The environment in which the CVS client runs can be set up to simplify the interface
with CVS. The following are the principal variables relevant to the client. A complete
list of environment variables for both client and server is given in Appendix B

CVSROOT
This defines the location of the root of the repository in the form of a connect string such
as:

:pserver:username@hostname:<repository root directory>
The possible connection methods are shown in Table 3.

Connection Method Description
local Use cvs in local mode
pserver Password server mode
gserver GSSAPI
kserver Kerberos 4
fork Emulate client/server in local mode
server Server accessed by internal rsh program
(only available in some implementations)
ext Server accessed by rsh or ssh

Table 3 Connection Methods
Although setting up this variable saves typing, the CVS system records the location of
the repository when a module is checked out, so the string normally is only needed once,
after which it is supplied automatically if not overridden.

CVSEDITOR
This specifies the editor to be used for recording log messages during the commit
operation. It overrides the EDITOR variable, which is used if CVSEDITOR is not set.

CVS_RSH
The program used to connect to CVS when using the ext connection mode is specified
by this variable. Usually it will be rsh or ssh.

CVS_SERVER
When connecting with the ext, server or fork methods this specifies the remote program
to run, together with any arguments. The default is cvs.

34


CVS_PASSFILE
After a successful verification of the user by the server, the username, connected host,
repository and password are recorded for future transactions until logout, when the
information is deleted. The passwords are weakly encrypted. This data is stored by
default in $HOME/.cvspass, but this environment variable may be used to change the
location.

~/.cvsrc
Default options for CVS commands may be specified in the .cshrc file in the user’s home
directory. The format of this file is a CVS command, followed by switches which are
prepended to the list of switches supplied on the command line. Note that the full name
of the command is searched for, even if the command is invoked using an abbreviated
form. The file might contain lines such as:
log –N
update –pD
Global options to cvs may be specified using cvs as the command:
cvs –q
The –f switch to cvs will prevent the file .cvsrc from being read, thus a command can be
executed without the default options if required.

35

Format of CVS Commands

6
Format of CVS Commands
The general format of a CVS command is:
cvs [global options] command [command options] [arguments]
The global options are valid for almost all commands, such as the –n switch which
causes CVS to go through the motions of executing the command, but without
modifying any files. The command options vary in their action for each command, and
the commands take different types and numbers of arguments.
The status of the action requested from CVS may be tested by examining the exit code
returned. A zero indicates success, while any other number indicates failure.

Revisions
Each change to a file committed to the repository is identified by a revision number,
which is in the form of an even number of numbers separated by dots. Valid examples
are 1.1, 4,6, 2.1.1.5. Generally a new file added to the repository starts off with revision
1.1, but if higher revision numbers exist, the first number will be set at the highest first
digit of a revision number in that directory. Branches are identified by having further
pairs of digits appended to the trunk revision number. Revision number can be set by the
user on commit operations, and the CVS system updates revision numbers automatically
by incrementing the rightmost digit. In general the revision number of a file is usually
ignored, tags being used to identify sets of files which form a release or other important
milestone.

37


Tags
Sets of files which form a release are tagged with a symbolic label, and can be retrieved
or exported by use of this label. In fact there are two tag types available, a vendor tag
and a release tag. Multiple tags can be assigned to the same version of a file.
Two tags are predefined, and have a special meaning, BASE and HEAD, and are
reserved for CVS use.
BASE refers to the revision on the current branch which was last checked out, updated,
or committed. Until the file is modified BASE is the committed revision matching it
HEAD refers to the latest revision on the current branch in the Repository

38

Setting up the Repository

7
In many cases there will be a significant code base to be stored under CVS, and its
structure will already have been determined and build systems orientated around this
structure. In this case it is sensible to import the code directly into a CVS repository.
However it is worthwhile first examining the types of file involved to determine whether
special treatment of some files is required. The cvswrappers file should be set up to deal
with any binary files, or any files which cannot have keywords expanded or any line end
translations made. For existing code the import command is used to load the repository:
cvs import –m “Initial import” <module name> <vendor tag> <release tag>
will load the current directory into the repository as <module name>. By default cvs
works recursively, so all subdirectories will also be imported. This behaviour can be
modified by the –R and –l switches, which turn recursion on and off respectively. In the
command above the –m switch specifies the log message, which prevents the log
message editor from being run, and the vendor and release tags are probably not needed
in this case, but must be specified.
An import is always made to the vendor branch, which by default is the branch 1.1.1,
and the vendor tag specified is added to the branch, as is the release tag. If a subsequent
import command specifies a new vendor tag this will merely be added to the same
default branch – a new branch will not be created. CVS is designed to support only a
single vendor branch, although there is a method of introducing multiple vendor
branches manually (see Revisions, Releases and Branches).
When a file is retrieved from the repository after an import the system looks for the head
revision, which will at first be located in the vendor branch, and will be checked out with

39


the revision number 1.1.1.1. When the modified file is written back to the repository it
will be stored in the main trunk and receive the revision number 1.1. Subsequent
checkouts will retrieve the latest revision of a file, from the trunk if it has been modified,
or from the vendor branch if it is still in its imported state.

To check what will happen when this command is run, but take no action on the
repository the global flag –n can be used. This is useful to see whether CVS detects any
errors, and to check what files are imported. A section of the output from the admin
command is shown below:

cvsdmin@oppenheimer:/usr/src/cvs/cvs-1.11.1p1> cvs -n import -m "Import" cvssources
mlc Import
N cvssources/FAQ
N cvssources/BUGS
N cvssources/NEWS
N cvssources/TODO
N cvssources/depcomp
I cvssources/Makefile
N cvssources/TESTS
N cvssources/aclocal.m4
I cvssources/config.status
N cvssources/cvs.spec.in
N cvssources/COPYING.LIB
N cvssources/DEVEL-CVS
N cvssources/README
N cvssources/configure
N cvssources/configure.in
N cvssources/cvs-format.el
N cvssources/cvsnt.dsp
N cvssources/cvsnt.dsw
N cvssources/cvsnt.mak
I cvssources/config.cache
N cvssources/PROJECTS
N cvssources/install-sh
I cvssources/config.log
Here the command is reporting the files imported (which are all marked N for new),
together with the files ignored because their filename was matched in a .cvsignore file.
Other possible status values are L for a symbolic link, which is ignored, U and C which
indicate files already in the repository which are unchanged (U), or changed from the
repository version (C). If a file is marked as changed, a merge may be required.
Having imported the code, some attention may be required to the modules file. If users
are likely to work on subdirectories within the imported code, and there is no
requirement to check out all the code for the project, giving the subdirectories module
names or aliases in the modules file may be useful.

40


The import command does not initialise the code in the user’s sandbox. If this is required
the module needs to be checked out.
Import assigns the revision number 1.1.1 to a new file in the repository, as it treats the
set of files as a vendor branch. When checked out the files will be given revision 1.1.1.1,
and on checkin will become revision 1.1 on the main trunk.

Importing From Other Repositories
Because CVS uses the file format of RCS, files previously stored in RCS can be directly
copied into subdirectories of the CVS repository. The files to be copied should be the
archive files, identified by the ,v appendage to the filename. The CVS distribution
includes contributed scripts which can be used to convert from SCCS to RCS, the files
then being copied into the repository.

Adding a Directory Structure
Where files are to be added manually, or the project being started is a new one, it may be
useful to add a directory structure into the repository. This can be achieved by setting up
a directory hierarchy, changing to its top-level directory, and issuing the import
command.

Adding and Removing Files
Sometimes there will be a need to add or remove files individually, rather than import an
existing code structure. The commands add and remove are used for this. Add operates
only on files in the current directory, so it is necessary to check out the module to which
the file is to be added, then create the file in the appropriate place.
cvs add –m “File added by hand” <filename>
Marks the file to be added, but the file is not actually written to the repository until a
commit command is given. The descriptive message must be given with the –m switch,
the log message editor is not invoked with this command.
Directories may also be added with this command, and will be created within the current
module structure.
mkdir <directory>
cvs add <directory>
cvs commit <directory>
will create a subdirectory of the current directory in the repository.
Removing files may be performed in two ways. If the file is removed using the remove
command, it will continue to exist in earlier revisions. In this case CVS copies the
existing file to a directory called the attic, so the file no longer appears when the module
is checked out, but earlier releases can still be retrieved. If this is the desired result, the
commands:

41


rm <filename>
cvs remove <filename>
cvs commit <filename>
In general this is the correct way to remove files. However sometimes, perhaps after an
initial import of a code base, there are files detected in the repository which have been
included by accident. In this case the remove command would leave a copy of the file
permanently in the repository, which is not the desired outcome. In this case the file
should be deleted directly from the repository.
Removing a directory is achieved by removing all the files in the directory. There is no
way to remove a directory from the CVS repository, as the director would have existed
in previous revisions. Options exist to remove empty directories on checkout.

42

Configuration management with cvs and open source tools

Configuration management with cvs and open source tools

Recomendados

Recomendados

Más contenido relacionado

Similar a Configuration management with cvs and open source tools

Similar a Configuration management with cvs and open source tools (20)

Último

Último (20)

Configuration management with cvs and open source tools