SlideShare a Scribd company logo

Configuration management with cvs and open source tools

K
Karthik Raja

This document provides guidance on using the open source configuration management tool CVS (Concurrent Versions System). It covers planning an installation, including sizing considerations and code organization. It also covers installing CVS on Unix and Windows systems. Additional sections provide details on authentication methods, the repository structure, environment variables, and CVS command formats. The goal is to help users understand how to set up and use CVS for software configuration management.

EducationTechnologyBusiness
1 of 143
Downloaded 29 times
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
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
Configuration management with cvs and open source tools
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
Configuration Management with CVS 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
Configuration Management with CVS 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
Configuration management with cvs and open source tools
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
Configuration Management with CVS 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
Configuration management with cvs and open source tools
Planning for Installation 1 Planning for Installation 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
Configuration Management with CVS 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
Planning for Installation 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
Configuration Management with CVS 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
Planning for Installation 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
Configuration Management with CVS 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
Configuration Management with CVS #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
Configuration Management with CVS 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
Configuration management with cvs and open source tools
Connection and Authentication 3 Connection and Authentication 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
Configuration Management with CVS 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
Connection and Authentication 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
Configuration Management with CVS 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
Configuration Management with CVS 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
Configuration Management with CVS 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
Configuration Management with CVS 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
Configuration Management with CVS (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
Configuration Management with CVS 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
Configuration Management with CVS 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 The User Environment 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
Configuration Management with CVS 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
The User Environment 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
Configuration management with cvs and open source tools
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
Configuration Management with CVS 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 Setting up the Repository 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
Configuration Management with CVS 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
Setting up the Repository 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
Configuration Management with CVS 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
Development 8 Development Obtaining a Working Copy The first task of a developer who wishes to make some modifications to the code is to check out a working copy of the code from the repository. The command: cvs checkout <modulename> will achieve this below the current working directory. Thus the command: cvsuser@bohr ~/work# cvs checkout cvssources results in the structure shown in Figure 2 43
Configuration Management with CVS Screenshot 2 Checking out a module Normally, however, in a medium or large project a developer will work on only a small part of the code. Checking out the top level module defined by the import command may result in the developer having to descend the file tree by several levels to access the code he is interested in. The modules file can be used to simplify the structure of the individuals work area. The action of regular and alias modules is illustrated in the following examples. The modules file has been set up to contain the commands: docmodule cvssources/doc docalias –a cvssources/doc Now the action of a checkout is only to retrieve the files in the /cvssources/doc directory, but cvsuser@bohr ~/work# cvs checkout docmodule creates the files directly below a directory docmodule (Screenshot 3), while: cvsuser@bohr ~/work# cvs checkout docalias preseves the directory structure of the project (Screenshot 4), although the directories not specified in the alias definition will remain empty. In either case CVS keeps track of the actual place in the repository from which the files were extracted, so the commit command will work correctly. Thus careful consideration of the contents of the modules file can greatly simplify the view of the code presented to the developer. Files which are checked out are marked read/write for the owner, unless the global cvs option –r is used. If a file is being watched it will automatically be set read-only on checkout to enforce the use of the edit command to notify the watchers. 44
Development Screenshot 3 Checking out a subdirectory with a regular module Screenshot 4 Checking out a subdirectory with an alias module Making Changes A developer may edit one or many files. rebuild the subproject and test the program unit. Firstly, because CVS allows multiple users to update the same files simultaneously, some of the files which the developer wants to edit may be set read-only, because another user has asked cvs to report activity on the file by setting up a watch on the file. The way to overcome this is not to use chmod, but rather the cvs edit command. This 45
Configuration Management with CVS ensures that anyone else interested in changes to that file will be notified. Equally, if the developer is interested in who else may be editing the file, the cvs editors command may be used. This command can only list those users who have run the edit command on the file. So if the file cvs.texinfo in the doc subdirectory is being watched by cvsadmin, the command: cvsuser@bohr: ~/work/docmodule> cvs edit cvs.texinfo will notify cvsadmin that cvsuser is editing the file cvs.texinfo, and cvsadmin may search for all editors of the file with: cvsadmin@oppenheimer:~/work/cvssources/doc> cvs editors cvs.texinfo cvs.texinfo cvsuser Wed Nov 13 13:06:06 2002 GMT oppenheimer /home/cvsuser/work/docmodule Notification that a file is being edited is usually performed by mail, which requires the administrative file notify to be set up. Usually the notify file is set up with a single line: All mail %s –s “CVS Notification” CVS replaces the placeholder %s with the username. If the recipient’s mailbox is on another machine the users file must be set up to map the username to his email address: cvsadmin cvsadmin@oppenheimer A typical watch message is in the format: From cvsuser@oppenheimer.mlc Thu Nov 14 10:39:21 2002 Date: Thu, 14 Nov 2002 10:39:21 GMT From: cvsuser@oppenheimer.mlc To: cvsadmin@oppenheimer.mlc Subject: CVS notification cvssources/doc cvs.texinfo --- Triggered edit watch on /usr/local/cvs/cvssources/doc By cvsuser Watches are set up with the cvs watch command, and a developer may watch for the specific actions edit, commit, unedit and all. The watch command requires two separate actions, firstly to turn watching on (or off) for certain files: cvs watch on <filename> which causes the file to be watched, and for checkouts of this file to be made read-only, and secondly to request notification on certain actions: cvs watch add –a edit <filename> Here the current user will be notified if anyone who has checked out the file uses the edit command to make the file writeable. 46
Development Finally, when a developer has completed the changes and unit tested the program, the code must be restored to the repository. This is performed with the commit command, but as CVS allows many users to be working on the same file simultaneously, a situation may arise where another developer has modified the same file and checked the file back in before the current user. If the checkin were allowed to proceed, the original modifications would be lost. The normal procedure therefore is to precede the commit with an update command, to attempt to merge any changes already applied in the repository with the working copy in the user’s directory. If the user forgets this procedure, and attempts to commit a file which has already been updated, the system will not check the file in, but rather warn the user that an update is necessary. cvs commit: Examining . cvs server: Up-to-date check failed for `cvs.texinfo' cvs [server aborted]: correct above errors first! cvs commit: saving log message in /tmp/cvsosj1bG When the user runs the update command, CVS will report on the status of the files: cvsuser@bohr:~/work/docmodule> cvs update cvs server: Updating . RCS file: /usr/local/cvs/cvssources/doc/ChangeLog,v retrieving revision 1.1.1.1 retrieving revision 1.2 Merging differences between 1.1.1.1 and 1.2 into ChangeLog M ChangeLog M cvs.texinfo Here the cvs update command indicates that the updated files in the repository have been successfully merged with the sandbox files. It is possible, however, that the update command will fail: cvsuser@bohr :~/work/docmodule >cvs update cvs server: Updating . RCS file: /usr/local/cvs/cvssources/doc/ChangeLog,v retrieving revision 1.1.1.1 retrieving revision 1.2 Merging differences between 1.1.1.1 and 1.2 into ChangeLog rcsmerge: warning: conflicts during merge cvs server: conflicts found in ChangeLog C ChangeLog In this case an automatic merge was not possible, as the same line in both revisions had been changed. Here the developer must resolve the conflicts himself. CVS will have flagged the conflict in the user’s working copy of the file, in a standard diff format: <<<<<<< ChangeLog 2001-04-24 Derek Price <dprice@collab.net> ======= 47
Configuration Management with CVS 2001-04-28 Derek Price <dprice@collab.net> >>>>>>> 1.3 When the user has resolved the conflict, the files can be committed: cvsuser@bohr:~/work/docmodule> cvs commit cvs commit: Examining . Checking in ChangeLog; /usr/local/cvs/cvssources/doc/ChangeLog,v <-- ChangeLog new revision: 1.4; previous revision: 1.3 done Checking in cvs.texinfo; /usr/local/cvs/cvssources/doc/cvs.texinfo,v <-- cvs.texinfo new revision: 1.3; previous revision: 1.2 done Small changes which can be made quickly are easy to deal with, but there are cases where code will be checked out and remain under development for longer periods. In this case it can be useful to check on what actions have taken place on a file, and to find the differences between versions of files. Three mechanisms are available for tracking changes, the history file and the diff and status commands. Status The status command reports on files in the user’s work area, and compares them to the latest revision in the repository. cvsuser@oppenheimer:~/work/docmodule> cvs status ChangeLog ============================================================ File: ChangeLog Status: Up-to-date Working revision: 1.4 Repository revision: 1.4 /usr/local/cvs/cvssources/doc/ChangeLog,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) Status may report the state of the file as: Up to date The file matches the most recent version in the repository for the current branch. Locally modified The file has been edited locally, but has not yet been committed. Locally added The file has been added with the cvs add command, but not yet committed. 48
Development Locally removed The file has been removed with the cvs remove command, but the remove has not yet been committed. Needs checkout The file in the repository has been modified since the file was checked out, and an update is needed. Needs patch The file in the repository has been modified since the file was checked out, and an update is needed. CVS will do this with a patch. Needs merge The file has been modified, but another user has committed changes to the repository. A merge will be required to reconcile the changes. File had conflicts on merge A previous update had failed because conflicts were detected. The merge must be made manually. Unknown The file exists in the work area, but not in the repository. Status also lists the revision which was checked out, and the current revision in the repository, together with any sticky options associated with the file. The Log History The types of action which are logged in the history file are set up in the administrative file config. The option is set by: LogHistory=[T|O|F|E|W|G|C|M|A|R|all] where the string is a concatenation of the options required, or the word all. The meaning of the options is shown in Table 4 Option Description A File added C Collisions detected during merge E export F release G Successful merge M File modified O checkout R File removed T rtag U Working file copied from repository W Working file deleted during update 49
Configuration Management with CVS Table 4 History Logging Options Information logged in the history file can be retrieved with the history command. It is not sensible to write scripts to process the history file directly, as the format of the file is undocumented, and may change in later versions. By default the history command only reports on actions performed by the current user, but this may be extended to cover all users with the –a switch. The information returned by the history command is rather terse: cvsuser@bohr:~/work/docmodule> cvs history –a –e cvs.texinfo O 2002-11-14 10:32 +0000 cvsadmin CVSROOT =CVSROOT= <remote>/* O 2002-11-14 10:32 +0000 cvsadmin CVSROOT =CVSROOT= ~/work/* M 2002-11-14 11:06 +0000 cvsadmin 1.2 cvs.texinfo cvssources/doc == <remote> O 2002-11-14 11:22 +0000 cvsadmin cvssources =cvssources= <remote>/* O 2002-11-13 11:27 +0000 cvsuser cvssources =cvssources= <remote>/* O 2002-11-13 11:29 +0000 cvsuser cvssources =cvssources= <remote>/* O 2002-11-13 12:03 +0000 cvsuser cvssources/doc =docmodule= <remote>/* O 2002-11-13 12:04 +0000 cvsuser cvssources/doc =cvssources/doc= <remote>/cvssources/doc O 2002-11-13 13:02 +0000 cvsuser cvssources/doc =docmodule= <remote>/* C 2002-11-14 11:12 +0000 cvsuser 1.2 cvs.texinfo cvssources/doc == <remote> M 2002-11-14 11:43 +0000 cvsuser 1.3 cvs.texinfo cvssources/doc == <remote> Another option is the CVS log command, which prints a log of the actions performed on an individual file: cvsuser@bohr:~/work/docmodule> cvs log cvs.texinfo RCS file: /usr/local/cvs/cvssources/doc/cvs.texinfo,v Working file: cvs.texinfo head: 1.3 branch: locks: strict access list: symbolic names: Import: 1.1.1.1 mlc: 1.1.1 keyword substitution: kv total revisions: 4; selected revisions: 4 description: ---------------------------- revision 1.3 date: 2002/11/14 11:43:38; author: cvsuser; state: Exp; lines: +2 -1 Further comments added ---------------------------- revision 1.2 date: 2002/11/14 11:06:11; author: cvsadmin; state: Exp; lines: +1 -1 Updated comments 50
Development ---------------------------- revision 1.1 date: 2002/11/11 11:09:00; author: cvsadmin; state: Exp; branches: 1.1.1; Initial revision ---------------------------- revision 1.1.1.1 date: 2002/11/11 11:09:00; author: cvsadmin; state: Exp; lines: +0 -0 Import ============================================================ Here each version of the file is described, along with a listing of the log message added at commit time. The annotate Command For an extremely detailed view of the changes made to a file, the annotate command prepends a comment to each line in the file, showing the version in which the line was last modified, the user performing the change, and the date and time: *************** 1.5 (cvsuser 23-Nov-02): 2001-07-14 John Gregory <jg@mlc.net> 1.5 (cvsuser 23-Nov-02): 1.5 (cvsuser 23-Nov-02): * Added comments on annotate. 1.5 (cvsuser 23-Nov-02): * Rebuilt system. 1.5 (cvsuser 23-Nov-02): 1.3 (cvsadmin 14-Nov-02): 2001-04-28 Derek Price <dprice@collab.net> 1.1 (cvsadmin 11-Nov-02): 1.1 (cvsadmin 11-Nov-02): * Makefile.in: Regenerated using AM 1.4e at 18:10 -0400. 1.1 (cvsadmin 11-Nov-02): * CVSvn.texi: Regenerated. 1.1 (cvsadmin 11-Nov-02): 1.4 (cvsuser 14-Nov-02): 2001-03-31 Larry Jones <larry.jones@sdrc.com> 1.1 (cvsadmin 11-Nov-02): 1.1 (cvsadmin 11-Nov-02): * cvsclient.texi (Dates, Requests): Add rannotate and rlog. 1.1 (cvsadmin 11-Nov-02): Earlier versions may be examined by specifying the date, revision or symbolic tag of the file or files in question. Customised Logging Where the default CVS logging information is considered inadequate, the administrative files modules, commitinfo, verifymsg and loginfo have options to run programs on certain actions, and these can be used to increase the flexibility of logging. For example 51
Configuration Management with CVS the –i option in the modules file specifies a program to run on commit actions. This program is supplied with the full pathname of the module as an argument. The Diff Command When checking the modifications which have been made to a file it is often useful to compare different versions of the file. The CVS diff command is useful because it can display differences between files in the user’s work area and revisions in the repository. By default the differences are computed from the file’s working copy and the revision from which the file was checked out, although there are many options to diff to choose the files being compared. cvsuser@bohr:~/work/docmodule> cvs diff ChangeLog Index: ChangeLog ============================================================ RCS file: /usr/local/cvs/cvssources/doc/ChangeLog,v retrieving revision 1.4 diff -r1.4 ChangeLog 0a1,5 > 2002-11-15 Peter Pauling <pete@uni.org> > > * Made some changes to show a diff. > * Rebuilt code. > cvsuser@oppenheimer:~/work/docmodule> Checkout –p Both checkout and update support a switch (-p) which causes the output to be directed to the console, and thus can be redirected to utility programs such as grep. This can be useful for examining changes in revisions of files without cluttering up the working directory by having to retrieve each file from the repository. Abandoning Changes Having checked out a module and made some changes, it sometimes becomes apparent that these changes are not needed, or the modification is abandoned. In this case the developer needs to release the files formally, but does not want to return them to the repsitory. The command: cvs release <directoryname> should be run from the parent directory of the directory to be released. A useful switch is the –d switch, which also deletes the working directory. It is not strictly necessary to use this command, as files are not locked in the repository. However, as the command checks for uncommitted changes, and leaves a record in the history file, it is safer to use this command rather than simply delete the working directory. 52
Development Keyword Substitution CVS supports keyword substitution to facilitate the readability of information stored in the code. Keywords specified with strings of the form $<keyword>$ or $<keyword>$:…$ are expanded to keyword, value pairs when a revision is obtained from the repository. The keywords available for expansion are shown in Table 5 Keyword Description $Author$ Username of the user who checked in the revision $Date$ Date and time of checkin $Id$ RCS filename, revision, date, author and state of the revision. $Header$ Full RCS file path, revision, date, author and state of the revision. $Name$ Tagname specified on checkout $Locker$ User who has locked the file. Normally not used in CVS $Log$ The log message specified on commit, together with the RCS filename, revision, author and date $RCSfile$ Name of the RCS file $Source$ Full path of RCS file $State$ State assigned to the revision $Revision$ Revision number Table 5 Keywords Keyword substitution can lead to problems, for example when a string matching a keyword is found in a binary file, so CVS provides various switches controlling how keywords are expanded. Each file has a keyword substitution mode associated with it, set either by the cvs add command when the file is first created in the repository, or added with the cvs admin command. This is particularly important for binary files, as accidental keyword expansion could destroy the file’s contents. A different mode may be set in a working copy of the file by specifying the keyword substitution mode to the checkout or update command. The CVS diff command may be set not to report different expansions of keywords with the –k<kflags> switch. Binary Files It has already been pointed out that keyword substitution needs to be turned off, and the line end conversion supplied by CVS when checking out to a system with different conventions needs to be suppressed in order to maintain the integrity of binary files. 53
Configuration Management with CVS Another problem arises with the default unreserved checkout mechanism of CVS. The system allows multiple updates, and relies on merging changes back into the repository. In most cases (and certainly if using only the facilities of CVS), there will be no merge program available for a binary file, so if simultaneous updates have occurred, the only action CVS can take is to present the user with the two copies of the file, and allow him to choose one or the other, or use some external mechanism to merge the files. Watches provide a mechanism for warning an interested user that someone is editing a file, but these do not force a behaviour on the developers, and need to be backed up with procedures. In a large project it would certainly be possible to overlook a reported watch message. If a strict method of dealing with this problem is required, binary files can be checked out exclusively, placing a lock on the file until it is released. The cvs admin –l command allows the file to be effectively locked. Sticky Options Normally one does not want to have to remember the options which need to be specified for handling a file on each commit, so certain options are recorded with the file, and persist during the life of the file, or until they are changed. Binary files added to the repository can have their keyword substitution mode set with: cvs add –kb <filename> Where a file has been given the wrong mode, it can be corrected with: cvs admin –kb <filename> It is possible to override this default when checking out, updating or exporting the file. The cvswrappers file also allows default behaviours to be specified depending on the matching of a filename pattern. Exclusive Locks The whole philosophy of CVS is built around the opportunity for many developers to work on the same files simultaneously. Many other systems operate with exclusive locks on files, which allow only one person to be modifying a file at any one time. The trade- off is delays in development against the problems of having to merge changes together when returning files to the repository. There can be occasions where an exclusive lock is desirable, but although CVS offers some means of controlling this situation, it is not a perfect solution. The command: cvs admin –l <filename> locks a file to the extent that only the person who issued this command will be able to commit the file to the repository. Only one lock in each branch of the code is allowed for each file. This, however, does not mean that the file is not already being modified by another user, who will then have problems returning the file to the repository. 54
Development There have been patches written for CVS to allow exclusive locks, but all depend to some extent on co-operation between users. The standard watch facilities are sufficient to warn a developer that another user id modifying a file, and these should be used in preference to other methods. Strange Files In normal operation CVS may create other files in the user’s working directory. Files named in the form: .#<filename>.<revision> are created when an update is performed in the working directory on a modified file, and records the state of the file before the update was performed. This can be useful if conflicts which cannot easily be resolved are found, as this file will contain only the developer’s own modifications to the file he checked out. It may be desirable to run a housekeeping job to delete such files after a certain time. 55
Configuration management with cvs and open source tools
Revisions, Releases and Branches 9 Revisions, Releases and Branches CVS records changes in files in the repository as development progresses using revision numbers. Normally the first revision of a file will have revision number 1.1, and the next update 1.2. When a new file is added, the rightmost number will be set to 1, with the left hand number set to the highest number existing in the module in the repository. Note that the import command acts slightly differently, and creates the first version in the repository as 1.1.1. There is normally no need for the user to concern himself with revision numbers, and it is much more convenient to use symbolic tags to mark releases or project milestones. However CVS does allow the user to manipulate revision numbers through the –r switch to commit. With the working directory the current directory, the command: cvs commit –r 5.1 will set all files to this version in the repository, even if they have not been modified locally. By default the command will deal recursively with subdirectories of the module. It is not possible to set a revision number lower than the highest one which exists already in the module. The process of defining all the revisions which make up a release or milestone is called tagging. Here a symbolic tag is added to a consistent set of files. The tag allows the release to be retrieved, even when development of the next version of the software has continued. Tags must start with a letter, and contain only alphanumeric characters, and the symbols ‘-‘ and ‘_’. Thus for release 1.0 of the program widget, a suitable tag might be widjet-1- 0. CVS provides two commands for manipulating tags, tag which operates on files in the working directory, and rtag which operates on files in the repository. The normal way to 57
Configuration Management with CVS set a tag representing a release is to move to the top of the module in the working directory, making sure all files are up to date, and issue the command: cvs tag widget-1-0 By default this command will operate recursively on all files in all subdirectories of the module. If this is not the desired effect, it can be turned off with the –l switch. Although the cvs tag command operates on the versions of files checked out in the current working directory, it also applies the tag immediately to the repository versions of these files. Tagging only a limited number of files is also possible : cvs tag widget-1-1 widget.h One useful switch to the cvs tag command is –c (which might be useful to set as a default in the users’ .cvsrc files). This forces a check for any differences between the repository revision of the file, and the copy in the working directory. If differences are found the tag is aborted. Having tagged a release or milestone, a user can check out that version of the software by using the –r switch to checkout: cvs checkout –r widget-1-0 <modulename> The command cvs rtag can be used to move or delete tags in the repository, so this is a command which must be used with extreme caution. Moving a tag means changing the revision number of one or more files with which the tag is associated. cvs rtag –r 2.7 –F <tagname> <filename> would associate <filename> revision 2.7 with the symbolic tag <tagname> in place of the current revision. Software development is rarely a straight-line process, and very often parallel development of features for different releases will be necessary. For such situations branches are set up. A branch is created with tag for a module in the working directory, or rtag for files not checked out of the repository. With the required version of the module checked out, the command: cvs tag –b <branchname> will create a branch in the repository, but will not actually check out that branch to the working directory – the original version is still in the work area. To switch to the new branch it is necessary to perform one of: cvs checkout –r <branchname> cvs update –r <branchname> Operating directly on the repository, the command: cvs rtag –b –r <tagname> <branchname> creates a new branch <branchname> based on the release <tagname> In creating a branch CVS creates a new stream for parallel development. A typical use for such a branch would be to continue development of a software product after a release, while using the branch from the release to fix any reported bugs. 58
Revisions, Releases and Branches Main Trunk Tag Rel-1-0 Revision Revision Revision Revision 1.6 1.7 1.8 1.9 Branch Tag Rel-1-0patch Branch Revision Revision Revision 1.7.2 1.7.2.1 1.7.2.2 1.7.2.3 Figure 2 Creating a Branch CVS creates a revision number for the branch by appending a further digit, starting with 2 onto the revision number of the root file. The files themselves are given a further digit starting at 1. Normally the user will not concern himself with the actual revision numbers, but will refer to the branch by its symbolic tag. Note that the set of files checked out have been selected by their symbolic tag, so the actual revision numbers of the files in the branch are all likely to be different, as they are rooted in files with different revision numbers. Working on a Branch When a developer issues a checkout command for a module, he will normally receive the latest version of the code in the main branch (trunk). To check out the code in a branch the command: cvs checkout –r <branchname> <modulename> or: cvs update –r <branchname> [<modulename>] is used. the name of the module only needs to be specified if the current directory is not set to the top level directory of the module within the work area. Now the user can work on the branch, and may simply commit modified code without worrying about where the code will be placed in the repository. The reason CVS is able to do this is that it maintains a “sticky tag” representing the branch name for the code in the working directory. The status command may be used to check this: 59
Configuration Management with CVS cvs status cvs.texinfo ============================================================ File: cvs.texinfo Status: Up-to-date Working revision: 1.3 Repository revision: 1.3 /usr/local/cvs/cvssources/doc/cvs.texinfo,v Sticky Tag: cvssrc-1-0patch (branch: 1.3.2) Sticky Date: (none) Sticky Options: (none) ============================================================ Operating in this way the developer, after checking out the branch may ignore the fact that he is working on a branch, until his work is complete. Obviously if manual changes are made to the work area, the sticky tag may be lost, so this should be avoided. Merging a branch In our scenario of a release, followed by further development and bug fixing in parallel, there will come a time when the bug fixes are required to be incorporated into the main trunk. This might be at a stable point in the new development, or delayed until the release is ready for final test. The process of incorporating changes from a branch into the trunk is performed by merging. There are two ways of merging a branch, with the update or checkout command, but in both cases the working area is first set to contain the contents of the main trunk. cvs update –r <tagname> [<modulename>] sets the work area to contain the main trunk code, then cvs update –j <branchname> causes the branch to be merged into the trunk in the work area. This must be followed by a commit to replace the files in the repository. When merging a branch it is possible to specify the date of the branch revisions to use to update the trunk: cvs update –j <branchname>:<date> Keyword substitution can produce false conflicts, when for example the revision number is expanded in both files being merged. It is thus useful to use the –kk switch to update, to suppress keyword expansion. Use of the –kk switch overrides any default keyword expansion flags set for a file, so it should not be used where binary files exist in the repository, and have the –kb mode set. Merging can, however, show up conflicts in the files, which have to be dealt with manually before committing. There can be further complications of working on a branch. Perhaps, during further development on the trunk it becomes necessary to incorporate a bug fix made in the patch branch, but work is still ongoing in both the trunk and branch code streams. It would be possible to merge the branch, and then set up a further branch off the tip of the 60
Revisions, Releases and Branches current branch for further development, but this may lead to confusion and is unnecessary. It is quite possible to merge the current state of the branch, perform more modifications, then merge the differences between the original merge, and the final code. If we were only concerned with a single file, the command: cvs update –j <revision number> -j <branchname> <filename> will merge all the differences in <filename> made between <revision number> (which should be the revision originally merged into the main trunk, and the current tip of the branch <branchname>. Such an operation is impractical when several files are involved, as they are all likely to have different revision numbers. However, if the branch is given a symbolic tag at the time of merging the branch, the same command may be given to merge all the updated files: cvs update –j <tagname> -j <branchname> similarly two symbolic tagnames could be used, if tags had been applied to the branch when milestones were reached. It is good practice to tag the head of a branch before merging, as if further changes are made to the branch, a second attempt to merge the branch from its root will fail with reported conflicts. It is necessary to merge only the new changes in the branch, which is much easier if a symbolic tag is used to mark the point of the previous merge. Backing Out a Change The update command can be used to revert to an earlier revision of a file, or to remove all changes made between two revisions. The command: cvs update –j 2.7 –j 2.3 <filename> will remove all the changes made between the two revisions 2.3 and 2.7. The order of the revisions is significant. The Vendor Branch When a set of files is imported into a repository both a vendor tag and a release tag are specified, and by default the files are imported into the CVS vendor branch which is labelled with the revision number 1.1.1. The vendor branch is also marked as the default branch, which will be searched as well as the trunk to find the most up to date revision of a file. CVS only supports properly a single vendor branch, but there is an option to the import command to specify the branch revision number when importing to create further vendor branches: cvs import -b<vendor branch> <module name> <vendor tag> <release tag> where <vendor-branch> is specified as (say) 2.2.2 (a branch is always identified by a 3 digit revision) will create a new vendor branch. CVS only looks for a single vendor branch, so the default branch will have to be specified when checking out files. 61
Configuration Management with CVS To set the default CVS branch for a work area to <branch> use checkout or update with the -r <branch> option. The effect of this command is to override any sticky branch tags for the work area concerned, and any subsequent checkouts will come from the specified branch. The ability to specify different vendor branches is of very little use, unless the previous vendor branch is to be removed from the repository. If multiple vendor branches are used, the greatest care must be taken to specify the branches correctly when checking out files. In practice it is unlikely that projects from different vendors would be mixed in the same repository, and a series of releases from a vendor can be imported into the same vendor branch, being identified by the release tag. 62
Source Distribution and Mirror Sites 10 Source Distribution and Mirror Sites When a release has been tagged, it may be desirable to package up the source for distribution to other sites. This can be achieved with the export command. cvs export –r <tagname> -d <directoryname> <modulename> which causes the module’s files tagged with <tagname> to be checked out into a directory structure under <directoryname>. The only difference between this command and a checkout is that the CVS directories are not created within the module directories, thus creating only a source tree suitable for distribution. The export command can also select files by date, or revision number. An alternative, where regular source updates are made, is to issue a patch to update the last release to the current revision. The CVS rdiff command: cvs rdiff –r <tagname1> -r <tagname2> will create a patch file to update a directory from release <tagname1> to release <tagname2>. Where there are distributed sites which need access to the code in a repository, it may be useful to mirror the main repository locally. A utility to do this, CVSup, is optimised for CVS in that it is able to update a repository by transmitting only the changes applied to the repository since the last update. The system runs as a daemon on the central CVS repository host, and a client, which is usable as a command line program or graphical interface, on each of the mirrors. 63
Configuration Management with CVS Screenshot 5 The CVSup GUI CVSup can be set up to transfer or update either a complete repository, or a particular version of selected modules of the code. There is considerable control over the files to be transferred, which is useful when many variants of a code set exist, for example for localisation. Transfers are initiated by the receiving client, which may decide to request a subset of the code tree offered by the main server daemon. Other open source packages which can be used to create mirror sites include sup, rdist, rsync and mirror, but these are not optimised for CVS. 64
Windows Problems 11 Windows Problems When using a Windows client using the NTFS file system, there are instances where the modification time of a file is erroneously set, and the file appears to have been modified when in fact it has not. This occurs with Windows clients, irrespective of whether the CVS server is running Windows or Unix and usually manifests itself during daylight saving time, or after a change to or from DST. A solution is available for the client supplied with cvsnt, in the form of a registry key. The key must be set for every user of the cvs client: [HKEY_CURRENT_USERSoftwareCVSClient] "GmtTimestamps"=dword:00000001 After setting this key, files which were incorrectly marked as updated can be fixed by running cvs stat on them. The difference between Windows and Unix treatment of line endings (CR/LF and LF) is automatically catered for by the CVS checkout and commit commands. This means, however that it is not possible to copy files in a user’s work area from one system to another. More attention should be given to specifying binary files, as line ending conversion will almost certainly render a binary file unusable. When using a filesystem exported by SAMBA, some problems during commits and removal of files have been reported. Setting DeleteReadOnly=yes should cure these problems. 65
Configuration management with cvs and open source tools
Front Ends 12 Front Ends So far we have concentrated on the use of the CVS command line interface, which will always be required to perform some of the tasks which the configuration manager will have to perform. The majority of developers, particularly those working in a GUI environment, are likely to be uncomfortable with this interface. There are several graphical front-ends available for CVS, both under MS Windows, and X-Windows which simplify the day-to-day tasks of a developer. The best known of these are WinCVS for MS-Windows and gCVS and Cervisia for Unix/Linux, but there are others available (See Resources). WinCVS The most windows-compliant and comprehensive GUI for CVS is WinCVS, developed by a group of enthusiasts, and made available under the GNU public licence. Once a project has been set up by the configuration manager, the GUI displays a representation of the project similar to Windows Explorer, with information on the status of the modules and files displayed graphically. Using the menu items, context menu or the toolbars, the developer can checkout a module, write-enable files, perform the changes required and check the module back into the repository. The only clue that CVS is in use is the message pane at the bottom of the window which displays the CVS commands being used, and any status and error messages. Differences between the repository files and local copies can be displayed, as can the version history of a file. Where WinCVS does not provide a facility (which should be very rare within the scope of a developer’s needs), a command line interface facility is available. 67
Configuration Management with CVS WinCVS provides every facility for the developer to operate under a completely graphical interface, and almost all that is needed by the configuration manager for setting up projects and releasing software versions. Screenshot 6 The WinCVS GUI gcvs The gcvs package which runs with the gtk+ toolkit (Gimp toolkit) follows similar lines to WinCVS, in that it displays the directory tree in the left hand pane, and the files in the work area in the right pane. Operations are performed in a similar way to WinCVS, and again the lower part of the window displays the actual CVS command line and the messages received from CVS. Screenshot 7 The gcvs GUI 68
Front Ends Cervisia The interface to Cervisia takes a slightly different approach, and only the files under development are shown, the directories being selected through a dialog box. Cervisia offers fewer command options than gcvs and WinCVS, but this may not be a bad thing as developers usually are more concerned with programming than configuration management, and simplicity can improve the CM process. Cervisia is supported for the Linux/KDE environment. Once again the lower part of the screen displays CVS commands and messages. Screenshot 8 The cervisia GUI TortioseCVS Another Windows GUI freely available, TortoiseCVS takes a different approach, by adding items to the Windows Explorer context and file menus. Whilst not offering the comprehensive support of WinCVS, TortoiseCVS may be a viable alternative for developers who only rarely need to get involved in configuration management issues, and just need to follow the discipline of checking modules in and out of the repository. TortoiseCVS indicates the status of files by modifying the icons used to identify files under windows explorer. By default a file which has been modified is displayed in red, while a file with conflicting modifications is shown in purple. Green signifies a file which has not been modified, but is held in the repository, while a blue question mark shows a file not yet stored in the repository. 69
Configuration Management with CVS Screenshot 9 The TortoiseCVS GUI CVSIn For developers using Microsoft Visual Studio CVSIn is an add-in which provides direct access to CVS repositories from the VS interface. CVSIn displays a toolbar with the basic CVS commands directly accessible from within VS. The commands catered for directly are: update ,commit, query, diff, log, status, edit, unedit, watch, release watch, tag, untag, fork and unlock.Where more complex CVS operations are to be performed CVSIn launches a wizard giving access to WinCVS. Screenshot 10 the CVSIn add-in toolbar for Visual Studio Lincvs LinCVS, although Linux support is implied by it’s name will also soon support Windows clients. It is based around the Qt package, a multiplatform C++ GUI application framework. Again an explorer-like view is shown in the left window, but this is not simply the file tree, but a selection of directories made by the user, by adding them to his workbench. Files from these directories are displayed in the right hand pane, and menu options allow CVS operations on these files, either singly or as a group. As with most of these front ends, the result of CVS commands is displayed in the lower window. 70
Front Ends Screenshot 11 The LinCVS GUI EMACS The popular Unix editor emacs has some built-in support for CVS, RCS and SCCS through its version control commands(VC). A further add-in script pcl-cvs provides further integration with CVS. VIM An add-in script for VIM, cvsmenu.vim to provide a CVS menu of commands is available. This functions both with the character based vim, and the graphical editor gvim. Screenshot 12 Cvsmenu adds CVS functions to vim 71
Configuration Management with CVS Screenshot 13 The gvim plugin Displays the CVS menu 72
Build Systems 13 Build Systems CVS does not provide any special facilities for building the software, so it is likely that one of the versions of make will be used. There are also open-source build systems available, such as Odin, Jam and Cook (See Resources). The problem in building is that a developer working on one or two modules will want to compile and test the code he is working on, while this code may be dependent on many other parts of the system. For each developer to check out large amounts of code is both time and disk consuming, and dangerous, as each individual developer will need to keep large amounts of code in synchronism with the repository. For this reason, in a large project it may be sensible for the configuration manager to maintain a central copy of up-to-date checked out code which can be used by the developers through operating system mechanisms such as links, or the make facilities such as VPATH. It is wise for the build to be totally automated, which favours makefiles at all levels within the project, allowing checked out modules to be compiled with a local makefile, and higher level makefiles visiting lower levels and executing the subordinate makefiles. Because of the default recursive behaviour of CVS, the latest source can always be copied to a staging area for compilation by issuing an update command at the top level of the project tree. For example: cvs update –j <tagname> will retrieve the whole project tree of the release tagged with <tagname>. Strictly it would be better to issue the command: cvs update –d –P –j <tagname> 73
Configuration Management with CVS as, if the work area has been used before, it may contain directories which have since been deleted, and not contain directories which have been added in the repository. The – d switch will cause the new directories to be created, while –P prunes any redundant ones. For auditing purposes it is frequently desirable to construct a bill of materials, recording all the versions of the code files which have been used in a build. This can be achieved if the release has been tagged with the command: cvs log –r<tagname> which produces as output: ============================================================ RCS file: /usr/local/cvs/cvssources/doc/cvs.texinfo,v Working file: docmodule/cvs.texinfo head: 1.3 branch: locks: strict access list: symbolic names: cvssrc-1-0patch: 1.3.0.2 cvssrc-1-0: 1.3 Import: 1.1.1.1 mlc: 1.1.1 keyword substitution: kv total revisions: 4; selected revisions: 0 description: ============================================================ RCS file: /usr/local/cvs/cvssources/doc/cvsclient.texi,v Working file: docmodule/cvsclient.texi head: 1.1 branch: 1.1.1 locks: strict access list: symbolic names: cvssrc-1-0patch: 1.1.1.1.0.2 cvssrc-1-0: 1.1.1.1 Import: 1.1.1.1 mlc: 1.1.1 keyword substitution: kv total revisions: 2; selected revisions: 0 description: 74
Build Systems Make Most developers will be familiar with one of the versions of make, and GNU make is available under the GNU Public Licence. Make can, however, be difficult to use in large projects where files are distributed over many directories, and variant builds can be problematic. One of the most difficult aspects of building a project with the minimum amount of recompilation is the determination of dependencies, for which a tool such as makedepend is required. It is normal to have to run this tool on the whole set of project files, each time a build is made in order to ensure that the correct files are rebuilt, which can be time consuming. The build systems described here use more sophisticated methods of determining and storing dependencies. Jam Jam (Just Another Make) is a software build tool particularly orientated towards C/C++, where its built-in rules are able to determine dependencies. It can, however be used with other languages. Jam is freely available as C source from Perforce Software. http://public.perforce.com/public/index.htmlBecause Jam understands C/C++ dependencies, there is no need to declare header or object files. A build of a C/C++ project can therefore be specified by simply listing the components in a syntax similar to make, using the rule Main: Main program: main.c sub.c sub1.c …; Jam runs on many platforms, and is able to handle projects scattered over many directories. It can also use multiple hosts to perform the build. Cook Cook is another replacement for make on Unix systems and includes variables and user- defined functions. It can distribute build activity across multiple machines on a network, and facilities for producing a bill of materials are included. The program provides a method of generating and using a dependency file for each component of the project. Odin Odin determines dependency information automatically, and stores it in a database, updating the information incrementally as required. It supports parallel builds on networked machines, and has features to support variant builds. ============================================================ 75
Configuration management with cvs and open source tools
Visualising the Source Tree 14 Visualising the Source Tree CVS offers no way of examining the ancestry of a file except in report form, but it is often useful to have a picture of the development tree showing the branches and releases. The Unix utility cvsgraph produces a graphical representation of the source code in an RCS file. WinCVS also has a feature to display the code tree graphically. 77
Configuration Management with CVS Screenshot 14 The Display from CVSgraph For Windows users the WinCVS front end also offers a graphical representation of the source tree. Screenshot 15 The WinCVS Graphical Display 78
Diff and Merge Programs 15 Diff and Merge Programs Windows Programs CSDiff Whilst not strictly an open source product, this diff program is available free of charge from Component Software. Text files are displayed either in the normal diff format or in a more friendly fashion in a single window. A useful feature of this program is that it can display differences in MS Word format files, although an installation of Word is required, as CSDiff launches Word to display the differences. CSDiff analyses the differences in both files and directories, and reports can be printed in diff or HTML format. 79
Configuration Management with CVS Screenshot 16 The CSDiff Diff Format Display Screenshot 17 CSDiff Handles MS Word Files WinMerge Winmerge displays the differences between two files side by side, with colour used to highlight additions and deletions. It will also analyse the differences between two directories. Merging can be performed by highlighting a difference and selecting copy to left or right, or all differences can be merged in one command. 80
Diff and Merge Programs Screenshot 18 The WinMerge Display Unix Programs xxdiff The xxdiff program is a graphical front end to standard diff programs such as gnu diff. It is launched from the command line as: xxdiff file1 file2 [file3] and can compare two or three files or two directories. Merging can be achieved by selecting sections of text and using a merge command from the menu. Screenshot 19 xxdiff shows the differences reported by a standard diff program GNU Diff Utilities GNU Diff Utilities are a set of command line programs for comparing files, generating patches and merging files. Diff and diff3 are used for comparing two files or directories, or three files, cmp compares two files, while sdiff can be used to merge files. The patch utility is used to apply a diff generated patch to a file. The CVS diff command supports a subset of the GNU diff commands. 81
Configuration Management with CVS 82
Anonymous CVS 16 Anonymous CVS The popularity of open source software, and the collaborative effort of programmers all over the world to produce and maintain it, has led to a large number of CVS source repositories being made publicly accessible. Obviously one of the objectives of configuration management and source code control is to avoid a free-for all in software development, and anonymous CVS provides the facilities to organise collaborative development. CVS can be set up to allow read-only access to anyone, and this is usually implemented by setting up a user named anonymous, requiring no password but included in the admin file readers. Anyone is therefore free to download the source tree of a project, and compile and modify the code. Each project may follow a different procedure, but if a developer would like his modifications to be incorporated in the project he will normally produce a patch with CVS and submit it to a moderator who has full access to the project source tree. A large number of such open source projects are hosted by SourceForge (http://sourceforge.net) The following is an example of obtaining the source to cvstrac from an anonymous CVS server: # cd /usr/src/cvstrac # cvs -d :pserver:anonymous@cvs.cvstrac.org:/cvstrac login Logging in to :pserver:anonymous@cvs.cvstrac.org:2401/cvstrac CVS password: 83
Configuration Management with CVS # cvs -d :pserver:anonymous@cvs.cvstrac.org:/cvstrac checkout cvstrac cvs server: Updating cvstrac U cvstrac/COMPILING U cvstrac/COPYING U cvstrac/VERSION U cvstrac/attach.c Obtaining cvstrac by anonymous cvs 84
Problem Tracking 17 Problem Tracking Another aspect of controlling the software development cycle is the recording of problems or development tasks in such a way that they can be planned for, monitored and related to releases. CVStrac A problem tracker which is integrated with CVS is available as an open source product. Cvstrac is a web-based product which maintains a problem database, usually in the CVSROOT directory, and offers problem tracking and reporting, together with the useful ability to browse the CVS repository and investigate differences in the files. Although not having the flexibility to tailor problem reports to the organisation’s needs found in more sophisticated (and expensive) products, the system is perfectly usable. Cvstrac can be launched from a cgi script, run as a service started with inetd., or as a stand-alone web server The advantage of using a browser-based system is that the central problem database can be accessed from all the hosts in use by the developers, whether Unix or Windows based, although the tracking system itself runs only on a Linux/Unix server. Using Cygwin (a collection of Unix utilities for Windows), however, it is possible to run cvstrac on a Windows/Apache server system in http mode. The tracking system implements its own SQL-based database, so no external database server is necessary. User defined queries can be generated, and users’ access to the problem tracking database can be controlled on an individual basis. A facility is also provided for administering the CVS passwd file interactively. 85
Configuration Management with CVS Screenshot 20 The CVStrac Problem Ticket Cvstrac produces a variety of reports on the problem database, even allowing the user to create a new report by selecting problems with SQL statements. A timeline of checkins can be displayed from the CVS history file, and differences between revisions can be displayed by drilling down when browsing the changes recorded for a file. Screenshot 21 CVStrac displays the changes made to a file 86
Problem Tracking Bugzilla/CVSZilla One of the most popular open source problem tracking systems is Bugzilla, a system developed for tracking problems at Mozilla. It was originally written in TCL, but later ported to Perl by Terry Weissman the author. The port to Perl was released under the open source licence as Bugzilla V2.0. Since then it has been adopted as the main bug tracking system for many open source and other projects, and seen significant enhancement. It is simply accessed through a browser. The current design principles are aimed at making the system fast, lightweight and interoperable with any SQL based database, although it is currently restricted to MySQL, with work going on to support PostGreSQL and Sybase. Being written in Perl it is easily modifiable, and there are many installations where the code has been tailored to suit a particular organisation’s way of working. Part of the standard Problem report form is shown in Screenshot 22, and Screenshot 23 shows the screen where queries can be built up to search the database. Additional queries can be set up in SQL. Screenshot 22 Part of Bugzilla's Problem Report 87
Configuration Management with CVS Screenshot 23 Bugzilla's Query Form CVSZilla is a set of Perl scripts, originally written by Tony Garnock-Jones, which help to integrate Bugzilla with CVS. and ViewCVS or CVSWeb. They use the standard CVS features of commitinfo, loginfo, taginfo and verifymsg to cause changes to be stored in the MySQL database. 88
Administrative Tasks 18 Administrative Tasks Backup The CVS repository comprises standard Unix or Windows file types, and thus any backup system can be used to safeguard the code base. The only consideration is that, to maintain a self-consistent set of files, the repository should not be updated during the backup. This can be achieved by placing lock files in the repository directories, or by stopping the CVS server in client/server mode. A useful program which locks a Unix CVS repository, executes a command, then unlocks the repository is cvslock by Thomas Roessler (see resources). Tidying up the Repository After a long period of software development the repository will become large, and it may become desirable to remove older, intermediate versions of the code, retaining only the released versions or major milestones. This is achieved with the admin –o command, but the syntax of this command makes it very easy to make mistakes. Unless this operation is absolutely necessary it is better not used. There is no mechanism for reversing the effects of this command. The command: 89
Configuration Management with CVS admin –o 2.5::2.8 <filename> deletes all the revisions between 2.5 and 2.8, leaving these revisions intact, while: admin –o 2.5:2.8 <filename> deletes all revisions from 2.5 to 2.8 inclusive. If a symbolic tag or a branch exists in a revision the revision will not be deleted if using the :: syntax, but will with the : syntax. In both cases the operation will fail if any of the revisions to be deleted contain branches or locks. Although the revisions to be deleted can be specified with tag names, this has the side effect that if a file has not changed it may be deleted from another, later tagged release. CVS Defaults The CVS admin command allows default values for some CVS parameters to be set up. In practice the only default which it is useful to change is the keyword substitution method. For example: cvs admin –kkv sets the default to be the normal method for keyword expansion. The choice made by the administrator may be overridden by setting the value on the command line. Most of the other options to the admin command are historical values relating to RCS, and should rarely be used. Reset the Default Branch There will be some instances where software is supplied by a third party but modified by local developers. The software will have been initially imported into the repository using a vendor tag to create the vendor branch. Modules and files which have been checked out and updated will now lie on the trunk, and a checkout which does not specify a specific branch will retrieve the revision at the head of the trunk. If an updated release is received from the supplier, this will be imported into the vendor branch rather than updating the trunk. To ensure that a checkout is made from the latest vendor revisions the vendor branch can be reset as the default branch: cvs admin -b<vendor-tag> <module-name> 90
Other Utilities 19 Other Utilities cvsadmin cvsadmin is a tool to administer users of a CVS repository. It handles adding, deleting, renaming users, changing passwords, etc. gcvsadmin is a GTK interface to it that handles multiple repositories. CVSWeb A cgi script which allows a repository to be viewed in a browser. This program has evolved into CVSWebclient and CVSWebedit, which also allow CVS files to be edited. ViewCVS An alternative program to CVSWeb which allows a CVS repository to be viewed through a browser. cvsmonitor Another browser based viewer, also providing statistics and a graphical representation of them on the activities on the code. cvsreport Formats and mails reports on CVS activity. Freepository Freepository is a Web-based revision control system based on extensions of CVSWeb. It employs a project concept, which provides member accounts and access controls. cvspwd A utility for generating Unix-encoded passwords. dgdeletelocks.pl dgfindlocks.pl Scripts to find hanging locks in a CVS repository and delete them. dgfixcvs.pl Script to update the copies of the administrative files in the users’ working directories when a repository is moved. 91
Configuration Management with CVS findlocks.pl Locate files with exclusive locks. 92
Environment Variables A Appendix A Environment Variables Variable Description CVS_CLIENT_LOG Sets up log files for debugging communication in client/server mode. All client initiated communication is logged in CVS_CLIENT_LOG.in, and replies from the server in the corresponding .out file CVS_CLIENT_PORT The port number to use to communicate with the server CVS_PASSFILE The file used to store passwords during a session in client/server mode after a successful login. Defaults to ~/.cvspass CVS_RCMD_PORT The port to use on the server side to execute the remote command CVS_RSH Specifies the remote shell program to use, usually rsh or ssh CVS_SERVER The remote program to run when accessing a repository in client/server mode with the ext, server or fork modes CVS_SERVER_SLEEP Delays the start of the server program so that a debugger may be attached CVSEDITOR Specifies the program to run to edit log EDITOR messages. CVSEDITOR overrides EDITOR CVSIGNORE A list of patterns, separated by white space indicating files to ignore. the pattern is a shell 93
Configuration Management with CVS pattern (e.g. *.exe) and not a regular expression. CVSREAD Set files checked out or updated to be read-only CVSROOT The location of the CVS repository. This may be a simple path in the case of a local repository, or a connect string in client/server mode. Local example: /usr/local/cvs pserver: :pserver:cvsuser@oppenheimer:/usr/local/cvs CVSUMASK Sets the default file mode of files in the repository. Only available when CVS is used in local mode CVSWRAPPERS A list of patterns (shell format) and the options to be applied to those files, separated by white space Table 6 Environment Variables 94
Command Reference B Appendix B CVS Command Reference 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. Global Options Common Options Switch Description -b <binary directory> Location of RCS binaries – now obsolete -T <temporary directory> Location for temporary files -v Display version number --version Table 7 Common Global Options 95
Configuration Management with CVS Client Command Options Switch Description -a GSSAPI switch causes authentication of all messages between the client and server -d <root directory> Specifies the root of the repository and overrides any setting in CVSROOT -e <editor> Specifies the log message editor, overriding CVSEDITOR and EDITOR -f Ignore the settings in ~/.cvsrc -H [<command>] Display help on the specified command, or --help[<command>] a general help message if no command is specified -l Do not record this command in the history file -n Perform the command without modifying any files -q Quiet mode -Q Very quiet mode -r Make new working files read-only -s <variable>=<value> Set user variable, which may be expanded in an administrative file -t Trace -w Make new working files writeable -x Encrypt all communication between client and server, applies only to GSSAPI and Kerberos connections -z Set compression level for client/server communication Table 8 Client Global Options Server Option Switch Description --allow-root=<root directory> Allow access only to users accessing this repository. May be repeated for multiple repositories. Table 9 Server Global Options 96
Command Reference Client Commands add Add files or directories to the repository: cvs add [options] <filename> [<filename> …] Switch Description -k <kflags> Determines how keyword substitution is performed -m <message> Defines a descriptive log message Table 10 add command options annotate Prints a report showing the history of every line of the files specified: cvs annotate [options] <filename. [<filename> …] Switch Description -D <date> Use most recent revision no later than <date> -r <revision> Use this revision or symbolic tag -f Include files not tagged with the tagname, or not present on <date> -l Do not recurse into subdirectories -R Recurse into subdirectories Table 11 annotate command options checkout Check out the specified module into the user’s work area (sandbox): cvs checkout [options] <module> [<module> …] Switch Description -A Reset sticky tags and dates -c Copy the sorted module file to standard output -d <dir> Override the default directory name -D <date> Use most recent revision no later than <date> -f Include files not tagged with the tagname, or not present on <date> -j <rev> Merge branches -k <kflags> Keyword substitution mode -l Do not recurse into subdirectories -n Do not run checkout program specified in the administrative files -N Use full module paths -p Pipe files to standard output with header information 97
Configuration Management with CVS -P Remove empty directories -r <revision> Use this revision or symbolic tag -R Recurse into subdirectories -s Show the status of each module Table 12 checkout command options commit Commits file changes made in the work area to the repository cvs commit [options] <filename> [<filename> …] Switch Description -f Force the commit, even if the file is unchanged -F <filename> Use the file as the log message -l Do not recurse into subdirectories -m <message> Specify the log message -n Do not run checkout program specified in the administrative files -r <revision> Use this revision or symbolic tag -R Recurse into subdirectories Table 13 commit command options diff Display the differences between two versions of a file. By default the version in the sandbox is compared with the version in the repository from which it was originally copied. cvs diff [options] <filename> [<filename> …] Switch Description -D <date> Use most recent revision no later than <date> format diff format options -k <kflags> Keyword substitution mode -l Do not recurse into subdirectories -r <revision> Use this revision or symbolic tag -R Recurse into subdirectories Table 14 diff common command options Option Description -a Treat the files as text even if they are not --text -B Ignore blank lines --ignore-blank-lines -b Ignore changes in the amount of --ignore-space-change whitespace 98
Command Reference --binary Treat the file as binary, ignoring line breaks --brief Just check if the files differ -c Context output format, prints three lines of text for context -C <lines> Context output format with <lines> of --context=<lines> context -d Search more effectively for differences, --minimal showing up smaller changes -i Ignore case --ignore-case -N Treat new files as if an empty file was --new-file present in the other directory -n Output in RCS format --rcs -p Show the name of the function containing --show-c-function the difference -s Show when two files are identical -report-identical-files -t Expand tabs to spaces in output --expand-tabs -u Unified output format -U <lines> Unified output format using <lines> of --unified[=<lines>] context -w Ignore whitespace --ignore-all-space -w <columns> Number of columns for side by side mode --width <columns> -Y In the output put a tab after the indicator --initial-tab character -y Show the files side by side --side-by-side Table 15 diff formatting options edit Sets a file to be writeable and sends a message to all users who are watching this file. cvs edit [options] <filename> [<filename> …] Option Description -a <action> Specify the action being performed -l Do not recurse -R Recurse into subdirectories Table 16 edit command options 99
Configuration Management with CVS Action Description all All these actions commit Changes have been committed edit A file is being edited none Default for edit unedit Changes have been removed Table 17 edit actions editors Displays a list of users who have used the edit command on the files specified. cvs editors [options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories Table 18 editors command options export Exports the specified files from the repository, without creating the CVS administrative files and directories. This can be used for preparing a package of files to transfer to another CVS system. cvs export [options] <filename> [<filename> …] Option Description -D <date> Export the most recent revision no later than <date> -d <directory> Used <directory> instead of the module name -f Include files not tagged with the specified tag, or not present on the selected date -k <kflags> Control keyword substitution -l Do not recurse -n Do not run any checkout programs -N Do not shorten directory paths -R Recurse into subdirectories -r <revision> Export the specified revision number or symbolic tag Table 19 export command options help Display the help messages. cvs help gives a list of commands, while cvs --help <command> gives help on a specific command. 100
Command Reference history Shows the history of actions taken on the specified file. This feature is only available if history is being collected by having the history file in the CVSROOT directory of the repository: cvs history [options] <filename> [<filename> …] Option Description -a Show history for all users -b <string> Show history back to a record containing <string> in the module name, file name or repository path -c Report commits -e Report everything -f <filename> Show the most recent action on <filename> -l Show the last action -m <modulename> A full report on <modulename> -n <modulename> Report the last action on <modulename> -o Report on checked out modules -p <repository> Report on a repository directory -t <tagname> Report on history since <tagname> was last added to the history file -T Report all symbolic tags -u <username Report all actions performed by <username> -w History for the current working directory -x <type> Report activities of type <type> -z <timezone> Report times for timezone <timezone> Table 20 history commandoptions Type Description A A file was added for the first time C A merge was required, but conflicts were detected E An export was performed F A release was made G An automatic merge was performed M A file was modified O A file was checked out R A file was removed T A symbolic tag was applied U A working file was copied from the repository W The working copy of a file was deleted 101
Configuration Management with CVS Table 21 history output import Imports a directory tree into the repository as a new module. cvs import [Options] <modulename> <vendor tag> <release tag> Multiple release tags may be specified. Option Description -b <branch> Import to a vendor branch -d Imports a file using the file’s modification date and time rather than the current date and time. Only available when CVS is working in local mode -I <pattern> Ignore files matching <pattern> -k <kflags> Control keyword expansion -m <message> Sets the log message -W <wrapper> Specify files to be filtered during input Table 22 import command options Information displayed by the import command uses the following codes: Status Description C Changed The file existed in the repository and the imported file was different, requiring a merge I Ignored Import was instructed to ignore the file by one of the cvsignore files L Link Symbolic links are always ignored N New The file was new and has been added to the repository U Update The file existed in the repository and the imported file was identical Table 23 import output log Display an activity log for specified files. cvs log [Options] <filename> [<filename> …] Option Description -b List revisions on the default branch -d <datespec> Report on the date or date range(s) -h Output the header only -N Suppress the output of tags -R Print RCS filename only -r <revisionspec> Report on the revisions specified -s <state> Report only revisions in <state> 102
Command Reference -t Output only the header and description -w<username>[,<username>, …] Report only checkins by these users. There may not be a space between –w and its arguments Table 24 log command options Date Specification Description date1<date2 or date2>date1 Revisions between date1 and date2 exclusive date1<=date2 or date2>=date1 Revisions between date1 and date2 inclusive <date or date> Revisions before date <=date or date >= Revisions before or on date date< or >date Revisions after date date<= or >=date Revisions on or after date date Most recent revision before or on date Table 25 log command date specification Revision Specification Description revision1:revision2 Revisions from revision1 to revision2 inclusive :revision Revisions from the beginning of the branch to revision inclusive revision: Revisions from revision to the end of the branch inclusive branch All revisions in the branch branch1:branch2 All revisions on all branches between branch1 and branch2 inclusive branch. The last revision on branch Table 26 log command revision specification login Validates the username and requires a password. The user’s password is stored in the ~/.cvspass so that the client can provide this when required. This command is only applicable to CVS operation where a password server or other authentication method is running. cvs [Options] login Typically the options field would specify the connect string for the repository. logout This ends the user’s session and removes his password from the ~/.cvspass file cvs logout rdiff 103
Configuration Management with CVS Runs a diff on two files or sets of files to produce a standard format patch file for updating one set of files to another. cvs rdiff [Options] <filename> [<filename> …] Option Description -c Context diff format (default) -D <date> Specify the dates for revisions -f Include files not containing the tag, or not present on the specified date -l Do not recurse -R Recurse into subdirectories -r <revision> Specify the revisions to compare -s Output a summary of changed files rather than a patch file -t Show differences between the two most recent revisions -u Unidiff format Table 27 rdiff command options release Release can be used to reverse a checkout. Although not strictly necessary, as CVS allows by default multiple users to check out files, using release has the advantage of making a record in the history file, and verifying the status of all files in the sandbox, before optionally deleting the files. cd <parentdirectory> cvs release [Option] <directory> Option Description -d Delete the sandbox Table 28 relese command option Before performing the optional delete, the release command checks the status of all files in the sandbox against the repository. Thus any commit actions which were intended, but were forgotten are flagged. Release prints a report with the following codes against each file specified Code Description A A file has been added but not committed to the repository M The working copy of the file has been modified U A newer version of the file exists in the P repository R A file has been removed but the remove has not been committed ? A file is present in the sandbox, but not in the repository 104
Command Reference Table 29 release command output remove Remove one or more files from the repository. The remove is not actually performed until the files are committed. cvs remove [Options] <filename> [<filename> …] Option Description -f Delete the file from the sandbox -l Do not recurse -R Recurse into subdirectories Table 30 remove command options rtag Set a symbolic tag on a specified revision of a set of files: cvs rtag [Options] <tag> <filename> [<filename> …] This command operates solely on files in the repository, and does not examine files in the sandbox. Option Description -a Search the attic for removed files containing the tag -b Use a branch tag -d Delete the tag -D <date> Specify the dates for tagging -F Force , causes an existing tag to be moved to the new revision -f Include files not containing the tag, or not present on the specified date -l Do not recurse -n Do not run any tag program -R Recurse into subdirectories -r <revision> Specify the revision for tagging Table 31 rtag command options status Show the status of the selected files: cvs status [Options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories -v Verbose, includes tag information Table 32 status command options 105
Configuration Management with CVS tag Assign a symbolic tag to the revisions of files in the current sandbox: cvs tag [Options] <filename> [<filename> …] Option Description -b Use a branch tag -c Check that files in the sandbox have not been modified without a commit -d Delete the tag -D <date> Specify the dates for tagging -F Force , causes an existing tag to be moved to the new revision -f Include files not containing the tag, or not present on the specified date -l Do not recurse -R Recurse into subdirectories -r <revision> Specify the revision for tagging Table 33 tag command options unedit Abandon file edit and make the file read-only, notifying watchers. cvs unedit [Options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories Table 34 unedit command options update Update the working copy of files in the sandbox, merging changes from the repository: cvs update [Options] <filename> [<filename> …] Option Description -A Reset sticky tags -d Create and update new directories -D <date> Use most recent revision no later than date -f Include most recent version of files where the tag does not exist, or the file did not exist on <date> -I <pattern> Ignore files matching this pattern -j <revision> Merge changes between the two revisions -k <kflags> Control keyword expansion -l Do not recurse -p Check out files to standard output -P Prune empty directories -R Recurse into subdirectories 106
Command Reference -r <revision> Retrieve the revision or tag specified -W <wrapper> Specify files to be filtered during input Table 35 update command options update reports the status of the files examined with a status code. Status Description ? The file was present in the sandbox, but not in the repository A Added No action taken, cvs add has been performed but the file has not been committed C Conflict The sandbox copy of the file has been modified, but there was a conflict merging it with the latest version in the repository M Modified The sandbox copy was modified, and was merged successfully with the repository version P Patched The file was successfully updated, but the server used a patch R Removed No action taken because cvs remove had been run on the file, but the file had not been committed U Updated The file was updated Table 36 update command output watch The watch command allows a developer to be informed automatically if another user takes any action on a set of files: cvs watch [Options] <filename> [<filename> …] Option Description on Turn on watching off Turn off watching add Start watching files remove Stop watching files -a <action> Action to watch for -l Do not recurse -R Recurse into subdirectories Table 37 watch command options The actions possible are: Action Description all All these actions commit Changes have been committed edit A file is being edited 107
Configuration Management with CVS none Default for edit unedit Changes have been removed Table 38 watch command actions watchers Displays a list of the users watching the files specified: cvs watchers [Options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories Table 39 watchers command options keyword substitution flags Flag Description -kkv Default form of keyword substitution -kkvl Add locker’s name, not normally used in CVS -kk Omit the value field. useful for displaying differences -ko Generate the keyword string as it would have appeared n the original file before it was checked in -kb As –ko but also suppress line ending translation. Required for binary files -kv generate only the value of the keyword, omitting the keyword itself Table 40 keyword substitution flags Admin Commands admin CVS also accepts adm or rcs for this command. If a cvsadmin user group exists, these commands will only be available to the group. Various administrative tasks are performed with this command. cvs admin [Options] [data] Option Description -b <revision> Set the default branch -k <kflags> Set default keyword substitution mode -L Enable strict locking. -l <revision> Lock the specified revision -m<revision>:<message> Set a revision’s log message -n<name>[:[<revision>]] Give the revision specified the symbolic name -N<name>[:[<revision>]] Give the revision specified the symbolic 108
Command Reference name, and move the name if it exists --o<range> Delete the revisions specified -q Quiet mode -s<state>[:<revision>] Change the state of a revision -t<filename> Set descriptive text in the RCS file specified -t-<string> Set descriptive text in the RCS file specified to <string> -U Disable strict locking -u<revision> Unlock the specified revision Table 41 admin command options init Create a new repository: cvs init –d <root directory> kserver Starts CVS in kserver mode pserver Starts cvs in server mode 109
Configuration Management with CVS Data Formats <tagname> [a-z,A-Z] *[a-z,A-Z,0-9,-,_] <branchname> The first character must be alphabetic, followed by any number of alphanumeric characters, together with the special characters ‘-‘ and ‘_’ <date> Although CVS recognises many date formats, the only two officially supported formats are ISO 8601, and RFC 1123 (email). ISO 8601: YYYY-MM-DD HH:MM [<timezone>] RFC 1123: 11 Nov 2002 Because these formats include spaces, dates normally need to be enclosed in quotation marks. <revision> An even number of digits separated by the ‘.’ character. Internally there may be revisions with an odd number of digits (for example representing a branch). Example: 4.1.7.5 <modulename> A valid directory name. This may differ between Windows and Unix systems. The space character in a pathname is problematic and should be avoided. <filename> A valid filename. This is system dependent, and spaces should be avoided. <kflags> Options for keyword expansion. The most common is for the treatment of binary files to suppress keyword expansion and line end conversion: -kb Table 42 Data Formats 110
Command Reference Other Date Formats Although deprecated, these date formats are also supported, but may disappear in future versions. Format Description mm/dd/yy The U.S. date format month/day/year. This should be avoided as it is ambiguous in other countries. yesterday Although these formats might be useful for last Monday displaying a diff, their use for checkouts 10 minutes ago and commits can easily lead to erroneous 1 hour ago results. The strings need to be quoted to be 3 days ago interpreted correctly. 5 years ago Table 43 Other Date Formats Alternate Command Names Because of the historical evolution of SCCS, RCS and CVS, some commands have alternative names. Command Alternatives add ad, new annotate ann checkout co, get commit ci, com diff dif, di export ex, exp history hi, his import im, imp login logon, lgn log rlog, lo rdiff patch, pa release rel, re delete remove, rm rtag rfreeze, rt status stat, st tag freeze, ta update upd, up admin adm, rcs Table 44 Alternate Command Names 111
Configuration management with cvs and open source tools
Customisation C Appendix C - Customisation Various administrative files offer options to run programs or scripts on the occurrence of certain actions. CVS provides certain arguments to these routines, as shown below. modules Option Action Arguments -i commit module name -e export repository directory -o checkout module name -t tag module name, symbolic tag -u updated repository directory Table 45 modules file options Note that for checkout, export and rtag the program specified is run on the server (assuming that CVS is running in client/server mode), while for commit and update the program is run on the local machine. Programs run on the server are searched for in the path. Changes to the commit and update programs set in the modules file will not take effect until a new copy of the source affected is checked out, as the program names are copied into the CVS directory of the working copy on the client. The programs are first searched for in the working copy of the source, then in the path. On the client the programs are executed from the top level directory of the module. All the programs specified in the modules file run after the successful completion of the action. 113
Configuration Management with CVS commitinfo Commitinfo allows the system administrator to specify scripts or programs to run before a file may be committed to the repository, the program being selected by a pattern match on the filename. Specification Arguments <regexp>, ALL, DEFAULT repository directory, filenames Table 46 commitinfo file options loginfo On a commit the log information can be directed to a program through the loginfo file. The information sent to the program may be selected from the filename, pre-commit and post-commit version numbers, using any or all of the format string %{sVv}.Loginfo programs run on the server in client/server mode. Specification Arguments <regexp>, ALL, DEFAULT repository directory, filenames and versions as selected, enclosed in quotes Table 47 loginfo file options verifymsg When committing a file to the repository a script may be run to verify that the required information has been supplied in the log message. The program runs on the server in client/server mode. Specification Arguments <regexp>, DEFAULT path to log message template file Table 48 verifymsg file options 114
Common Tasks D Appendix D - Common Tasks In the following examples the action taken by CVS often relies on the current working directory to supply some of its arguments. Optionally the commands could be run from a higher level directory, specifying the files or modules to act on. Add a directory to a module cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # mkdir <directory name> cvsuser@oppenheimer work/<modulename> # cvs add <directory name> cvsuser@oppenheimer work/<modulename> # cvs commit [<directoryname>] Add a file to a module cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs add <filename> cvsuser@oppenheimer work/<modulename> # cvs commit [<filename>] Back out a change cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –j 1.3 –j 1.2 <filename> cvsuser@oppenheimer work/<modulename> # cvs commit [<filename>] Checkout a branch cvsuser@oppenheimer work # cd <modulename> 115
Configuration Management with CVS cvsuser@oppenheimer work/<modulename> # cvs update –r <tagname> [<modulename>] or: cvsuser@oppenheimer work # cvs checkout –r <tagname> <modulename> Checkout a module cvsuser@oppenheimer work # cvs checkout <modulename> Commit a module cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs commit or: cvsuser@oppenheimer work # cvs commit <modulename> Create a branch cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs tag –b <tagname> or: cvsuser@oppenheimer work # cvs rtag –b <tagname> <modulename> Exclusive lock cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs admin –l <filename> Merge a branch cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –j <branchname> cvsuser@oppenheimer work/<modulename> # cvs commit Remove a file cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs remove <filename> cvsuser@oppenheimer work/<modulename> # cvs commit Remove a directory A directory is removed by removing all its files. To tidy up the working directory: cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –P 116
Common Tasks Return the working directory to the current revision cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –A –d -P Tag a Release cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs tag <tagname> cvsuser@oppenheimer work/<modulename> # cvs commit or: cvsuser@oppenheimer work # cvs rtag –r <tagname> <modulename> Update a working directory cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –d -P 117
Configuration management with cvs and open source tools
Resources E Appendix E – Resources Bugzilla http://www.bugzilla.org cervisia http://cervisia.sourceforge.net/ Cook http://www.canb.auug.org.au/~millerp/cook/cook.html cvsadmin http://freshmeat.net/projects/cvsadmin/ CSDiff http://www.componentsoftware.com/products/csdiff/ CVS http://www.cvshome.org/ CVSFAQ http://www.loria.fr/~molli/fom-serve/cache/1.html CVSGraph http://www.akhphd.au.dk/~bertho/cvsgraph/ CVSIn http://sourceforge.net/projects/cvsin/ cvsmenu.vim http://vim.sourceforge.net/script.php?script_id=58 cvsmonitor http://search.cpan.org/author/ADAMK/Bundle-CVSMonitor-0.6/ CVSNT http://www.cvsnt.org/ cvspwd http://www.loria.fr/cgi-bin/molli/wilma.cgi/rel.987302735.html cvsreport http://cvsreport.sourceforge.net/ cvstrac http://www.cvstrac.org/ cvstrac Windows http://cvs.cvstrac.org/wiki?p=CvstracOnWindows 119
Configuration Management with CVS CVSup http://www.cvsup.org/ CVSWeb http://www.freebsd.org/projects/cvsweb.html CVSWebclient http://sourceforge.net/projects/cvswebclient/ CVSWebedit http://search.cpan.org/author/MRJC/cvswebedit-v2.0b1/ CVSZilla http://homepages.kcbbs.gen.nz/~tonyg/ dgdeletelocks.pl http://www.devguy.com/fp/cfgmgmt/cvs/ dgfindlocks.pl http://www.devguy.com/fp/cfgmgmt/cvs/ dgfixcvs.pl http://www.devguy.com/fp/cfgmgmt/cvs/ findlocks.pl http://www.devguy.com/fp/cfgmgmt/cvs/ Freepository https://www.freepository.com/ gcvs http://www.wincvs.org/ GNU Diffutils http://www.gnu.org/software/diffutils/diffutils.html Jam http://www.perforce.com/jam/jam.html lincvs http://www.lincvs.org/ mirror http://sunsite.doc.ic.ac.uk/packages/mirror/ Odin ftp: //ftp.cs.colorado.edu/pub/distribs/odin OpenSSH http://www.openssh.com/ pcl-cvs http://www.cvshome.org/cyclic/cvs/soft-pcl.html rdist http://www.magnicomp.com/rdist/ rsync http://rsync.samba.org/ sup http://gd.tuwien.ac.at tkdiff http://www.accurev.com/free/tkdiff/ TortoiseCVS http://www.tortoisecvs.org/ ViewCVS http://viewcvs.sourceforge.net/ WinCVS http://www.wincvs.org/ 120
GNU Free Documentation Licence F Appendix F – GNU Free Documentation Licence Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0 PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals 121
Configuration Management with CVS providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". 122
GNU Free Documentation Licence Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY 123
Configuration Management with CVS If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: • A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. • B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. 124
GNU Free Documentation Licence • C. State on the Title page the name of the publisher of the Modified Version, as the publisher. • D. Preserve all the copyright notices of the Document. • E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. • F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. • G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. • H. Include an unaltered copy of this License. • I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. • J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. • K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. • L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. • M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. • N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. • O. Preserve any Warranty Disclaimers. 125
Configuration Management with CVS If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS 126
GNU Free Documentation Licence You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this 127
Configuration Management with CVS License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. 128
Index Index branchname, 112 . Bugzilla, 87, 121 Build Systems, 73 .# files, 55 Cook, 75 .cvsignore, 33 Jam, 75 .cvsrc, 35 Make, 75 .cvswrappers, 34 Odin, 75 A C Abandoning Changes, 52 cervisia, 121 add, 99 Cervisia, 69 Add a directory, 117 Changes, 45 Add a file, 117 checkin, 2 Adding, 41 Checkin.prog, 32 Adding and Removing Files, 41 checkout, 2, 99 admin, 110 Checkout a branch, 118 Admin Commands Checkout a module, 118 admin, 110 Checkout –p, 52 init, 111 checkoutlist, 24 kserver, 111 Client Command Options, 98 pserver, 111 Client Commands Administrative Tasks, 89 add, 99 Backup, 89 annotate, 99 CVS Defaults, 90 checkout, 99 Reset the Default Branch, 90 commit, 100 Tidying up the Repository, 89 diff, 100 Alternate Command Names, 113 edit, 101 annotate, 51, 99 editors, 102 Anonymous CVS, 83 export, 102 help, 102 B history, 103 Back out a change, 117 import, 104 Backing Out, 61 log, 104 Backup, 89 login, 105 Base, 30 logout, 105 Baserev, 30 rdiff, 105 Binary Files, 53 release, 106 branch, 2 remove, 107 Branch, 59 rtag, 107 Branches, 57 status, 107 129
Configuration Management with CVS tag, 108 cvsadmin, 93, 121 unedit, 108 CVSEDITOR, 34 update, 108 CVSFAQ, 121 watch, 109 cvsgraph, 77 watchers, 110 CVSGraph, 121 Client/Server Mode, 12 cvsignore, 25 Code Organisation, 7 CVSIn, 70, 121 Command Format, 37 cvsmenu.vim, 121 Command Reference, 97 cvsmonitor, 93, 121 Commands, 99 CVSNT, 121 commit, 2, 100 CVSNT Differences, 15 Commit a module, 118 cvspwd, 94, 121 commitinfo, 24, 116 cvsreport, 93, 122 Common Options, 97 CVSROOT, 34 Common Steps, 11 CVSROOT Files, 30 Common Tasks, 117 cvstrac, 122 Add a directory, 117 Cvstrac, 85 Add a file, 117 CVSup, 122 Back out a change, 117 CVSWeb, 93, 122 Checkout a branch, 118 CVSWebclient, 122 Checkout a module, 118 CVSWebedit, 122 Commit a module, 118 cvswrappers, 26 Create a branch, 118 CVSZilla, 88, 122 exclusive lock, 118 Merge a branch, 118 D Remove a directory, 119 Data Formats, 112 Remove a file, 119 branchname, 112 Return the working directory to the current revision, 119 date, 112 Tag a release, 119 Filename, 112 kflags, 112 Update a working directory, 119 modulename, 112 config, 25 revision, 112 Configuration, 5 conflict, 2 tagname, 112 Connection and Authentication, 17 date, 112 Development, 43 Cook, 75, 121 dgdeletelocks.pl, 94, 122 Create a branch, 118 dgfindlocks.pl, 94, 122 CSDiff, 79, 121 dgfixcvs.pl, 94, 122 Customisation, 115 Customised Logging, 51 diff, 79, 100 CVS, 121 Diff, 52 Diff and Merge CVS Defaults, 90 CSDiff, 79 CVS_PASSFILE, 35 GNU Diff Utilities, 81 CVS_RSH, 34 WinMerge, 80 CVS_SERVER, 35 xxdiff, 81 130
Index E Importing, 41 init, 111 edit, 101 Installation, 11 editinfo, 30 Introduction, 1 editors, 102 EMACS, 71 J Entries, 30 Entries.Backup, 31 Jam, 75, 122 Entries.Log, 31 Entries.Static, 31 K Environment Variables, 34, 95 Exclusive lock, 118 Kerberos 4, 20 Exclusive Locks, 54 Keyword Substitution, 53 export, 102 keyword substitution flags, 110 kflags, 112 kserver, 111 F filename, 112 L findlocks.pl, 94, 122 Freepository, 93, 122 lincvs, 122 Front Ends, 67 Lincvs, 70 Cervisia, 69 LockDir, 25 CVSIn, 70 log, 104 EMACS, 71 Log History, 49 gcvs, 68 LogHistory, 25 Lincvs, 70 login, 105 TortoiseCVS, 69 loginfo, 26, 116 WinCVS, 67 logout, 105 G M gcvs, 68, 122 Make, 75 Global Options, 97 merge, 2, 79 Glossary, 2 Merge a branch, 118 GNU Diff Utilities, 81 Merging, 60 GNU Free Documentation Licence, 123 mirror, 122 GSSAPI, 20 Mirror Sites, 63 modulename, 112 modules, 26, 115 H alias modules, 26 Hanging Locks, 32 regular modules, 27 head, 2 help, 102 N history, 26, 103 notify, 27 Notify, 31 I import, 104 131
Configuration Management with CVS O Secure Shell, 18 Server Option, 98 Odin, 75, 122 Sizing, 7 OpenSSH, 122 Source Distribution, 63 Other Date Formats, 113 status, 107 Status, 48 P Sticky Options, 54 passwd, 28 Strange Files, 55 Password Server, 17 sup, 122 pcl-cvs, 122 SystemAuth, 25 Planning for Installation, 5 Problem Tracking, 85 T Bugzilla, 87 tag, 108 Cvstrac, 85 Tag, 32 CVSZilla, 88 Tag a release, 119 pserver, 111 taginfo, 28 tagname, 112 R Tags, 38 rcsinfo, 28 Template, 32 rdiff, 105 The Vendor Branch, 61 rdist, 122 Tidying up the Repository, 89 readers, 29 Times and Timezones, 8 release, 106 tip, 2 Releases, 57 tkdiff, 122 Remote Shell, 18 TopLevelAdmin, 25 remove, 107 TortioseCVS, 69 Remove a directory, 119 TortoiseCVS, 122 Remove a file, 119 Troubleshooting, 13 repository, 2 trunk, 3 Repository, 21, 32 Typographical Conventions, 2 Setup, 39 Repository Files, 30 U Reset the Default Branch, 90 unedit, 108 Resources, 121 Unix Systems, 11 Return the working directory to the update, 108 current revision, 119 Update a working directory, 119 revision, 3, 112 Update.prog, 32 Revisions, 37, 57 User Environment, 33 Root, 31 users, 29 rsync, 122 Utilities, 93 rtag, 107 cvsmonitor, 93 cvspwd, 94 S cvsreport, 93 sandbox, 3 CVSWeb, 93 132
Index dgdeletelocks.pl, 94 W dgfindlocks.pl, 94 watch, 109 dgfixcvs.pl, 94 watchers, 110 findlocks.pl, 94 WinCVS, 67, 122 Freepository, 93 Windows Problems, 65 ViewCVS, 93 Windows Systems, 14 WinMerge, 80 V work area, 3 verifymsg, 28, 116 Working Copy, 43 ViewCVS, 93, 122 writers, 29 Visualising the Source Tree, 77 X xxdiff, 81 133

More Related Content

PDF
business - marketing, planning and strategy
Boni
 
PDF
Mathlab dsp a computer based approach solution manual - sanjit k mitra
Jesus Rodriguez Rascon
 
PDF
LIFE SKILLS BY ANURAG TYAGI CLASSES, GHAZIABAD
ANURAG TYAGI CLASSES (ATC)
 
PDF
Empower Connect11 Trend Flash
Empower MediaMarketing
 
PDF
I have a LinkedIn profile.. Now what?
LinkedIn
 
PDF
LinkedIn Introduction_SHRM WC 0309
LinkedIn
 
PPTX
Who is the digital you?
Tony Fish
 
PDF
Incitrio: State Education Editors Conference 2009
Angela Hill
 
business - marketing, planning and strategy
Boni
 
Mathlab dsp a computer based approach solution manual - sanjit k mitra
Jesus Rodriguez Rascon
 
LIFE SKILLS BY ANURAG TYAGI CLASSES, GHAZIABAD
ANURAG TYAGI CLASSES (ATC)
 
Empower Connect11 Trend Flash
Empower MediaMarketing
 
I have a LinkedIn profile.. Now what?
LinkedIn
 
LinkedIn Introduction_SHRM WC 0309
LinkedIn
 
Who is the digital you?
Tony Fish
 
Incitrio: State Education Editors Conference 2009
Angela Hill
 

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

PDF
Noam Chomsky-Failed States
Yousef al-Khattab
 
PDF
CiA Human Resource Exploitation Training Manual (1983) Aka Honduras Manua...
Emillion Mihoff
 
PDF
Barron's mastering spanish
byollog
 
PDF
Business the power of strategy innovation-a new way of linking creativity a...
Batjargal Shasnaabadraa
 
PDF
Www empowernetwork com_ribeiro_blog_tips_on_using_personal_d (1)
Rogerio Galiano
 
PDF
Learn how to take most out of personal development!
Rogerio Galiano
 
PDF
Article marketing course
VaibhavHande4
 
PDF
eCairn List of Tribes
eCairn Inc.
 
PDF
Article marketingcourse
Alfredo Luis Varela
 
PDF
List of Virtual Communities
Fernando Rodriguez
 
PDF
List of Virtual Communities
eCairn Inc.
 
PDF
How to build your private practice s plemmons
Michelle Zadrozny, LMSW
 
PDF
Advanced Internet Marketing November 2010
kevindean9737
 
PDF
Successful business marketing
informationguide
 
PDF
Microsoft power point goal setting system
puneet_jain
 
PDF
19633268 economics-principles-of-financial-economics-2
Jigmee
 
PDF
Increases your company output through corporate training
GIO
 
PDF
Online Marketing
clevermethod
 
PPTX
Skills For Successful Life
Kaushik_Sarkar
 
PPTX
Skills For Successful Life
Kaushik_Sarkar
 
Noam Chomsky-Failed States
Yousef al-Khattab
 
CiA Human Resource Exploitation Training Manual (1983) Aka Honduras Manua...
Emillion Mihoff
 
Barron's mastering spanish
byollog
 
Business the power of strategy innovation-a new way of linking creativity a...
Batjargal Shasnaabadraa
 
Www empowernetwork com_ribeiro_blog_tips_on_using_personal_d (1)
Rogerio Galiano
 
Learn how to take most out of personal development!
Rogerio Galiano
 
Article marketing course
VaibhavHande4
 
eCairn List of Tribes
eCairn Inc.
 
Article marketingcourse
Alfredo Luis Varela
 
List of Virtual Communities
Fernando Rodriguez
 
List of Virtual Communities
eCairn Inc.
 
How to build your private practice s plemmons
Michelle Zadrozny, LMSW
 
Advanced Internet Marketing November 2010
kevindean9737
 
Successful business marketing
informationguide
 
Microsoft power point goal setting system
puneet_jain
 
19633268 economics-principles-of-financial-economics-2
Jigmee
 
Increases your company output through corporate training
GIO
 
Online Marketing
clevermethod
 
Skills For Successful Life
Kaushik_Sarkar
 
Skills For Successful Life
Kaushik_Sarkar
 
Ad

Recently uploaded (20)

PPTX
Cell Types and Its function , kingdom of life
ClaireMangundayao1
 
PDF
OBE - B.A.(HON'S) IN INTERIOR ARCHITECTURE -Ar.MOHIUDDIN.pdf
ArchitectAFMMohiuddi
 
PDF
ANTIBIOTICS.pptx.pdf………………… xxxxxxxxxxxxx
HakHe
 
PDF
Chinmaya Tiranga quiz Grand Finale.pdf
Nitin Suresh
 
PDF
A systematic review of self-coping strategies used by university students to ...
CleeveMoralde1
 
PDF
RMMM.pdf make it easy to upload and study
sajedul2
 
PDF
O7-L3 Supply Chain Operations - ICLT Program
labyankof
 
PPTX
Microbial diseases, their pathogenesis and prophylaxis
DevlinaSengupta
 
PDF
VCE English Exam - Section C Student Revision Booklet
jpinnuck
 
PDF
Chapter 2 Heredity, Prenatal Development, and Birth.pdf
MarjorieLopezTiu
 
PDF
Computing-Curriculum for Schools in Ghana
abigailanane203
 
PPTX
Final Presentation General Medicine 03-08-2024.pptx
ZaheerAhmad228692
 
PDF
The Lost Whites of Pakistan by Jahanzaib Mughal.pdf
jahanzaibmughal6
 
PDF
3rd Neelam Sanjeevareddy Memorial Lecture.pdf
Academy of Grassroots Studies and Research of India (AGRASRI)
 
PDF
Anesthesia in Laparoscopic Surgery in India
mohitsuren827
 
PPTX
Presentation on HIE in infants and its manifestations
joghikamal786
 
PDF
102 student loan defaulters named and shamed – Is someone you know on the list?
Kweku Zurek
 
PDF
Supply Chain Operations Speaking Notes -ICLT Program
labyankof
 
PPTX
master seminar digital applications in india
ananyaray35
 
PDF
GENETICS IN BIOLOGY IN SECONDARY LEVEL FORM 3
ElishamichaelSamwel
 
Cell Types and Its function , kingdom of life
ClaireMangundayao1
 
OBE - B.A.(HON'S) IN INTERIOR ARCHITECTURE -Ar.MOHIUDDIN.pdf
ArchitectAFMMohiuddi
 
ANTIBIOTICS.pptx.pdf………………… xxxxxxxxxxxxx
HakHe
 
Chinmaya Tiranga quiz Grand Finale.pdf
Nitin Suresh
 
A systematic review of self-coping strategies used by university students to ...
CleeveMoralde1
 
RMMM.pdf make it easy to upload and study
sajedul2
 
O7-L3 Supply Chain Operations - ICLT Program
labyankof
 
Microbial diseases, their pathogenesis and prophylaxis
DevlinaSengupta
 
VCE English Exam - Section C Student Revision Booklet
jpinnuck
 
Chapter 2 Heredity, Prenatal Development, and Birth.pdf
MarjorieLopezTiu
 
Computing-Curriculum for Schools in Ghana
abigailanane203
 
Final Presentation General Medicine 03-08-2024.pptx
ZaheerAhmad228692
 
The Lost Whites of Pakistan by Jahanzaib Mughal.pdf
jahanzaibmughal6
 
3rd Neelam Sanjeevareddy Memorial Lecture.pdf
Academy of Grassroots Studies and Research of India (AGRASRI)
 
Anesthesia in Laparoscopic Surgery in India
mohitsuren827
 
Presentation on HIE in infants and its manifestations
joghikamal786
 
102 student loan defaulters named and shamed – Is someone you know on the list?
Kweku Zurek
 
Supply Chain Operations Speaking Notes -ICLT Program
labyankof
 
master seminar digital applications in india
ananyaray35
 
GENETICS IN BIOLOGY IN SECONDARY LEVEL FORM 3
ElishamichaelSamwel
 
Ad

Configuration management with cvs and open source tools

  • 1. 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
  • 2. Configuration Management with CVS and Open Source Tools Derek Clifford
  • 3. 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
  • 5. 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
  • 6. Configuration Management with CVS 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
  • 7. 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
  • 8. Configuration Management with CVS 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
  • 9. 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
  • 11. 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
  • 12. Configuration Management with CVS 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
  • 13. 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
  • 15. Planning for Installation 1 Planning for Installation 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
  • 16. Configuration Management with CVS 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
  • 17. Planning for Installation 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
  • 18. Configuration Management with CVS 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
  • 19. Planning for Installation 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
  • 20. Configuration Management with CVS 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
  • 21. 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
  • 22. Configuration Management with CVS #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
  • 23. 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
  • 24. Configuration Management with CVS 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
  • 25. 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
  • 27. Connection and Authentication 3 Connection and Authentication 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
  • 28. Configuration Management with CVS 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
  • 29. Connection and Authentication 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
  • 30. Configuration Management with CVS 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
  • 31. 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
  • 32. Configuration Management with CVS 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
  • 33. 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
  • 34. Configuration Management with CVS 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
  • 35. 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
  • 36. Configuration Management with CVS 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
  • 37. 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
  • 38. Configuration Management with CVS (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
  • 39. 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
  • 40. Configuration Management with CVS 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
  • 41. 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
  • 42. Configuration Management with CVS 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
  • 43. The User Environment 5 The User Environment 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
  • 44. Configuration Management with CVS 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
  • 45. The User Environment 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
  • 47. 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
  • 48. Configuration Management with CVS 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
  • 49. Setting up the Repository 7 Setting up the Repository 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
  • 50. Configuration Management with CVS 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
  • 51. Setting up the Repository 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
  • 52. Configuration Management with CVS 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
  • 53. Development 8 Development Obtaining a Working Copy The first task of a developer who wishes to make some modifications to the code is to check out a working copy of the code from the repository. The command: cvs checkout <modulename> will achieve this below the current working directory. Thus the command: cvsuser@bohr ~/work# cvs checkout cvssources results in the structure shown in Figure 2 43
  • 54. Configuration Management with CVS Screenshot 2 Checking out a module Normally, however, in a medium or large project a developer will work on only a small part of the code. Checking out the top level module defined by the import command may result in the developer having to descend the file tree by several levels to access the code he is interested in. The modules file can be used to simplify the structure of the individuals work area. The action of regular and alias modules is illustrated in the following examples. The modules file has been set up to contain the commands: docmodule cvssources/doc docalias –a cvssources/doc Now the action of a checkout is only to retrieve the files in the /cvssources/doc directory, but cvsuser@bohr ~/work# cvs checkout docmodule creates the files directly below a directory docmodule (Screenshot 3), while: cvsuser@bohr ~/work# cvs checkout docalias preseves the directory structure of the project (Screenshot 4), although the directories not specified in the alias definition will remain empty. In either case CVS keeps track of the actual place in the repository from which the files were extracted, so the commit command will work correctly. Thus careful consideration of the contents of the modules file can greatly simplify the view of the code presented to the developer. Files which are checked out are marked read/write for the owner, unless the global cvs option –r is used. If a file is being watched it will automatically be set read-only on checkout to enforce the use of the edit command to notify the watchers. 44
  • 55. Development Screenshot 3 Checking out a subdirectory with a regular module Screenshot 4 Checking out a subdirectory with an alias module Making Changes A developer may edit one or many files. rebuild the subproject and test the program unit. Firstly, because CVS allows multiple users to update the same files simultaneously, some of the files which the developer wants to edit may be set read-only, because another user has asked cvs to report activity on the file by setting up a watch on the file. The way to overcome this is not to use chmod, but rather the cvs edit command. This 45
  • 56. Configuration Management with CVS ensures that anyone else interested in changes to that file will be notified. Equally, if the developer is interested in who else may be editing the file, the cvs editors command may be used. This command can only list those users who have run the edit command on the file. So if the file cvs.texinfo in the doc subdirectory is being watched by cvsadmin, the command: cvsuser@bohr: ~/work/docmodule> cvs edit cvs.texinfo will notify cvsadmin that cvsuser is editing the file cvs.texinfo, and cvsadmin may search for all editors of the file with: cvsadmin@oppenheimer:~/work/cvssources/doc> cvs editors cvs.texinfo cvs.texinfo cvsuser Wed Nov 13 13:06:06 2002 GMT oppenheimer /home/cvsuser/work/docmodule Notification that a file is being edited is usually performed by mail, which requires the administrative file notify to be set up. Usually the notify file is set up with a single line: All mail %s –s “CVS Notification” CVS replaces the placeholder %s with the username. If the recipient’s mailbox is on another machine the users file must be set up to map the username to his email address: cvsadmin cvsadmin@oppenheimer A typical watch message is in the format: From cvsuser@oppenheimer.mlc Thu Nov 14 10:39:21 2002 Date: Thu, 14 Nov 2002 10:39:21 GMT From: cvsuser@oppenheimer.mlc To: cvsadmin@oppenheimer.mlc Subject: CVS notification cvssources/doc cvs.texinfo --- Triggered edit watch on /usr/local/cvs/cvssources/doc By cvsuser Watches are set up with the cvs watch command, and a developer may watch for the specific actions edit, commit, unedit and all. The watch command requires two separate actions, firstly to turn watching on (or off) for certain files: cvs watch on <filename> which causes the file to be watched, and for checkouts of this file to be made read-only, and secondly to request notification on certain actions: cvs watch add –a edit <filename> Here the current user will be notified if anyone who has checked out the file uses the edit command to make the file writeable. 46
  • 57. Development Finally, when a developer has completed the changes and unit tested the program, the code must be restored to the repository. This is performed with the commit command, but as CVS allows many users to be working on the same file simultaneously, a situation may arise where another developer has modified the same file and checked the file back in before the current user. If the checkin were allowed to proceed, the original modifications would be lost. The normal procedure therefore is to precede the commit with an update command, to attempt to merge any changes already applied in the repository with the working copy in the user’s directory. If the user forgets this procedure, and attempts to commit a file which has already been updated, the system will not check the file in, but rather warn the user that an update is necessary. cvs commit: Examining . cvs server: Up-to-date check failed for `cvs.texinfo' cvs [server aborted]: correct above errors first! cvs commit: saving log message in /tmp/cvsosj1bG When the user runs the update command, CVS will report on the status of the files: cvsuser@bohr:~/work/docmodule> cvs update cvs server: Updating . RCS file: /usr/local/cvs/cvssources/doc/ChangeLog,v retrieving revision 1.1.1.1 retrieving revision 1.2 Merging differences between 1.1.1.1 and 1.2 into ChangeLog M ChangeLog M cvs.texinfo Here the cvs update command indicates that the updated files in the repository have been successfully merged with the sandbox files. It is possible, however, that the update command will fail: cvsuser@bohr :~/work/docmodule >cvs update cvs server: Updating . RCS file: /usr/local/cvs/cvssources/doc/ChangeLog,v retrieving revision 1.1.1.1 retrieving revision 1.2 Merging differences between 1.1.1.1 and 1.2 into ChangeLog rcsmerge: warning: conflicts during merge cvs server: conflicts found in ChangeLog C ChangeLog In this case an automatic merge was not possible, as the same line in both revisions had been changed. Here the developer must resolve the conflicts himself. CVS will have flagged the conflict in the user’s working copy of the file, in a standard diff format: <<<<<<< ChangeLog 2001-04-24 Derek Price <dprice@collab.net> ======= 47
  • 58. Configuration Management with CVS 2001-04-28 Derek Price <dprice@collab.net> >>>>>>> 1.3 When the user has resolved the conflict, the files can be committed: cvsuser@bohr:~/work/docmodule> cvs commit cvs commit: Examining . Checking in ChangeLog; /usr/local/cvs/cvssources/doc/ChangeLog,v <-- ChangeLog new revision: 1.4; previous revision: 1.3 done Checking in cvs.texinfo; /usr/local/cvs/cvssources/doc/cvs.texinfo,v <-- cvs.texinfo new revision: 1.3; previous revision: 1.2 done Small changes which can be made quickly are easy to deal with, but there are cases where code will be checked out and remain under development for longer periods. In this case it can be useful to check on what actions have taken place on a file, and to find the differences between versions of files. Three mechanisms are available for tracking changes, the history file and the diff and status commands. Status The status command reports on files in the user’s work area, and compares them to the latest revision in the repository. cvsuser@oppenheimer:~/work/docmodule> cvs status ChangeLog ============================================================ File: ChangeLog Status: Up-to-date Working revision: 1.4 Repository revision: 1.4 /usr/local/cvs/cvssources/doc/ChangeLog,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) Status may report the state of the file as: Up to date The file matches the most recent version in the repository for the current branch. Locally modified The file has been edited locally, but has not yet been committed. Locally added The file has been added with the cvs add command, but not yet committed. 48
  • 59. Development Locally removed The file has been removed with the cvs remove command, but the remove has not yet been committed. Needs checkout The file in the repository has been modified since the file was checked out, and an update is needed. Needs patch The file in the repository has been modified since the file was checked out, and an update is needed. CVS will do this with a patch. Needs merge The file has been modified, but another user has committed changes to the repository. A merge will be required to reconcile the changes. File had conflicts on merge A previous update had failed because conflicts were detected. The merge must be made manually. Unknown The file exists in the work area, but not in the repository. Status also lists the revision which was checked out, and the current revision in the repository, together with any sticky options associated with the file. The Log History The types of action which are logged in the history file are set up in the administrative file config. The option is set by: LogHistory=[T|O|F|E|W|G|C|M|A|R|all] where the string is a concatenation of the options required, or the word all. The meaning of the options is shown in Table 4 Option Description A File added C Collisions detected during merge E export F release G Successful merge M File modified O checkout R File removed T rtag U Working file copied from repository W Working file deleted during update 49
  • 60. Configuration Management with CVS Table 4 History Logging Options Information logged in the history file can be retrieved with the history command. It is not sensible to write scripts to process the history file directly, as the format of the file is undocumented, and may change in later versions. By default the history command only reports on actions performed by the current user, but this may be extended to cover all users with the –a switch. The information returned by the history command is rather terse: cvsuser@bohr:~/work/docmodule> cvs history –a –e cvs.texinfo O 2002-11-14 10:32 +0000 cvsadmin CVSROOT =CVSROOT= <remote>/* O 2002-11-14 10:32 +0000 cvsadmin CVSROOT =CVSROOT= ~/work/* M 2002-11-14 11:06 +0000 cvsadmin 1.2 cvs.texinfo cvssources/doc == <remote> O 2002-11-14 11:22 +0000 cvsadmin cvssources =cvssources= <remote>/* O 2002-11-13 11:27 +0000 cvsuser cvssources =cvssources= <remote>/* O 2002-11-13 11:29 +0000 cvsuser cvssources =cvssources= <remote>/* O 2002-11-13 12:03 +0000 cvsuser cvssources/doc =docmodule= <remote>/* O 2002-11-13 12:04 +0000 cvsuser cvssources/doc =cvssources/doc= <remote>/cvssources/doc O 2002-11-13 13:02 +0000 cvsuser cvssources/doc =docmodule= <remote>/* C 2002-11-14 11:12 +0000 cvsuser 1.2 cvs.texinfo cvssources/doc == <remote> M 2002-11-14 11:43 +0000 cvsuser 1.3 cvs.texinfo cvssources/doc == <remote> Another option is the CVS log command, which prints a log of the actions performed on an individual file: cvsuser@bohr:~/work/docmodule> cvs log cvs.texinfo RCS file: /usr/local/cvs/cvssources/doc/cvs.texinfo,v Working file: cvs.texinfo head: 1.3 branch: locks: strict access list: symbolic names: Import: 1.1.1.1 mlc: 1.1.1 keyword substitution: kv total revisions: 4; selected revisions: 4 description: ---------------------------- revision 1.3 date: 2002/11/14 11:43:38; author: cvsuser; state: Exp; lines: +2 -1 Further comments added ---------------------------- revision 1.2 date: 2002/11/14 11:06:11; author: cvsadmin; state: Exp; lines: +1 -1 Updated comments 50
  • 61. Development ---------------------------- revision 1.1 date: 2002/11/11 11:09:00; author: cvsadmin; state: Exp; branches: 1.1.1; Initial revision ---------------------------- revision 1.1.1.1 date: 2002/11/11 11:09:00; author: cvsadmin; state: Exp; lines: +0 -0 Import ============================================================ Here each version of the file is described, along with a listing of the log message added at commit time. The annotate Command For an extremely detailed view of the changes made to a file, the annotate command prepends a comment to each line in the file, showing the version in which the line was last modified, the user performing the change, and the date and time: *************** 1.5 (cvsuser 23-Nov-02): 2001-07-14 John Gregory <jg@mlc.net> 1.5 (cvsuser 23-Nov-02): 1.5 (cvsuser 23-Nov-02): * Added comments on annotate. 1.5 (cvsuser 23-Nov-02): * Rebuilt system. 1.5 (cvsuser 23-Nov-02): 1.3 (cvsadmin 14-Nov-02): 2001-04-28 Derek Price <dprice@collab.net> 1.1 (cvsadmin 11-Nov-02): 1.1 (cvsadmin 11-Nov-02): * Makefile.in: Regenerated using AM 1.4e at 18:10 -0400. 1.1 (cvsadmin 11-Nov-02): * CVSvn.texi: Regenerated. 1.1 (cvsadmin 11-Nov-02): 1.4 (cvsuser 14-Nov-02): 2001-03-31 Larry Jones <larry.jones@sdrc.com> 1.1 (cvsadmin 11-Nov-02): 1.1 (cvsadmin 11-Nov-02): * cvsclient.texi (Dates, Requests): Add rannotate and rlog. 1.1 (cvsadmin 11-Nov-02): Earlier versions may be examined by specifying the date, revision or symbolic tag of the file or files in question. Customised Logging Where the default CVS logging information is considered inadequate, the administrative files modules, commitinfo, verifymsg and loginfo have options to run programs on certain actions, and these can be used to increase the flexibility of logging. For example 51
  • 62. Configuration Management with CVS the –i option in the modules file specifies a program to run on commit actions. This program is supplied with the full pathname of the module as an argument. The Diff Command When checking the modifications which have been made to a file it is often useful to compare different versions of the file. The CVS diff command is useful because it can display differences between files in the user’s work area and revisions in the repository. By default the differences are computed from the file’s working copy and the revision from which the file was checked out, although there are many options to diff to choose the files being compared. cvsuser@bohr:~/work/docmodule> cvs diff ChangeLog Index: ChangeLog ============================================================ RCS file: /usr/local/cvs/cvssources/doc/ChangeLog,v retrieving revision 1.4 diff -r1.4 ChangeLog 0a1,5 > 2002-11-15 Peter Pauling <pete@uni.org> > > * Made some changes to show a diff. > * Rebuilt code. > cvsuser@oppenheimer:~/work/docmodule> Checkout –p Both checkout and update support a switch (-p) which causes the output to be directed to the console, and thus can be redirected to utility programs such as grep. This can be useful for examining changes in revisions of files without cluttering up the working directory by having to retrieve each file from the repository. Abandoning Changes Having checked out a module and made some changes, it sometimes becomes apparent that these changes are not needed, or the modification is abandoned. In this case the developer needs to release the files formally, but does not want to return them to the repsitory. The command: cvs release <directoryname> should be run from the parent directory of the directory to be released. A useful switch is the –d switch, which also deletes the working directory. It is not strictly necessary to use this command, as files are not locked in the repository. However, as the command checks for uncommitted changes, and leaves a record in the history file, it is safer to use this command rather than simply delete the working directory. 52
  • 63. Development Keyword Substitution CVS supports keyword substitution to facilitate the readability of information stored in the code. Keywords specified with strings of the form $<keyword>$ or $<keyword>$:…$ are expanded to keyword, value pairs when a revision is obtained from the repository. The keywords available for expansion are shown in Table 5 Keyword Description $Author$ Username of the user who checked in the revision $Date$ Date and time of checkin $Id$ RCS filename, revision, date, author and state of the revision. $Header$ Full RCS file path, revision, date, author and state of the revision. $Name$ Tagname specified on checkout $Locker$ User who has locked the file. Normally not used in CVS $Log$ The log message specified on commit, together with the RCS filename, revision, author and date $RCSfile$ Name of the RCS file $Source$ Full path of RCS file $State$ State assigned to the revision $Revision$ Revision number Table 5 Keywords Keyword substitution can lead to problems, for example when a string matching a keyword is found in a binary file, so CVS provides various switches controlling how keywords are expanded. Each file has a keyword substitution mode associated with it, set either by the cvs add command when the file is first created in the repository, or added with the cvs admin command. This is particularly important for binary files, as accidental keyword expansion could destroy the file’s contents. A different mode may be set in a working copy of the file by specifying the keyword substitution mode to the checkout or update command. The CVS diff command may be set not to report different expansions of keywords with the –k<kflags> switch. Binary Files It has already been pointed out that keyword substitution needs to be turned off, and the line end conversion supplied by CVS when checking out to a system with different conventions needs to be suppressed in order to maintain the integrity of binary files. 53
  • 64. Configuration Management with CVS Another problem arises with the default unreserved checkout mechanism of CVS. The system allows multiple updates, and relies on merging changes back into the repository. In most cases (and certainly if using only the facilities of CVS), there will be no merge program available for a binary file, so if simultaneous updates have occurred, the only action CVS can take is to present the user with the two copies of the file, and allow him to choose one or the other, or use some external mechanism to merge the files. Watches provide a mechanism for warning an interested user that someone is editing a file, but these do not force a behaviour on the developers, and need to be backed up with procedures. In a large project it would certainly be possible to overlook a reported watch message. If a strict method of dealing with this problem is required, binary files can be checked out exclusively, placing a lock on the file until it is released. The cvs admin –l command allows the file to be effectively locked. Sticky Options Normally one does not want to have to remember the options which need to be specified for handling a file on each commit, so certain options are recorded with the file, and persist during the life of the file, or until they are changed. Binary files added to the repository can have their keyword substitution mode set with: cvs add –kb <filename> Where a file has been given the wrong mode, it can be corrected with: cvs admin –kb <filename> It is possible to override this default when checking out, updating or exporting the file. The cvswrappers file also allows default behaviours to be specified depending on the matching of a filename pattern. Exclusive Locks The whole philosophy of CVS is built around the opportunity for many developers to work on the same files simultaneously. Many other systems operate with exclusive locks on files, which allow only one person to be modifying a file at any one time. The trade- off is delays in development against the problems of having to merge changes together when returning files to the repository. There can be occasions where an exclusive lock is desirable, but although CVS offers some means of controlling this situation, it is not a perfect solution. The command: cvs admin –l <filename> locks a file to the extent that only the person who issued this command will be able to commit the file to the repository. Only one lock in each branch of the code is allowed for each file. This, however, does not mean that the file is not already being modified by another user, who will then have problems returning the file to the repository. 54
  • 65. Development There have been patches written for CVS to allow exclusive locks, but all depend to some extent on co-operation between users. The standard watch facilities are sufficient to warn a developer that another user id modifying a file, and these should be used in preference to other methods. Strange Files In normal operation CVS may create other files in the user’s working directory. Files named in the form: .#<filename>.<revision> are created when an update is performed in the working directory on a modified file, and records the state of the file before the update was performed. This can be useful if conflicts which cannot easily be resolved are found, as this file will contain only the developer’s own modifications to the file he checked out. It may be desirable to run a housekeeping job to delete such files after a certain time. 55
  • 67. Revisions, Releases and Branches 9 Revisions, Releases and Branches CVS records changes in files in the repository as development progresses using revision numbers. Normally the first revision of a file will have revision number 1.1, and the next update 1.2. When a new file is added, the rightmost number will be set to 1, with the left hand number set to the highest number existing in the module in the repository. Note that the import command acts slightly differently, and creates the first version in the repository as 1.1.1. There is normally no need for the user to concern himself with revision numbers, and it is much more convenient to use symbolic tags to mark releases or project milestones. However CVS does allow the user to manipulate revision numbers through the –r switch to commit. With the working directory the current directory, the command: cvs commit –r 5.1 will set all files to this version in the repository, even if they have not been modified locally. By default the command will deal recursively with subdirectories of the module. It is not possible to set a revision number lower than the highest one which exists already in the module. The process of defining all the revisions which make up a release or milestone is called tagging. Here a symbolic tag is added to a consistent set of files. The tag allows the release to be retrieved, even when development of the next version of the software has continued. Tags must start with a letter, and contain only alphanumeric characters, and the symbols ‘-‘ and ‘_’. Thus for release 1.0 of the program widget, a suitable tag might be widjet-1- 0. CVS provides two commands for manipulating tags, tag which operates on files in the working directory, and rtag which operates on files in the repository. The normal way to 57
  • 68. Configuration Management with CVS set a tag representing a release is to move to the top of the module in the working directory, making sure all files are up to date, and issue the command: cvs tag widget-1-0 By default this command will operate recursively on all files in all subdirectories of the module. If this is not the desired effect, it can be turned off with the –l switch. Although the cvs tag command operates on the versions of files checked out in the current working directory, it also applies the tag immediately to the repository versions of these files. Tagging only a limited number of files is also possible : cvs tag widget-1-1 widget.h One useful switch to the cvs tag command is –c (which might be useful to set as a default in the users’ .cvsrc files). This forces a check for any differences between the repository revision of the file, and the copy in the working directory. If differences are found the tag is aborted. Having tagged a release or milestone, a user can check out that version of the software by using the –r switch to checkout: cvs checkout –r widget-1-0 <modulename> The command cvs rtag can be used to move or delete tags in the repository, so this is a command which must be used with extreme caution. Moving a tag means changing the revision number of one or more files with which the tag is associated. cvs rtag –r 2.7 –F <tagname> <filename> would associate <filename> revision 2.7 with the symbolic tag <tagname> in place of the current revision. Software development is rarely a straight-line process, and very often parallel development of features for different releases will be necessary. For such situations branches are set up. A branch is created with tag for a module in the working directory, or rtag for files not checked out of the repository. With the required version of the module checked out, the command: cvs tag –b <branchname> will create a branch in the repository, but will not actually check out that branch to the working directory – the original version is still in the work area. To switch to the new branch it is necessary to perform one of: cvs checkout –r <branchname> cvs update –r <branchname> Operating directly on the repository, the command: cvs rtag –b –r <tagname> <branchname> creates a new branch <branchname> based on the release <tagname> In creating a branch CVS creates a new stream for parallel development. A typical use for such a branch would be to continue development of a software product after a release, while using the branch from the release to fix any reported bugs. 58
  • 69. Revisions, Releases and Branches Main Trunk Tag Rel-1-0 Revision Revision Revision Revision 1.6 1.7 1.8 1.9 Branch Tag Rel-1-0patch Branch Revision Revision Revision 1.7.2 1.7.2.1 1.7.2.2 1.7.2.3 Figure 2 Creating a Branch CVS creates a revision number for the branch by appending a further digit, starting with 2 onto the revision number of the root file. The files themselves are given a further digit starting at 1. Normally the user will not concern himself with the actual revision numbers, but will refer to the branch by its symbolic tag. Note that the set of files checked out have been selected by their symbolic tag, so the actual revision numbers of the files in the branch are all likely to be different, as they are rooted in files with different revision numbers. Working on a Branch When a developer issues a checkout command for a module, he will normally receive the latest version of the code in the main branch (trunk). To check out the code in a branch the command: cvs checkout –r <branchname> <modulename> or: cvs update –r <branchname> [<modulename>] is used. the name of the module only needs to be specified if the current directory is not set to the top level directory of the module within the work area. Now the user can work on the branch, and may simply commit modified code without worrying about where the code will be placed in the repository. The reason CVS is able to do this is that it maintains a “sticky tag” representing the branch name for the code in the working directory. The status command may be used to check this: 59
  • 70. Configuration Management with CVS cvs status cvs.texinfo ============================================================ File: cvs.texinfo Status: Up-to-date Working revision: 1.3 Repository revision: 1.3 /usr/local/cvs/cvssources/doc/cvs.texinfo,v Sticky Tag: cvssrc-1-0patch (branch: 1.3.2) Sticky Date: (none) Sticky Options: (none) ============================================================ Operating in this way the developer, after checking out the branch may ignore the fact that he is working on a branch, until his work is complete. Obviously if manual changes are made to the work area, the sticky tag may be lost, so this should be avoided. Merging a branch In our scenario of a release, followed by further development and bug fixing in parallel, there will come a time when the bug fixes are required to be incorporated into the main trunk. This might be at a stable point in the new development, or delayed until the release is ready for final test. The process of incorporating changes from a branch into the trunk is performed by merging. There are two ways of merging a branch, with the update or checkout command, but in both cases the working area is first set to contain the contents of the main trunk. cvs update –r <tagname> [<modulename>] sets the work area to contain the main trunk code, then cvs update –j <branchname> causes the branch to be merged into the trunk in the work area. This must be followed by a commit to replace the files in the repository. When merging a branch it is possible to specify the date of the branch revisions to use to update the trunk: cvs update –j <branchname>:<date> Keyword substitution can produce false conflicts, when for example the revision number is expanded in both files being merged. It is thus useful to use the –kk switch to update, to suppress keyword expansion. Use of the –kk switch overrides any default keyword expansion flags set for a file, so it should not be used where binary files exist in the repository, and have the –kb mode set. Merging can, however, show up conflicts in the files, which have to be dealt with manually before committing. There can be further complications of working on a branch. Perhaps, during further development on the trunk it becomes necessary to incorporate a bug fix made in the patch branch, but work is still ongoing in both the trunk and branch code streams. It would be possible to merge the branch, and then set up a further branch off the tip of the 60
  • 71. Revisions, Releases and Branches current branch for further development, but this may lead to confusion and is unnecessary. It is quite possible to merge the current state of the branch, perform more modifications, then merge the differences between the original merge, and the final code. If we were only concerned with a single file, the command: cvs update –j <revision number> -j <branchname> <filename> will merge all the differences in <filename> made between <revision number> (which should be the revision originally merged into the main trunk, and the current tip of the branch <branchname>. Such an operation is impractical when several files are involved, as they are all likely to have different revision numbers. However, if the branch is given a symbolic tag at the time of merging the branch, the same command may be given to merge all the updated files: cvs update –j <tagname> -j <branchname> similarly two symbolic tagnames could be used, if tags had been applied to the branch when milestones were reached. It is good practice to tag the head of a branch before merging, as if further changes are made to the branch, a second attempt to merge the branch from its root will fail with reported conflicts. It is necessary to merge only the new changes in the branch, which is much easier if a symbolic tag is used to mark the point of the previous merge. Backing Out a Change The update command can be used to revert to an earlier revision of a file, or to remove all changes made between two revisions. The command: cvs update –j 2.7 –j 2.3 <filename> will remove all the changes made between the two revisions 2.3 and 2.7. The order of the revisions is significant. The Vendor Branch When a set of files is imported into a repository both a vendor tag and a release tag are specified, and by default the files are imported into the CVS vendor branch which is labelled with the revision number 1.1.1. The vendor branch is also marked as the default branch, which will be searched as well as the trunk to find the most up to date revision of a file. CVS only supports properly a single vendor branch, but there is an option to the import command to specify the branch revision number when importing to create further vendor branches: cvs import -b<vendor branch> <module name> <vendor tag> <release tag> where <vendor-branch> is specified as (say) 2.2.2 (a branch is always identified by a 3 digit revision) will create a new vendor branch. CVS only looks for a single vendor branch, so the default branch will have to be specified when checking out files. 61
  • 72. Configuration Management with CVS To set the default CVS branch for a work area to <branch> use checkout or update with the -r <branch> option. The effect of this command is to override any sticky branch tags for the work area concerned, and any subsequent checkouts will come from the specified branch. The ability to specify different vendor branches is of very little use, unless the previous vendor branch is to be removed from the repository. If multiple vendor branches are used, the greatest care must be taken to specify the branches correctly when checking out files. In practice it is unlikely that projects from different vendors would be mixed in the same repository, and a series of releases from a vendor can be imported into the same vendor branch, being identified by the release tag. 62
  • 73. Source Distribution and Mirror Sites 10 Source Distribution and Mirror Sites When a release has been tagged, it may be desirable to package up the source for distribution to other sites. This can be achieved with the export command. cvs export –r <tagname> -d <directoryname> <modulename> which causes the module’s files tagged with <tagname> to be checked out into a directory structure under <directoryname>. The only difference between this command and a checkout is that the CVS directories are not created within the module directories, thus creating only a source tree suitable for distribution. The export command can also select files by date, or revision number. An alternative, where regular source updates are made, is to issue a patch to update the last release to the current revision. The CVS rdiff command: cvs rdiff –r <tagname1> -r <tagname2> will create a patch file to update a directory from release <tagname1> to release <tagname2>. Where there are distributed sites which need access to the code in a repository, it may be useful to mirror the main repository locally. A utility to do this, CVSup, is optimised for CVS in that it is able to update a repository by transmitting only the changes applied to the repository since the last update. The system runs as a daemon on the central CVS repository host, and a client, which is usable as a command line program or graphical interface, on each of the mirrors. 63
  • 74. Configuration Management with CVS Screenshot 5 The CVSup GUI CVSup can be set up to transfer or update either a complete repository, or a particular version of selected modules of the code. There is considerable control over the files to be transferred, which is useful when many variants of a code set exist, for example for localisation. Transfers are initiated by the receiving client, which may decide to request a subset of the code tree offered by the main server daemon. Other open source packages which can be used to create mirror sites include sup, rdist, rsync and mirror, but these are not optimised for CVS. 64
  • 75. Windows Problems 11 Windows Problems When using a Windows client using the NTFS file system, there are instances where the modification time of a file is erroneously set, and the file appears to have been modified when in fact it has not. This occurs with Windows clients, irrespective of whether the CVS server is running Windows or Unix and usually manifests itself during daylight saving time, or after a change to or from DST. A solution is available for the client supplied with cvsnt, in the form of a registry key. The key must be set for every user of the cvs client: [HKEY_CURRENT_USERSoftwareCVSClient] "GmtTimestamps"=dword:00000001 After setting this key, files which were incorrectly marked as updated can be fixed by running cvs stat on them. The difference between Windows and Unix treatment of line endings (CR/LF and LF) is automatically catered for by the CVS checkout and commit commands. This means, however that it is not possible to copy files in a user’s work area from one system to another. More attention should be given to specifying binary files, as line ending conversion will almost certainly render a binary file unusable. When using a filesystem exported by SAMBA, some problems during commits and removal of files have been reported. Setting DeleteReadOnly=yes should cure these problems. 65
  • 77. Front Ends 12 Front Ends So far we have concentrated on the use of the CVS command line interface, which will always be required to perform some of the tasks which the configuration manager will have to perform. The majority of developers, particularly those working in a GUI environment, are likely to be uncomfortable with this interface. There are several graphical front-ends available for CVS, both under MS Windows, and X-Windows which simplify the day-to-day tasks of a developer. The best known of these are WinCVS for MS-Windows and gCVS and Cervisia for Unix/Linux, but there are others available (See Resources). WinCVS The most windows-compliant and comprehensive GUI for CVS is WinCVS, developed by a group of enthusiasts, and made available under the GNU public licence. Once a project has been set up by the configuration manager, the GUI displays a representation of the project similar to Windows Explorer, with information on the status of the modules and files displayed graphically. Using the menu items, context menu or the toolbars, the developer can checkout a module, write-enable files, perform the changes required and check the module back into the repository. The only clue that CVS is in use is the message pane at the bottom of the window which displays the CVS commands being used, and any status and error messages. Differences between the repository files and local copies can be displayed, as can the version history of a file. Where WinCVS does not provide a facility (which should be very rare within the scope of a developer’s needs), a command line interface facility is available. 67
  • 78. Configuration Management with CVS WinCVS provides every facility for the developer to operate under a completely graphical interface, and almost all that is needed by the configuration manager for setting up projects and releasing software versions. Screenshot 6 The WinCVS GUI gcvs The gcvs package which runs with the gtk+ toolkit (Gimp toolkit) follows similar lines to WinCVS, in that it displays the directory tree in the left hand pane, and the files in the work area in the right pane. Operations are performed in a similar way to WinCVS, and again the lower part of the window displays the actual CVS command line and the messages received from CVS. Screenshot 7 The gcvs GUI 68
  • 79. Front Ends Cervisia The interface to Cervisia takes a slightly different approach, and only the files under development are shown, the directories being selected through a dialog box. Cervisia offers fewer command options than gcvs and WinCVS, but this may not be a bad thing as developers usually are more concerned with programming than configuration management, and simplicity can improve the CM process. Cervisia is supported for the Linux/KDE environment. Once again the lower part of the screen displays CVS commands and messages. Screenshot 8 The cervisia GUI TortioseCVS Another Windows GUI freely available, TortoiseCVS takes a different approach, by adding items to the Windows Explorer context and file menus. Whilst not offering the comprehensive support of WinCVS, TortoiseCVS may be a viable alternative for developers who only rarely need to get involved in configuration management issues, and just need to follow the discipline of checking modules in and out of the repository. TortoiseCVS indicates the status of files by modifying the icons used to identify files under windows explorer. By default a file which has been modified is displayed in red, while a file with conflicting modifications is shown in purple. Green signifies a file which has not been modified, but is held in the repository, while a blue question mark shows a file not yet stored in the repository. 69
  • 80. Configuration Management with CVS Screenshot 9 The TortoiseCVS GUI CVSIn For developers using Microsoft Visual Studio CVSIn is an add-in which provides direct access to CVS repositories from the VS interface. CVSIn displays a toolbar with the basic CVS commands directly accessible from within VS. The commands catered for directly are: update ,commit, query, diff, log, status, edit, unedit, watch, release watch, tag, untag, fork and unlock.Where more complex CVS operations are to be performed CVSIn launches a wizard giving access to WinCVS. Screenshot 10 the CVSIn add-in toolbar for Visual Studio Lincvs LinCVS, although Linux support is implied by it’s name will also soon support Windows clients. It is based around the Qt package, a multiplatform C++ GUI application framework. Again an explorer-like view is shown in the left window, but this is not simply the file tree, but a selection of directories made by the user, by adding them to his workbench. Files from these directories are displayed in the right hand pane, and menu options allow CVS operations on these files, either singly or as a group. As with most of these front ends, the result of CVS commands is displayed in the lower window. 70
  • 81. Front Ends Screenshot 11 The LinCVS GUI EMACS The popular Unix editor emacs has some built-in support for CVS, RCS and SCCS through its version control commands(VC). A further add-in script pcl-cvs provides further integration with CVS. VIM An add-in script for VIM, cvsmenu.vim to provide a CVS menu of commands is available. This functions both with the character based vim, and the graphical editor gvim. Screenshot 12 Cvsmenu adds CVS functions to vim 71
  • 82. Configuration Management with CVS Screenshot 13 The gvim plugin Displays the CVS menu 72
  • 83. Build Systems 13 Build Systems CVS does not provide any special facilities for building the software, so it is likely that one of the versions of make will be used. There are also open-source build systems available, such as Odin, Jam and Cook (See Resources). The problem in building is that a developer working on one or two modules will want to compile and test the code he is working on, while this code may be dependent on many other parts of the system. For each developer to check out large amounts of code is both time and disk consuming, and dangerous, as each individual developer will need to keep large amounts of code in synchronism with the repository. For this reason, in a large project it may be sensible for the configuration manager to maintain a central copy of up-to-date checked out code which can be used by the developers through operating system mechanisms such as links, or the make facilities such as VPATH. It is wise for the build to be totally automated, which favours makefiles at all levels within the project, allowing checked out modules to be compiled with a local makefile, and higher level makefiles visiting lower levels and executing the subordinate makefiles. Because of the default recursive behaviour of CVS, the latest source can always be copied to a staging area for compilation by issuing an update command at the top level of the project tree. For example: cvs update –j <tagname> will retrieve the whole project tree of the release tagged with <tagname>. Strictly it would be better to issue the command: cvs update –d –P –j <tagname> 73
  • 84. Configuration Management with CVS as, if the work area has been used before, it may contain directories which have since been deleted, and not contain directories which have been added in the repository. The – d switch will cause the new directories to be created, while –P prunes any redundant ones. For auditing purposes it is frequently desirable to construct a bill of materials, recording all the versions of the code files which have been used in a build. This can be achieved if the release has been tagged with the command: cvs log –r<tagname> which produces as output: ============================================================ RCS file: /usr/local/cvs/cvssources/doc/cvs.texinfo,v Working file: docmodule/cvs.texinfo head: 1.3 branch: locks: strict access list: symbolic names: cvssrc-1-0patch: 1.3.0.2 cvssrc-1-0: 1.3 Import: 1.1.1.1 mlc: 1.1.1 keyword substitution: kv total revisions: 4; selected revisions: 0 description: ============================================================ RCS file: /usr/local/cvs/cvssources/doc/cvsclient.texi,v Working file: docmodule/cvsclient.texi head: 1.1 branch: 1.1.1 locks: strict access list: symbolic names: cvssrc-1-0patch: 1.1.1.1.0.2 cvssrc-1-0: 1.1.1.1 Import: 1.1.1.1 mlc: 1.1.1 keyword substitution: kv total revisions: 2; selected revisions: 0 description: 74
  • 85. Build Systems Make Most developers will be familiar with one of the versions of make, and GNU make is available under the GNU Public Licence. Make can, however, be difficult to use in large projects where files are distributed over many directories, and variant builds can be problematic. One of the most difficult aspects of building a project with the minimum amount of recompilation is the determination of dependencies, for which a tool such as makedepend is required. It is normal to have to run this tool on the whole set of project files, each time a build is made in order to ensure that the correct files are rebuilt, which can be time consuming. The build systems described here use more sophisticated methods of determining and storing dependencies. Jam Jam (Just Another Make) is a software build tool particularly orientated towards C/C++, where its built-in rules are able to determine dependencies. It can, however be used with other languages. Jam is freely available as C source from Perforce Software. http://public.perforce.com/public/index.htmlBecause Jam understands C/C++ dependencies, there is no need to declare header or object files. A build of a C/C++ project can therefore be specified by simply listing the components in a syntax similar to make, using the rule Main: Main program: main.c sub.c sub1.c …; Jam runs on many platforms, and is able to handle projects scattered over many directories. It can also use multiple hosts to perform the build. Cook Cook is another replacement for make on Unix systems and includes variables and user- defined functions. It can distribute build activity across multiple machines on a network, and facilities for producing a bill of materials are included. The program provides a method of generating and using a dependency file for each component of the project. Odin Odin determines dependency information automatically, and stores it in a database, updating the information incrementally as required. It supports parallel builds on networked machines, and has features to support variant builds. ============================================================ 75
  • 87. Visualising the Source Tree 14 Visualising the Source Tree CVS offers no way of examining the ancestry of a file except in report form, but it is often useful to have a picture of the development tree showing the branches and releases. The Unix utility cvsgraph produces a graphical representation of the source code in an RCS file. WinCVS also has a feature to display the code tree graphically. 77
  • 88. Configuration Management with CVS Screenshot 14 The Display from CVSgraph For Windows users the WinCVS front end also offers a graphical representation of the source tree. Screenshot 15 The WinCVS Graphical Display 78
  • 89. Diff and Merge Programs 15 Diff and Merge Programs Windows Programs CSDiff Whilst not strictly an open source product, this diff program is available free of charge from Component Software. Text files are displayed either in the normal diff format or in a more friendly fashion in a single window. A useful feature of this program is that it can display differences in MS Word format files, although an installation of Word is required, as CSDiff launches Word to display the differences. CSDiff analyses the differences in both files and directories, and reports can be printed in diff or HTML format. 79
  • 90. Configuration Management with CVS Screenshot 16 The CSDiff Diff Format Display Screenshot 17 CSDiff Handles MS Word Files WinMerge Winmerge displays the differences between two files side by side, with colour used to highlight additions and deletions. It will also analyse the differences between two directories. Merging can be performed by highlighting a difference and selecting copy to left or right, or all differences can be merged in one command. 80
  • 91. Diff and Merge Programs Screenshot 18 The WinMerge Display Unix Programs xxdiff The xxdiff program is a graphical front end to standard diff programs such as gnu diff. It is launched from the command line as: xxdiff file1 file2 [file3] and can compare two or three files or two directories. Merging can be achieved by selecting sections of text and using a merge command from the menu. Screenshot 19 xxdiff shows the differences reported by a standard diff program GNU Diff Utilities GNU Diff Utilities are a set of command line programs for comparing files, generating patches and merging files. Diff and diff3 are used for comparing two files or directories, or three files, cmp compares two files, while sdiff can be used to merge files. The patch utility is used to apply a diff generated patch to a file. The CVS diff command supports a subset of the GNU diff commands. 81
  • 93. Anonymous CVS 16 Anonymous CVS The popularity of open source software, and the collaborative effort of programmers all over the world to produce and maintain it, has led to a large number of CVS source repositories being made publicly accessible. Obviously one of the objectives of configuration management and source code control is to avoid a free-for all in software development, and anonymous CVS provides the facilities to organise collaborative development. CVS can be set up to allow read-only access to anyone, and this is usually implemented by setting up a user named anonymous, requiring no password but included in the admin file readers. Anyone is therefore free to download the source tree of a project, and compile and modify the code. Each project may follow a different procedure, but if a developer would like his modifications to be incorporated in the project he will normally produce a patch with CVS and submit it to a moderator who has full access to the project source tree. A large number of such open source projects are hosted by SourceForge (http://sourceforge.net) The following is an example of obtaining the source to cvstrac from an anonymous CVS server: # cd /usr/src/cvstrac # cvs -d :pserver:anonymous@cvs.cvstrac.org:/cvstrac login Logging in to :pserver:anonymous@cvs.cvstrac.org:2401/cvstrac CVS password: 83
  • 94. Configuration Management with CVS # cvs -d :pserver:anonymous@cvs.cvstrac.org:/cvstrac checkout cvstrac cvs server: Updating cvstrac U cvstrac/COMPILING U cvstrac/COPYING U cvstrac/VERSION U cvstrac/attach.c Obtaining cvstrac by anonymous cvs 84
  • 95. Problem Tracking 17 Problem Tracking Another aspect of controlling the software development cycle is the recording of problems or development tasks in such a way that they can be planned for, monitored and related to releases. CVStrac A problem tracker which is integrated with CVS is available as an open source product. Cvstrac is a web-based product which maintains a problem database, usually in the CVSROOT directory, and offers problem tracking and reporting, together with the useful ability to browse the CVS repository and investigate differences in the files. Although not having the flexibility to tailor problem reports to the organisation’s needs found in more sophisticated (and expensive) products, the system is perfectly usable. Cvstrac can be launched from a cgi script, run as a service started with inetd., or as a stand-alone web server The advantage of using a browser-based system is that the central problem database can be accessed from all the hosts in use by the developers, whether Unix or Windows based, although the tracking system itself runs only on a Linux/Unix server. Using Cygwin (a collection of Unix utilities for Windows), however, it is possible to run cvstrac on a Windows/Apache server system in http mode. The tracking system implements its own SQL-based database, so no external database server is necessary. User defined queries can be generated, and users’ access to the problem tracking database can be controlled on an individual basis. A facility is also provided for administering the CVS passwd file interactively. 85
  • 96. Configuration Management with CVS Screenshot 20 The CVStrac Problem Ticket Cvstrac produces a variety of reports on the problem database, even allowing the user to create a new report by selecting problems with SQL statements. A timeline of checkins can be displayed from the CVS history file, and differences between revisions can be displayed by drilling down when browsing the changes recorded for a file. Screenshot 21 CVStrac displays the changes made to a file 86
  • 97. Problem Tracking Bugzilla/CVSZilla One of the most popular open source problem tracking systems is Bugzilla, a system developed for tracking problems at Mozilla. It was originally written in TCL, but later ported to Perl by Terry Weissman the author. The port to Perl was released under the open source licence as Bugzilla V2.0. Since then it has been adopted as the main bug tracking system for many open source and other projects, and seen significant enhancement. It is simply accessed through a browser. The current design principles are aimed at making the system fast, lightweight and interoperable with any SQL based database, although it is currently restricted to MySQL, with work going on to support PostGreSQL and Sybase. Being written in Perl it is easily modifiable, and there are many installations where the code has been tailored to suit a particular organisation’s way of working. Part of the standard Problem report form is shown in Screenshot 22, and Screenshot 23 shows the screen where queries can be built up to search the database. Additional queries can be set up in SQL. Screenshot 22 Part of Bugzilla's Problem Report 87
  • 98. Configuration Management with CVS Screenshot 23 Bugzilla's Query Form CVSZilla is a set of Perl scripts, originally written by Tony Garnock-Jones, which help to integrate Bugzilla with CVS. and ViewCVS or CVSWeb. They use the standard CVS features of commitinfo, loginfo, taginfo and verifymsg to cause changes to be stored in the MySQL database. 88
  • 99. Administrative Tasks 18 Administrative Tasks Backup The CVS repository comprises standard Unix or Windows file types, and thus any backup system can be used to safeguard the code base. The only consideration is that, to maintain a self-consistent set of files, the repository should not be updated during the backup. This can be achieved by placing lock files in the repository directories, or by stopping the CVS server in client/server mode. A useful program which locks a Unix CVS repository, executes a command, then unlocks the repository is cvslock by Thomas Roessler (see resources). Tidying up the Repository After a long period of software development the repository will become large, and it may become desirable to remove older, intermediate versions of the code, retaining only the released versions or major milestones. This is achieved with the admin –o command, but the syntax of this command makes it very easy to make mistakes. Unless this operation is absolutely necessary it is better not used. There is no mechanism for reversing the effects of this command. The command: 89
  • 100. Configuration Management with CVS admin –o 2.5::2.8 <filename> deletes all the revisions between 2.5 and 2.8, leaving these revisions intact, while: admin –o 2.5:2.8 <filename> deletes all revisions from 2.5 to 2.8 inclusive. If a symbolic tag or a branch exists in a revision the revision will not be deleted if using the :: syntax, but will with the : syntax. In both cases the operation will fail if any of the revisions to be deleted contain branches or locks. Although the revisions to be deleted can be specified with tag names, this has the side effect that if a file has not changed it may be deleted from another, later tagged release. CVS Defaults The CVS admin command allows default values for some CVS parameters to be set up. In practice the only default which it is useful to change is the keyword substitution method. For example: cvs admin –kkv sets the default to be the normal method for keyword expansion. The choice made by the administrator may be overridden by setting the value on the command line. Most of the other options to the admin command are historical values relating to RCS, and should rarely be used. Reset the Default Branch There will be some instances where software is supplied by a third party but modified by local developers. The software will have been initially imported into the repository using a vendor tag to create the vendor branch. Modules and files which have been checked out and updated will now lie on the trunk, and a checkout which does not specify a specific branch will retrieve the revision at the head of the trunk. If an updated release is received from the supplier, this will be imported into the vendor branch rather than updating the trunk. To ensure that a checkout is made from the latest vendor revisions the vendor branch can be reset as the default branch: cvs admin -b<vendor-tag> <module-name> 90
  • 101. Other Utilities 19 Other Utilities cvsadmin cvsadmin is a tool to administer users of a CVS repository. It handles adding, deleting, renaming users, changing passwords, etc. gcvsadmin is a GTK interface to it that handles multiple repositories. CVSWeb A cgi script which allows a repository to be viewed in a browser. This program has evolved into CVSWebclient and CVSWebedit, which also allow CVS files to be edited. ViewCVS An alternative program to CVSWeb which allows a CVS repository to be viewed through a browser. cvsmonitor Another browser based viewer, also providing statistics and a graphical representation of them on the activities on the code. cvsreport Formats and mails reports on CVS activity. Freepository Freepository is a Web-based revision control system based on extensions of CVSWeb. It employs a project concept, which provides member accounts and access controls. cvspwd A utility for generating Unix-encoded passwords. dgdeletelocks.pl dgfindlocks.pl Scripts to find hanging locks in a CVS repository and delete them. dgfixcvs.pl Script to update the copies of the administrative files in the users’ working directories when a repository is moved. 91
  • 102. Configuration Management with CVS findlocks.pl Locate files with exclusive locks. 92
  • 103. Environment Variables A Appendix A Environment Variables Variable Description CVS_CLIENT_LOG Sets up log files for debugging communication in client/server mode. All client initiated communication is logged in CVS_CLIENT_LOG.in, and replies from the server in the corresponding .out file CVS_CLIENT_PORT The port number to use to communicate with the server CVS_PASSFILE The file used to store passwords during a session in client/server mode after a successful login. Defaults to ~/.cvspass CVS_RCMD_PORT The port to use on the server side to execute the remote command CVS_RSH Specifies the remote shell program to use, usually rsh or ssh CVS_SERVER The remote program to run when accessing a repository in client/server mode with the ext, server or fork modes CVS_SERVER_SLEEP Delays the start of the server program so that a debugger may be attached CVSEDITOR Specifies the program to run to edit log EDITOR messages. CVSEDITOR overrides EDITOR CVSIGNORE A list of patterns, separated by white space indicating files to ignore. the pattern is a shell 93
  • 104. Configuration Management with CVS pattern (e.g. *.exe) and not a regular expression. CVSREAD Set files checked out or updated to be read-only CVSROOT The location of the CVS repository. This may be a simple path in the case of a local repository, or a connect string in client/server mode. Local example: /usr/local/cvs pserver: :pserver:cvsuser@oppenheimer:/usr/local/cvs CVSUMASK Sets the default file mode of files in the repository. Only available when CVS is used in local mode CVSWRAPPERS A list of patterns (shell format) and the options to be applied to those files, separated by white space Table 6 Environment Variables 94
  • 105. Command Reference B Appendix B CVS Command Reference 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. Global Options Common Options Switch Description -b <binary directory> Location of RCS binaries – now obsolete -T <temporary directory> Location for temporary files -v Display version number --version Table 7 Common Global Options 95
  • 106. Configuration Management with CVS Client Command Options Switch Description -a GSSAPI switch causes authentication of all messages between the client and server -d <root directory> Specifies the root of the repository and overrides any setting in CVSROOT -e <editor> Specifies the log message editor, overriding CVSEDITOR and EDITOR -f Ignore the settings in ~/.cvsrc -H [<command>] Display help on the specified command, or --help[<command>] a general help message if no command is specified -l Do not record this command in the history file -n Perform the command without modifying any files -q Quiet mode -Q Very quiet mode -r Make new working files read-only -s <variable>=<value> Set user variable, which may be expanded in an administrative file -t Trace -w Make new working files writeable -x Encrypt all communication between client and server, applies only to GSSAPI and Kerberos connections -z Set compression level for client/server communication Table 8 Client Global Options Server Option Switch Description --allow-root=<root directory> Allow access only to users accessing this repository. May be repeated for multiple repositories. Table 9 Server Global Options 96
  • 107. Command Reference Client Commands add Add files or directories to the repository: cvs add [options] <filename> [<filename> …] Switch Description -k <kflags> Determines how keyword substitution is performed -m <message> Defines a descriptive log message Table 10 add command options annotate Prints a report showing the history of every line of the files specified: cvs annotate [options] <filename. [<filename> …] Switch Description -D <date> Use most recent revision no later than <date> -r <revision> Use this revision or symbolic tag -f Include files not tagged with the tagname, or not present on <date> -l Do not recurse into subdirectories -R Recurse into subdirectories Table 11 annotate command options checkout Check out the specified module into the user’s work area (sandbox): cvs checkout [options] <module> [<module> …] Switch Description -A Reset sticky tags and dates -c Copy the sorted module file to standard output -d <dir> Override the default directory name -D <date> Use most recent revision no later than <date> -f Include files not tagged with the tagname, or not present on <date> -j <rev> Merge branches -k <kflags> Keyword substitution mode -l Do not recurse into subdirectories -n Do not run checkout program specified in the administrative files -N Use full module paths -p Pipe files to standard output with header information 97
  • 108. Configuration Management with CVS -P Remove empty directories -r <revision> Use this revision or symbolic tag -R Recurse into subdirectories -s Show the status of each module Table 12 checkout command options commit Commits file changes made in the work area to the repository cvs commit [options] <filename> [<filename> …] Switch Description -f Force the commit, even if the file is unchanged -F <filename> Use the file as the log message -l Do not recurse into subdirectories -m <message> Specify the log message -n Do not run checkout program specified in the administrative files -r <revision> Use this revision or symbolic tag -R Recurse into subdirectories Table 13 commit command options diff Display the differences between two versions of a file. By default the version in the sandbox is compared with the version in the repository from which it was originally copied. cvs diff [options] <filename> [<filename> …] Switch Description -D <date> Use most recent revision no later than <date> format diff format options -k <kflags> Keyword substitution mode -l Do not recurse into subdirectories -r <revision> Use this revision or symbolic tag -R Recurse into subdirectories Table 14 diff common command options Option Description -a Treat the files as text even if they are not --text -B Ignore blank lines --ignore-blank-lines -b Ignore changes in the amount of --ignore-space-change whitespace 98
  • 109. Command Reference --binary Treat the file as binary, ignoring line breaks --brief Just check if the files differ -c Context output format, prints three lines of text for context -C <lines> Context output format with <lines> of --context=<lines> context -d Search more effectively for differences, --minimal showing up smaller changes -i Ignore case --ignore-case -N Treat new files as if an empty file was --new-file present in the other directory -n Output in RCS format --rcs -p Show the name of the function containing --show-c-function the difference -s Show when two files are identical -report-identical-files -t Expand tabs to spaces in output --expand-tabs -u Unified output format -U <lines> Unified output format using <lines> of --unified[=<lines>] context -w Ignore whitespace --ignore-all-space -w <columns> Number of columns for side by side mode --width <columns> -Y In the output put a tab after the indicator --initial-tab character -y Show the files side by side --side-by-side Table 15 diff formatting options edit Sets a file to be writeable and sends a message to all users who are watching this file. cvs edit [options] <filename> [<filename> …] Option Description -a <action> Specify the action being performed -l Do not recurse -R Recurse into subdirectories Table 16 edit command options 99
  • 110. Configuration Management with CVS Action Description all All these actions commit Changes have been committed edit A file is being edited none Default for edit unedit Changes have been removed Table 17 edit actions editors Displays a list of users who have used the edit command on the files specified. cvs editors [options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories Table 18 editors command options export Exports the specified files from the repository, without creating the CVS administrative files and directories. This can be used for preparing a package of files to transfer to another CVS system. cvs export [options] <filename> [<filename> …] Option Description -D <date> Export the most recent revision no later than <date> -d <directory> Used <directory> instead of the module name -f Include files not tagged with the specified tag, or not present on the selected date -k <kflags> Control keyword substitution -l Do not recurse -n Do not run any checkout programs -N Do not shorten directory paths -R Recurse into subdirectories -r <revision> Export the specified revision number or symbolic tag Table 19 export command options help Display the help messages. cvs help gives a list of commands, while cvs --help <command> gives help on a specific command. 100
  • 111. Command Reference history Shows the history of actions taken on the specified file. This feature is only available if history is being collected by having the history file in the CVSROOT directory of the repository: cvs history [options] <filename> [<filename> …] Option Description -a Show history for all users -b <string> Show history back to a record containing <string> in the module name, file name or repository path -c Report commits -e Report everything -f <filename> Show the most recent action on <filename> -l Show the last action -m <modulename> A full report on <modulename> -n <modulename> Report the last action on <modulename> -o Report on checked out modules -p <repository> Report on a repository directory -t <tagname> Report on history since <tagname> was last added to the history file -T Report all symbolic tags -u <username Report all actions performed by <username> -w History for the current working directory -x <type> Report activities of type <type> -z <timezone> Report times for timezone <timezone> Table 20 history commandoptions Type Description A A file was added for the first time C A merge was required, but conflicts were detected E An export was performed F A release was made G An automatic merge was performed M A file was modified O A file was checked out R A file was removed T A symbolic tag was applied U A working file was copied from the repository W The working copy of a file was deleted 101
  • 112. Configuration Management with CVS Table 21 history output import Imports a directory tree into the repository as a new module. cvs import [Options] <modulename> <vendor tag> <release tag> Multiple release tags may be specified. Option Description -b <branch> Import to a vendor branch -d Imports a file using the file’s modification date and time rather than the current date and time. Only available when CVS is working in local mode -I <pattern> Ignore files matching <pattern> -k <kflags> Control keyword expansion -m <message> Sets the log message -W <wrapper> Specify files to be filtered during input Table 22 import command options Information displayed by the import command uses the following codes: Status Description C Changed The file existed in the repository and the imported file was different, requiring a merge I Ignored Import was instructed to ignore the file by one of the cvsignore files L Link Symbolic links are always ignored N New The file was new and has been added to the repository U Update The file existed in the repository and the imported file was identical Table 23 import output log Display an activity log for specified files. cvs log [Options] <filename> [<filename> …] Option Description -b List revisions on the default branch -d <datespec> Report on the date or date range(s) -h Output the header only -N Suppress the output of tags -R Print RCS filename only -r <revisionspec> Report on the revisions specified -s <state> Report only revisions in <state> 102
  • 113. Command Reference -t Output only the header and description -w<username>[,<username>, …] Report only checkins by these users. There may not be a space between –w and its arguments Table 24 log command options Date Specification Description date1<date2 or date2>date1 Revisions between date1 and date2 exclusive date1<=date2 or date2>=date1 Revisions between date1 and date2 inclusive <date or date> Revisions before date <=date or date >= Revisions before or on date date< or >date Revisions after date date<= or >=date Revisions on or after date date Most recent revision before or on date Table 25 log command date specification Revision Specification Description revision1:revision2 Revisions from revision1 to revision2 inclusive :revision Revisions from the beginning of the branch to revision inclusive revision: Revisions from revision to the end of the branch inclusive branch All revisions in the branch branch1:branch2 All revisions on all branches between branch1 and branch2 inclusive branch. The last revision on branch Table 26 log command revision specification login Validates the username and requires a password. The user’s password is stored in the ~/.cvspass so that the client can provide this when required. This command is only applicable to CVS operation where a password server or other authentication method is running. cvs [Options] login Typically the options field would specify the connect string for the repository. logout This ends the user’s session and removes his password from the ~/.cvspass file cvs logout rdiff 103
  • 114. Configuration Management with CVS Runs a diff on two files or sets of files to produce a standard format patch file for updating one set of files to another. cvs rdiff [Options] <filename> [<filename> …] Option Description -c Context diff format (default) -D <date> Specify the dates for revisions -f Include files not containing the tag, or not present on the specified date -l Do not recurse -R Recurse into subdirectories -r <revision> Specify the revisions to compare -s Output a summary of changed files rather than a patch file -t Show differences between the two most recent revisions -u Unidiff format Table 27 rdiff command options release Release can be used to reverse a checkout. Although not strictly necessary, as CVS allows by default multiple users to check out files, using release has the advantage of making a record in the history file, and verifying the status of all files in the sandbox, before optionally deleting the files. cd <parentdirectory> cvs release [Option] <directory> Option Description -d Delete the sandbox Table 28 relese command option Before performing the optional delete, the release command checks the status of all files in the sandbox against the repository. Thus any commit actions which were intended, but were forgotten are flagged. Release prints a report with the following codes against each file specified Code Description A A file has been added but not committed to the repository M The working copy of the file has been modified U A newer version of the file exists in the P repository R A file has been removed but the remove has not been committed ? A file is present in the sandbox, but not in the repository 104
  • 115. Command Reference Table 29 release command output remove Remove one or more files from the repository. The remove is not actually performed until the files are committed. cvs remove [Options] <filename> [<filename> …] Option Description -f Delete the file from the sandbox -l Do not recurse -R Recurse into subdirectories Table 30 remove command options rtag Set a symbolic tag on a specified revision of a set of files: cvs rtag [Options] <tag> <filename> [<filename> …] This command operates solely on files in the repository, and does not examine files in the sandbox. Option Description -a Search the attic for removed files containing the tag -b Use a branch tag -d Delete the tag -D <date> Specify the dates for tagging -F Force , causes an existing tag to be moved to the new revision -f Include files not containing the tag, or not present on the specified date -l Do not recurse -n Do not run any tag program -R Recurse into subdirectories -r <revision> Specify the revision for tagging Table 31 rtag command options status Show the status of the selected files: cvs status [Options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories -v Verbose, includes tag information Table 32 status command options 105
  • 116. Configuration Management with CVS tag Assign a symbolic tag to the revisions of files in the current sandbox: cvs tag [Options] <filename> [<filename> …] Option Description -b Use a branch tag -c Check that files in the sandbox have not been modified without a commit -d Delete the tag -D <date> Specify the dates for tagging -F Force , causes an existing tag to be moved to the new revision -f Include files not containing the tag, or not present on the specified date -l Do not recurse -R Recurse into subdirectories -r <revision> Specify the revision for tagging Table 33 tag command options unedit Abandon file edit and make the file read-only, notifying watchers. cvs unedit [Options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories Table 34 unedit command options update Update the working copy of files in the sandbox, merging changes from the repository: cvs update [Options] <filename> [<filename> …] Option Description -A Reset sticky tags -d Create and update new directories -D <date> Use most recent revision no later than date -f Include most recent version of files where the tag does not exist, or the file did not exist on <date> -I <pattern> Ignore files matching this pattern -j <revision> Merge changes between the two revisions -k <kflags> Control keyword expansion -l Do not recurse -p Check out files to standard output -P Prune empty directories -R Recurse into subdirectories 106
  • 117. Command Reference -r <revision> Retrieve the revision or tag specified -W <wrapper> Specify files to be filtered during input Table 35 update command options update reports the status of the files examined with a status code. Status Description ? The file was present in the sandbox, but not in the repository A Added No action taken, cvs add has been performed but the file has not been committed C Conflict The sandbox copy of the file has been modified, but there was a conflict merging it with the latest version in the repository M Modified The sandbox copy was modified, and was merged successfully with the repository version P Patched The file was successfully updated, but the server used a patch R Removed No action taken because cvs remove had been run on the file, but the file had not been committed U Updated The file was updated Table 36 update command output watch The watch command allows a developer to be informed automatically if another user takes any action on a set of files: cvs watch [Options] <filename> [<filename> …] Option Description on Turn on watching off Turn off watching add Start watching files remove Stop watching files -a <action> Action to watch for -l Do not recurse -R Recurse into subdirectories Table 37 watch command options The actions possible are: Action Description all All these actions commit Changes have been committed edit A file is being edited 107
  • 118. Configuration Management with CVS none Default for edit unedit Changes have been removed Table 38 watch command actions watchers Displays a list of the users watching the files specified: cvs watchers [Options] <filename> [<filename> …] Option Description -l Do not recurse -R Recurse into subdirectories Table 39 watchers command options keyword substitution flags Flag Description -kkv Default form of keyword substitution -kkvl Add locker’s name, not normally used in CVS -kk Omit the value field. useful for displaying differences -ko Generate the keyword string as it would have appeared n the original file before it was checked in -kb As –ko but also suppress line ending translation. Required for binary files -kv generate only the value of the keyword, omitting the keyword itself Table 40 keyword substitution flags Admin Commands admin CVS also accepts adm or rcs for this command. If a cvsadmin user group exists, these commands will only be available to the group. Various administrative tasks are performed with this command. cvs admin [Options] [data] Option Description -b <revision> Set the default branch -k <kflags> Set default keyword substitution mode -L Enable strict locking. -l <revision> Lock the specified revision -m<revision>:<message> Set a revision’s log message -n<name>[:[<revision>]] Give the revision specified the symbolic name -N<name>[:[<revision>]] Give the revision specified the symbolic 108
  • 119. Command Reference name, and move the name if it exists --o<range> Delete the revisions specified -q Quiet mode -s<state>[:<revision>] Change the state of a revision -t<filename> Set descriptive text in the RCS file specified -t-<string> Set descriptive text in the RCS file specified to <string> -U Disable strict locking -u<revision> Unlock the specified revision Table 41 admin command options init Create a new repository: cvs init –d <root directory> kserver Starts CVS in kserver mode pserver Starts cvs in server mode 109
  • 120. Configuration Management with CVS Data Formats <tagname> [a-z,A-Z] *[a-z,A-Z,0-9,-,_] <branchname> The first character must be alphabetic, followed by any number of alphanumeric characters, together with the special characters ‘-‘ and ‘_’ <date> Although CVS recognises many date formats, the only two officially supported formats are ISO 8601, and RFC 1123 (email). ISO 8601: YYYY-MM-DD HH:MM [<timezone>] RFC 1123: 11 Nov 2002 Because these formats include spaces, dates normally need to be enclosed in quotation marks. <revision> An even number of digits separated by the ‘.’ character. Internally there may be revisions with an odd number of digits (for example representing a branch). Example: 4.1.7.5 <modulename> A valid directory name. This may differ between Windows and Unix systems. The space character in a pathname is problematic and should be avoided. <filename> A valid filename. This is system dependent, and spaces should be avoided. <kflags> Options for keyword expansion. The most common is for the treatment of binary files to suppress keyword expansion and line end conversion: -kb Table 42 Data Formats 110
  • 121. Command Reference Other Date Formats Although deprecated, these date formats are also supported, but may disappear in future versions. Format Description mm/dd/yy The U.S. date format month/day/year. This should be avoided as it is ambiguous in other countries. yesterday Although these formats might be useful for last Monday displaying a diff, their use for checkouts 10 minutes ago and commits can easily lead to erroneous 1 hour ago results. The strings need to be quoted to be 3 days ago interpreted correctly. 5 years ago Table 43 Other Date Formats Alternate Command Names Because of the historical evolution of SCCS, RCS and CVS, some commands have alternative names. Command Alternatives add ad, new annotate ann checkout co, get commit ci, com diff dif, di export ex, exp history hi, his import im, imp login logon, lgn log rlog, lo rdiff patch, pa release rel, re delete remove, rm rtag rfreeze, rt status stat, st tag freeze, ta update upd, up admin adm, rcs Table 44 Alternate Command Names 111
  • 123. Customisation C Appendix C - Customisation Various administrative files offer options to run programs or scripts on the occurrence of certain actions. CVS provides certain arguments to these routines, as shown below. modules Option Action Arguments -i commit module name -e export repository directory -o checkout module name -t tag module name, symbolic tag -u updated repository directory Table 45 modules file options Note that for checkout, export and rtag the program specified is run on the server (assuming that CVS is running in client/server mode), while for commit and update the program is run on the local machine. Programs run on the server are searched for in the path. Changes to the commit and update programs set in the modules file will not take effect until a new copy of the source affected is checked out, as the program names are copied into the CVS directory of the working copy on the client. The programs are first searched for in the working copy of the source, then in the path. On the client the programs are executed from the top level directory of the module. All the programs specified in the modules file run after the successful completion of the action. 113
  • 124. Configuration Management with CVS commitinfo Commitinfo allows the system administrator to specify scripts or programs to run before a file may be committed to the repository, the program being selected by a pattern match on the filename. Specification Arguments <regexp>, ALL, DEFAULT repository directory, filenames Table 46 commitinfo file options loginfo On a commit the log information can be directed to a program through the loginfo file. The information sent to the program may be selected from the filename, pre-commit and post-commit version numbers, using any or all of the format string %{sVv}.Loginfo programs run on the server in client/server mode. Specification Arguments <regexp>, ALL, DEFAULT repository directory, filenames and versions as selected, enclosed in quotes Table 47 loginfo file options verifymsg When committing a file to the repository a script may be run to verify that the required information has been supplied in the log message. The program runs on the server in client/server mode. Specification Arguments <regexp>, DEFAULT path to log message template file Table 48 verifymsg file options 114
  • 125. Common Tasks D Appendix D - Common Tasks In the following examples the action taken by CVS often relies on the current working directory to supply some of its arguments. Optionally the commands could be run from a higher level directory, specifying the files or modules to act on. Add a directory to a module cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # mkdir <directory name> cvsuser@oppenheimer work/<modulename> # cvs add <directory name> cvsuser@oppenheimer work/<modulename> # cvs commit [<directoryname>] Add a file to a module cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs add <filename> cvsuser@oppenheimer work/<modulename> # cvs commit [<filename>] Back out a change cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –j 1.3 –j 1.2 <filename> cvsuser@oppenheimer work/<modulename> # cvs commit [<filename>] Checkout a branch cvsuser@oppenheimer work # cd <modulename> 115
  • 126. Configuration Management with CVS cvsuser@oppenheimer work/<modulename> # cvs update –r <tagname> [<modulename>] or: cvsuser@oppenheimer work # cvs checkout –r <tagname> <modulename> Checkout a module cvsuser@oppenheimer work # cvs checkout <modulename> Commit a module cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs commit or: cvsuser@oppenheimer work # cvs commit <modulename> Create a branch cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs tag –b <tagname> or: cvsuser@oppenheimer work # cvs rtag –b <tagname> <modulename> Exclusive lock cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs admin –l <filename> Merge a branch cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –j <branchname> cvsuser@oppenheimer work/<modulename> # cvs commit Remove a file cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs remove <filename> cvsuser@oppenheimer work/<modulename> # cvs commit Remove a directory A directory is removed by removing all its files. To tidy up the working directory: cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –P 116
  • 127. Common Tasks Return the working directory to the current revision cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –A –d -P Tag a Release cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs tag <tagname> cvsuser@oppenheimer work/<modulename> # cvs commit or: cvsuser@oppenheimer work # cvs rtag –r <tagname> <modulename> Update a working directory cvsuser@oppenheimer work # cd <modulename> cvsuser@oppenheimer work/<modulename> # cvs update –d -P 117
  • 129. Resources E Appendix E – Resources Bugzilla http://www.bugzilla.org cervisia http://cervisia.sourceforge.net/ Cook http://www.canb.auug.org.au/~millerp/cook/cook.html cvsadmin http://freshmeat.net/projects/cvsadmin/ CSDiff http://www.componentsoftware.com/products/csdiff/ CVS http://www.cvshome.org/ CVSFAQ http://www.loria.fr/~molli/fom-serve/cache/1.html CVSGraph http://www.akhphd.au.dk/~bertho/cvsgraph/ CVSIn http://sourceforge.net/projects/cvsin/ cvsmenu.vim http://vim.sourceforge.net/script.php?script_id=58 cvsmonitor http://search.cpan.org/author/ADAMK/Bundle-CVSMonitor-0.6/ CVSNT http://www.cvsnt.org/ cvspwd http://www.loria.fr/cgi-bin/molli/wilma.cgi/rel.987302735.html cvsreport http://cvsreport.sourceforge.net/ cvstrac http://www.cvstrac.org/ cvstrac Windows http://cvs.cvstrac.org/wiki?p=CvstracOnWindows 119
  • 130. Configuration Management with CVS CVSup http://www.cvsup.org/ CVSWeb http://www.freebsd.org/projects/cvsweb.html CVSWebclient http://sourceforge.net/projects/cvswebclient/ CVSWebedit http://search.cpan.org/author/MRJC/cvswebedit-v2.0b1/ CVSZilla http://homepages.kcbbs.gen.nz/~tonyg/ dgdeletelocks.pl http://www.devguy.com/fp/cfgmgmt/cvs/ dgfindlocks.pl http://www.devguy.com/fp/cfgmgmt/cvs/ dgfixcvs.pl http://www.devguy.com/fp/cfgmgmt/cvs/ findlocks.pl http://www.devguy.com/fp/cfgmgmt/cvs/ Freepository https://www.freepository.com/ gcvs http://www.wincvs.org/ GNU Diffutils http://www.gnu.org/software/diffutils/diffutils.html Jam http://www.perforce.com/jam/jam.html lincvs http://www.lincvs.org/ mirror http://sunsite.doc.ic.ac.uk/packages/mirror/ Odin ftp: //ftp.cs.colorado.edu/pub/distribs/odin OpenSSH http://www.openssh.com/ pcl-cvs http://www.cvshome.org/cyclic/cvs/soft-pcl.html rdist http://www.magnicomp.com/rdist/ rsync http://rsync.samba.org/ sup http://gd.tuwien.ac.at tkdiff http://www.accurev.com/free/tkdiff/ TortoiseCVS http://www.tortoisecvs.org/ ViewCVS http://viewcvs.sourceforge.net/ WinCVS http://www.wincvs.org/ 120
  • 131. GNU Free Documentation Licence F Appendix F – GNU Free Documentation Licence Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0 PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals 121
  • 132. Configuration Management with CVS providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". 122
  • 133. GNU Free Documentation Licence Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY 123
  • 134. Configuration Management with CVS If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: • A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. • B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. 124
  • 135. GNU Free Documentation Licence • C. State on the Title page the name of the publisher of the Modified Version, as the publisher. • D. Preserve all the copyright notices of the Document. • E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. • F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. • G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. • H. Include an unaltered copy of this License. • I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. • J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. • K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. • L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. • M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. • N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. • O. Preserve any Warranty Disclaimers. 125
  • 136. Configuration Management with CVS If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS 126
  • 137. GNU Free Documentation Licence You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this 127
  • 138. Configuration Management with CVS License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. 128
  • 139. Index Index branchname, 112 . Bugzilla, 87, 121 Build Systems, 73 .# files, 55 Cook, 75 .cvsignore, 33 Jam, 75 .cvsrc, 35 Make, 75 .cvswrappers, 34 Odin, 75 A C Abandoning Changes, 52 cervisia, 121 add, 99 Cervisia, 69 Add a directory, 117 Changes, 45 Add a file, 117 checkin, 2 Adding, 41 Checkin.prog, 32 Adding and Removing Files, 41 checkout, 2, 99 admin, 110 Checkout a branch, 118 Admin Commands Checkout a module, 118 admin, 110 Checkout –p, 52 init, 111 checkoutlist, 24 kserver, 111 Client Command Options, 98 pserver, 111 Client Commands Administrative Tasks, 89 add, 99 Backup, 89 annotate, 99 CVS Defaults, 90 checkout, 99 Reset the Default Branch, 90 commit, 100 Tidying up the Repository, 89 diff, 100 Alternate Command Names, 113 edit, 101 annotate, 51, 99 editors, 102 Anonymous CVS, 83 export, 102 help, 102 B history, 103 Back out a change, 117 import, 104 Backing Out, 61 log, 104 Backup, 89 login, 105 Base, 30 logout, 105 Baserev, 30 rdiff, 105 Binary Files, 53 release, 106 branch, 2 remove, 107 Branch, 59 rtag, 107 Branches, 57 status, 107 129
  • 140. Configuration Management with CVS tag, 108 cvsadmin, 93, 121 unedit, 108 CVSEDITOR, 34 update, 108 CVSFAQ, 121 watch, 109 cvsgraph, 77 watchers, 110 CVSGraph, 121 Client/Server Mode, 12 cvsignore, 25 Code Organisation, 7 CVSIn, 70, 121 Command Format, 37 cvsmenu.vim, 121 Command Reference, 97 cvsmonitor, 93, 121 Commands, 99 CVSNT, 121 commit, 2, 100 CVSNT Differences, 15 Commit a module, 118 cvspwd, 94, 121 commitinfo, 24, 116 cvsreport, 93, 122 Common Options, 97 CVSROOT, 34 Common Steps, 11 CVSROOT Files, 30 Common Tasks, 117 cvstrac, 122 Add a directory, 117 Cvstrac, 85 Add a file, 117 CVSup, 122 Back out a change, 117 CVSWeb, 93, 122 Checkout a branch, 118 CVSWebclient, 122 Checkout a module, 118 CVSWebedit, 122 Commit a module, 118 cvswrappers, 26 Create a branch, 118 CVSZilla, 88, 122 exclusive lock, 118 Merge a branch, 118 D Remove a directory, 119 Data Formats, 112 Remove a file, 119 branchname, 112 Return the working directory to the current revision, 119 date, 112 Tag a release, 119 Filename, 112 kflags, 112 Update a working directory, 119 modulename, 112 config, 25 revision, 112 Configuration, 5 conflict, 2 tagname, 112 Connection and Authentication, 17 date, 112 Development, 43 Cook, 75, 121 dgdeletelocks.pl, 94, 122 Create a branch, 118 dgfindlocks.pl, 94, 122 CSDiff, 79, 121 dgfixcvs.pl, 94, 122 Customisation, 115 Customised Logging, 51 diff, 79, 100 CVS, 121 Diff, 52 Diff and Merge CVS Defaults, 90 CSDiff, 79 CVS_PASSFILE, 35 GNU Diff Utilities, 81 CVS_RSH, 34 WinMerge, 80 CVS_SERVER, 35 xxdiff, 81 130
  • 141. Index E Importing, 41 init, 111 edit, 101 Installation, 11 editinfo, 30 Introduction, 1 editors, 102 EMACS, 71 J Entries, 30 Entries.Backup, 31 Jam, 75, 122 Entries.Log, 31 Entries.Static, 31 K Environment Variables, 34, 95 Exclusive lock, 118 Kerberos 4, 20 Exclusive Locks, 54 Keyword Substitution, 53 export, 102 keyword substitution flags, 110 kflags, 112 kserver, 111 F filename, 112 L findlocks.pl, 94, 122 Freepository, 93, 122 lincvs, 122 Front Ends, 67 Lincvs, 70 Cervisia, 69 LockDir, 25 CVSIn, 70 log, 104 EMACS, 71 Log History, 49 gcvs, 68 LogHistory, 25 Lincvs, 70 login, 105 TortoiseCVS, 69 loginfo, 26, 116 WinCVS, 67 logout, 105 G M gcvs, 68, 122 Make, 75 Global Options, 97 merge, 2, 79 Glossary, 2 Merge a branch, 118 GNU Diff Utilities, 81 Merging, 60 GNU Free Documentation Licence, 123 mirror, 122 GSSAPI, 20 Mirror Sites, 63 modulename, 112 modules, 26, 115 H alias modules, 26 Hanging Locks, 32 regular modules, 27 head, 2 help, 102 N history, 26, 103 notify, 27 Notify, 31 I import, 104 131
  • 142. Configuration Management with CVS O Secure Shell, 18 Server Option, 98 Odin, 75, 122 Sizing, 7 OpenSSH, 122 Source Distribution, 63 Other Date Formats, 113 status, 107 Status, 48 P Sticky Options, 54 passwd, 28 Strange Files, 55 Password Server, 17 sup, 122 pcl-cvs, 122 SystemAuth, 25 Planning for Installation, 5 Problem Tracking, 85 T Bugzilla, 87 tag, 108 Cvstrac, 85 Tag, 32 CVSZilla, 88 Tag a release, 119 pserver, 111 taginfo, 28 tagname, 112 R Tags, 38 rcsinfo, 28 Template, 32 rdiff, 105 The Vendor Branch, 61 rdist, 122 Tidying up the Repository, 89 readers, 29 Times and Timezones, 8 release, 106 tip, 2 Releases, 57 tkdiff, 122 Remote Shell, 18 TopLevelAdmin, 25 remove, 107 TortioseCVS, 69 Remove a directory, 119 TortoiseCVS, 122 Remove a file, 119 Troubleshooting, 13 repository, 2 trunk, 3 Repository, 21, 32 Typographical Conventions, 2 Setup, 39 Repository Files, 30 U Reset the Default Branch, 90 unedit, 108 Resources, 121 Unix Systems, 11 Return the working directory to the update, 108 current revision, 119 Update a working directory, 119 revision, 3, 112 Update.prog, 32 Revisions, 37, 57 User Environment, 33 Root, 31 users, 29 rsync, 122 Utilities, 93 rtag, 107 cvsmonitor, 93 cvspwd, 94 S cvsreport, 93 sandbox, 3 CVSWeb, 93 132
  • 143. Index dgdeletelocks.pl, 94 W dgfindlocks.pl, 94 watch, 109 dgfixcvs.pl, 94 watchers, 110 findlocks.pl, 94 WinCVS, 67, 122 Freepository, 93 Windows Problems, 65 ViewCVS, 93 Windows Systems, 14 WinMerge, 80 V work area, 3 verifymsg, 28, 116 Working Copy, 43 ViewCVS, 93, 122 writers, 29 Visualising the Source Tree, 77 X xxdiff, 81 133