A Practical Introduction to CVS
Stephen Booth, Project Manager
A practical introduction to CVS
4Why choose CVS?
–
–
–
–
It’s free and widely available
It’s widely used in academia and industry
It offers multi-platform support (UNIX, NT, client-server)
It’s a “module level” tool rather than “file level”
• Better for managing code for whole software projects
– Its basic operation is very simple
– Its lack of file locking and its change merging process
encourage developers to talk to each other
– The author likes it :-)
2
Advanced Programming: Tools and Techniques - Session 3
1
Basic CVS concepts
4Global code repository
– Usually $HOME/CVS
– Stored in environment variable $CVSROOT
4Works with source-code modules
–
–
–
–
Often module = directory
Modules can be anything at all
Single CVS commands operate on all module source together
The key lies in the administrative modules file...
4CVS administrative files
– Live in $CVSROOT/CVSROOT (unfortunately...)
– Retrieve working version before editing
Advanced Programming: Tools and Techniques - Session 3
3
Creating a CVS Repository
4Choose where you want the Repository to live
4Set the CVSROOT environment variable
– bash$ export CVSROOT=$HOME/CVS
4Run cvs init
4What does this do?
– Creates the directory specified by $CVSROOT
– Creates the subdirectory of administrative files,
$CVSROOT/CVSROOT
4Your CVS Repository is now ready for use
4
Advanced Programming: Tools and Techniques - Session 3
2
Retrieving the CVS admin files
4Run cvs co CVSROOT from $HOME
4What does this do?
– “Checks out” a directory CVSROOT into $HOME
– CVSROOT contains working versions of modules etc.
4Deeply unfortunate naming convention:
– $CVSROOT is the Repository, usually $HOME/CVS
– $HOME/CVSROOT is the subdirectory containing CVS
administration files, not the Repository...
– So, $CVSROOT ≠ $HOME/CVSROOT
4Hope that’s clear...
Advanced Programming: Tools and Techniques - Session 3
5
Typical CVS setup
4Contents of $HOME
Repository
CVSROOT
Checked in files with
modules,v
revision history
project1
main.c,v
<other module directories>
CVSROOT
Working version of admin files
modules
my_projects
Private checked out copy of
project1
“project1” module
main.c
CVS
6
Advanced Programming: Tools and Techniques - Session 3
3
CVS modules
4The key to CVS is the CVSROOT/modules file
4Used to define modules in terms of files,
directories or other modules within the Repository
4CVS extracts / commits files at the module level
– A lot of CVS commands default to act on the current module
7
Advanced Programming: Tools and Techniques - Session 3
CVS modules
4A simple modules file:
# This is a comment
include
project/include
src
project/src
gui
project/src/gui
db
project/src/db
p-gui
-d src/gui project/src/gui
p-db
-d src/db project/src/db
4Define modules to be all files in named dirs
– Directories are relative to $CVSROOT/
4Use -d to rename a module directory for co
8
Advanced Programming: Tools and Techniques - Session 3
4
Key CVS commands
4All CVS commands prefixed by cvs command
– Importing new code wholesale
• cvs import
– Changing and retrieving files
• cvs co, cvs ci, cvs update
– Adding files to & removing files from a module
• cvs add, cvs remove
– Information and status
• cvs diff, cvs log, cvs status
4“Online help”? Use cvs -H <command>
– Gives synopsis of options for that command
– e.g. cvs -H import
9
Advanced Programming: Tools and Techniques - Session 3
cvs import
4Best way to add a whole source tree or module
– Create a project “baseline”
4cvs import <path> <tag-1> <tag-2>
– Creates directories in Repository: $CVSROOT/<path>
– Adds all files from current working directory, recursively
– Can use options to tell CVS to ignore certain files
– Tags are symbolic names for this “baseline”
4import adds to the Repository but does not
provide a proper working version...
4Before further hacking, must co a working version
10
Advanced Programming: Tools and Techniques - Session 3
5
cvs import
4A standard “recipe” is
– cd ~/my_projects/project1
cvs import project1 project1 baseline
• Imports code to $CVSROOT/project1
[add new entry to modules file if desired]
cd ~/my_projects
mv project1 project1.old
cvs co project1
• Extracts a proper working version with CVS admin directory
rm -rf project1.old
4After import is also a good time to define a
new module for the newly imported code
11
Advanced Programming: Tools and Techniques - Session 3
Changing and retrieving files
4cvs co <module>
– “Check out”
– Extracts private working versions of files in module <module>
4cvs ci [files]
– “Check in”
– “Publishes” changed working files in the Repository
– Creates new file version number
4cvs update [files]
– Retrieves most up-to-date versions from Repository
– “Re-syncs” working files with Repository files
– Doesn’t lose changes to working files
12
Advanced Programming: Tools and Techniques - Session 3
6
cvs co
4cvs co project/src/db
– Extracts private working versions from all files in directory
$CVSROOT/project/src/db/
– Puts them in subdirectory ./project/src/db/
4cvs co my_module
– Extracts working versions from whatever collection of directories
or files my_module refers to (in $HOME/CVSROOT/modules)
– Puts them in subdirectory ./my_module/
• (NB -d option in modules file)
– If no entry in modules file, defaults to first ‘directory’ behaviour
• Checks out all files in $CVSROOT/my_module/
13
Advanced Programming: Tools and Techniques - Session 3
cvs co
4Also creates a CVS subdirectory
– e.g. ./project/src/db/CVS
4This contains admin files for this module
– Entries, Root, Repository
– Internal CVS files
– Ignore them; certainly don’t delete them :-)
4Presence of this subdirectory usually tells you
that this directory is under CVS control
14
Advanced Programming: Tools and Techniques - Session 3
7
cvs ci
4cvs ci [files]
– For each specified file that has been changed (or each
changed file in the current module):
• Creates a new revision version in the Repository
• Adds a new “delta” to each ,v file with a new revision number
• Prompts for a “log message” to describe changes
• Automatically updates your working versions
4If someone got there first, CVS will complain
– If someone else has committed changes to the same files,
CVS will not let you overwrite them
– Must do an “update” first to merge any changes
– May have to resolve conflicts
15
Advanced Programming: Tools and Techniques - Session 3
cvs ci
4Any changes to working versions are not
“published” until check-in
– e.g. Files cvs add’ed or cvs remove’ed
16
Advanced Programming: Tools and Techniques - Session 3
8
cvs update
4cvs update file1 file2
– Retrieves latest checked-in versions of files if they differ from
your working ones (but doesn’t overwrite your changes)
– Reports on each file as it does it
• U file : “updated”, for unchanged or missing working files
• A file : “added”, for working files you’ve add’ed but not checked in
• R file : “removed”, for files you’ve remove’ed but not checked in
• M file : “modified”, for changed working files which have merged
successfully with any Repository changes
• C file : “conflict”, for changed working files whose changes conflict
with Repository changes (someone got there before you...)
• ? file : a file CVS knows nothing about
17
Advanced Programming: Tools and Techniques - Session 3
cvs update
4The only result to worry about is “conflict”
4The conflicting file now contains lines like
<<<<<<< filename
working version lines
=======
Repository version lines
>>>>>>> VN
where VN is the Repository version number
4Resolve this by hand editing & cvs ci
– May need to talk to author of version VN!
18
Advanced Programming: Tools and Techniques - Session 3
9
Adding and removing files
4cvs add <files>
– Marks files to be added to the current module in the Repository
– Must use this to let CVS know of new files
4cvs remove <files>
– Marks files to be removed from the current module in the
Repository
– Files must be deleted from the working directory first
4Both commands only “flag” files
– Adds/removes not completed until cvs ci
19
Advanced Programming: Tools and Techniques - Session 3
cvs add
4cvs add init.c map.c fcbridge.F
4Can also add new subdirectories:
bash$ cvs add subdir
bash$ cd subdir
bash$ cvs add <files>
4Must add subdir before adding files
20
Advanced Programming: Tools and Techniques - Session 3
10
cvs remove
4cvs remove testHarness.c hacks.c
4Must actually delete working files first
bash$ rm oldfile
bash$ cvs remove oldfile
– Otherwise CVS complains (nice safety net!)
4To cvs remove subdirs, they must be empty
bash$ rm subdir/<all files>
bash$ cvs remove subdir
– Does an implicit cvs remove on subdir/<all files>
4Don’t forget the check in!
4If you get it wrong, there’s always the Attic...
21
Advanced Programming: Tools and Techniques - Session 3
Getting CVS information
4cvs status [files]
– Gives a useful summary of status of [files] (or all files in
the module)
• working and Repository revisions
• whether working file is modified, add’ed, remove’d
• status of any symbolic tags
4cvs log [files]
– Lists revision history and check-in comments for each version
of [files]
4cvs diff [files]
– Lists all differences between current working versions and lastchecked-out versions of files in standard Unix diff format
22
Advanced Programming: Tools and Techniques - Session 3
11
cvs status
4cvs status gui.h
cvs status: Examining .
=================================================================
File: gui.h
Status: Locally Modified
Working revision:
1.3
Repository revision: 1.3
Sticky Tag:
Sticky Date:
Sticky Options:
Thu Nov 21 11:33:51 1996
/home/me/CVS/project/include/gui.h,v
(none)
(none)
(none)
4Useful before a ci or update
23
Advanced Programming: Tools and Techniques - Session 3
cvs log
4cvs log init.c
RCS file: /home/me/CVS/project/src/db/init.c,v
Working file: init.c
head: 1.18
branch:
locks: strict
access list:
symbolic names:
start: 1.1.1.1
project: 1.1.1
keyword substitution: kv
total revisions: 19;
selected revisions: 19
description:
---------------------------revision 1.18
...
24
Advanced Programming: Tools and Techniques - Session 3
12
cvs log
---------------------------revision 1.18
date: 1996/12/04 15:16:28; author: fred; state: Exp; lines: +2 -1
Added init code for new Freezers table.
---------------------------revision 1.17
date: 1996/11/27 09:05:56; author: sally; state: Exp; lines: +4 -1
Changes for addition of simple.c.
---------------------------revision 1.16
date: 1996/10/01 11:14:32; author: sally; state: Exp; lines: +7 -2
Fixed file error bug. Failure to open files led to attempting to
destroy a table not yet created. Hence, if you get the filename
wrong you get a bus error :-(.
---------------------------...
25
Advanced Programming: Tools and Techniques - Session 3
cvs diff
4cvs diff db.h
Index: db.h
======================================================
RCS file: /home/me/CVS/project/include/db.h,v
retrieving revision 1.3
diff -r1.3 db.h
57,58c57,58
< #define DB_TOOSMALL
-22
< #define DB_NOSPACE
-21
--> #define DB_TOOSMALL
-26
> #define DB_NOSPACE
-25
4The ‘<’ lines are the “official” version (1.3 here);
the ‘>’ lines are the working version
26
Advanced Programming: Tools and Techniques - Session 3
13
cvs diff
4cvs diff answers the question
– “I’m working on version 1.3; what changes have I made to it?”
4You can also ask
– “I’m working on version 1.3; has anyone checked in any new
versions, and if so, how does my working version differ from
the latest one?”
– Use cvs diff -r HEAD
• HEAD is a special symbolic name for the latest version in the
Repository, the “head of the tree”
27
Advanced Programming: Tools and Techniques - Session 3
WinCVS
4 GUI-based client for Windows/NT and 9x
– Working directory on NT system can talk to remote
repository on UNIX
– Uses standard Unix .rhosts access file
– Repository:
:server:<myname>@opal:/home/me/CVS
4Access to all CVS functionality
4Does the right thing with EOLs etc...
4http://www.wincvs.org/
28
Advanced Programming: Tools and Techniques - Session 3
14
CVSweb
4Web interface to standard CVS
– Bill Fenner, Henner Zeller, Henrik Nordström and Ken Coar
4Runs as CGI script, cgi-bin/cvsweb.cgi
4Ideal for distributed development
4http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/
29
Advanced Programming: Tools and Techniques - Session 3
CVSweb
30
Advanced Programming: Tools and Techniques - Session 3
15
Summary
4CVS is an excellent tool for software project
revision control
4Can be applied at start or midway through
4Has client-server version for cross-platform
development (eg. NT → Unix)
4A few core commands will go a long way
– ci, co, update, add, remove, diff, status, import
4Understanding modules file is key to unlocking
the power of CVS
4http://www.cyclic.com/cyclic-pages/cvs.html
31
Advanced Programming: Tools and Techniques - Session 3
CVS practical
4A practical example mimicking two codevelopers,
Fred and Sally
4Point your browser at
http://www.epcc.ed.ac.uk/~softdev/day1/cvsTest.html
32
Advanced Programming: Tools and Techniques - Session 3
16
A CVS cribsheet
4 Adding new files
– Create the files; cvs add the files; cvs ci
4 Adding new directories
– Create the directory; cvs add the directory; change into it and cvs
add its files; cvs ci
4 Deleting files
– Delete the files; cvs delete them; cvs ci
4 Deleting subdirectories
– Remove all files from the directory; cvs delete the directory (don't
delete the directory first); cvs ci
4 File or module status
– cvs status
4 File revision history
– cvs log
33
Advanced Programming: Tools and Techniques - Session 3
17