A primer to
using CVS
Rob M Baxter, Stephen P Booth,
Joachim Hein
Outline
• Using CVS
–
–
–
–
–
Existing repository
Finding out about its modules
Getting code in and out
Getting information about the repository contents
Tagging code versions
• Advanced topics
– Starting a repository
– Starting a module
– Branching & merging
• Getting help
M02:Using CVS
2
Why CVS?
• Why use CVS
–
–
–
–
Its open source and very widely used
It works on collections of files (modules)
It can access remote repositories across networks
Many/most IDE environments support CVS as a backend version
control system
– We like it.
• CVS weak points
– Automatic file versions numbers are per-file not per-project
– Change logs are per-file not per-project
– The subversion system addresses these issues and may
eventually replace CVS but its not as widespread as CVS yet.
M02:Using CVS
3
CVS commands I
• CVS consists of one program (called cvs) that can perform
many operations.
– Usage:
cvs [cvs-options] command [command-options and argments]
• The command keyword specifies which operation you want
– Some commands have alternative names
• The cvs-options control the general behaviour of cvs
• The command-options are specific to the command
• A small number of commands goes a long way
M02:Using CVS
4
CVS commands II
• Most commands take a list of files/directories/modules as an
argument but default to the current directory/module
• When operating on a directory/module all sub-directories are
automatically included in the operation.
• Use cvs --help for more information
M02:Using CVS
5
Starting work with CVS
• CVS stores file versions in a Repository
– A Repository is a directory tree.
– Your first step is to tell CVS where your repository is: $CVSROOT
– csh and tcsh users:
setenv CVSROOT /home/myid/cvsroot
– sh and bash users:
export CVSROOT=/home/myid/cvsroot
– Can also use -d flag
• You take a working copy of the files you need to edit
– Working copies store Repository and version information in a
sub-directory called CVS.
– Once you have a working copy it “remembers” where the
Repository is.
M02:Using CVS
6
Repository on a remote computer/network
• Repository on a remote computer: use $CVS_RSH to tell
CVS how to access (ssh is a good idea)
export CVS_RSH=ssh
export \
CVSROOT=':ext:<uid>@training.epcc.ed.ac.uk:/home/<uid>/c
vsroot'
• This will query password, unless you set up an ssh-agent
• If cvs is not on the default PATH on remote machine
export CVS_SERVER=/opt/local/bin/cvs
• There are other mechanisms but this is the most common
M02:Using CVS
7
Other configuration
• Choose your preferred editor, for when CVS needs input:
– export CVSEDITOR="emacs –nw"
– If $CVSEDITOR is unset, it checks: $EDITOR
• Consider putting into .profile, .bashrc, ...
• CVS also has a set of configuration files.
– These are stored in the Repository in a module called CVSROOT
– Unfortunate naming convention as CVSROOT != $CVSROOT
– To modify configuration files to need to:
– Check out working copy
– Edit files
– Commit changes to the Repository
– More on configuration files later..
M02:Using CVS
8
CVS repository
• CVSROOT contains
CVS admin files
– CVSROOT  $CVSROOT
• Projects are stored in
subdirectories
• *,v-files contain the
history of each file
• Removed files get
moved to the “Attic”
• Manipulate repository
via cvs commands only
• Defining modules helps
M02:Using CVS
9
Modules
• Many CVS commands work on modules
– Modules are useful collections of files
• At its simplest a module may just be a directory tree
• More complex modules can also be defined by using the
configuration files.
– However the default behaviour is to look for a directory tree in
the Repository with the same name as the module.
M02:Using CVS
10
Ready to go: Changing and retrieving files
• cvs co <module>
– “Check out”
– Extracts private working versions of files in module <module>
– Only use this the first time you create a working copy!
• cvs ci [files]
– “Check in”
– “Publishes” changed working files in the Repository
– Creates new file version numbers
• cvs update [files]
–
–
–
–
Retrieves most up-to-date versions from Repository
“Re-syncs” working files with Repository files
Doesn’t lose changes to working files
Only needed for multiple developer projects
M02:Using CVS
11
cvs co
• cvs co project/src/db
– Extracts private working versions from all files beneath directory
$CVSROOT/project/src/db/
– Puts them in subdirectory ./project/src/db/
• cvs co my_module
– Extracts working versions from whatever collection of directories or
files my_module refers to (in $CVSROOT/CVSROOT/modules,v)
– Puts them in subdirectory ./my_module/
– (Rem: unless -d specified in modules file)
– If no entry in modules file, defaults to first ‘directory’ behaviour
– Checks out all files in $CVSROOT/my_module/
• Recommendation: use modules
M02:Using CVS
12
cvs co
• Also creates a CVS subdirectory
– e.g. ./project/src/db/CVS
• This contains admin files for this working copy
– Entries, Root, Repository
– Internal CVS files
– Ignore them; certainly don’t delete them :-)
• Presence of this subdirectory usually tells you that this
directory is under CVS control
M02:Using CVS
13
cvs ci
• cvs 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
– Acts recursive if no files specified
• If 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 into your
working copy
– May have to resolve conflicts
M02:Using CVS
14
cvs update
• cvs 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
– If you want to go back to your most recent version, delete the file
and run update
M02:Using CVS
15
cvs update
• The only result to worry about is “conflict”
• The conflicting file now contains lines like
<<<<<<< filename
working version lines
=======
Repository version lines
>>>>>>> VN
where VN is the Repository version number
• Resolve this by hand editing & cvs ci
– May need to talk to author of version VN!
M02:Using CVS
16
cvs update -d
• Normally
cvs update
updates existing files and directories only
• Use -d option to get files and directories added (by others):
cvs update –d
• Consider what you need:
– Not using –d when needed: you loose out on latest additions
– Using –d when not needed: you might drown in stuff
M02:Using CVS
17
Adding and removing files
• cvs add <files>
– Marks files to be added to the current module in the Repository
– Must use this to let CVS know of new files
• cvs remove <files>
– Marks files to be removed from the current module in the Repository
– Files must be deleted from the working directory first
• Both commands only “flag” files
– Adds/removes not completed until cvs ci
M02:Using CVS
18
cvs add
• Schedule files for addition:
cvs add init.c map.c fcbridge.F
• Can also add new subdirectories:
bash$ cvs add subdir
bash$ cd subdir
bash$ cvs add <files>
• Must add subdir before adding files
• Important:
– Only after cvs ci will these be in the Repository!
M02:Using CVS
19
cvs remove
• cvs remove testHarness.c hacks.c
• Must actually delete working files first
bash$ rm oldfile
bash$ cvs remove oldfile
– Otherwise CVS complains (nice safety net!)
• To 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>
• Don’t forget the check in!
• Removed files get moved to the “Attic”
– They are not deleted from the repository (Thanks goodness!)
M02:Using CVS
20
Getting CVS information
• cvs 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
• cvs log [files]
– Lists revision history and check-in comments for each version of
[files]
• cvs diff [files]
– Lists all differences between current working versions and lastchecked-out versions of files in standard Unix diff format
M02:Using CVS
21
cvs status
• cvs status gui.h
cvs status: Examining .
============================================================
File: gui.h
Working revision:
Status: Locally Modified
1.3
Thu Nov 21 11:33:51 1996
Repository revision: 1.3
/home/me/CVS/project/include/gui.h,v
Sticky Tag:
(none)
Sticky Date:
(none)
Sticky Options:
(none)
• Useful before a ci or update
M02:Using CVS
22
cvs log
• cvs 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
...
M02:Using CVS
23
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
state: Exp;
lines: +7 -2
Changes for addition of simple.c.
---------------------------revision 1.16
date: 1996/10/01 11:14:32;
author: sally;
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 :-(.
---------------------------...
M02:Using CVS
24
cvs diff
• cvs 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
• The ‘<’ lines are the “official” version (1.3 here);
the ‘>’ lines are the working version
M02:Using CVS
25
cvs diff
• cvs diff answers the question
– “I’m working on version 1.3; what changes have I made to it?”
• You 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”
M02:Using CVS
26
cvs release
• You can use the UNIX rm to remove a working copy
– No checks whether there are non-committed changes
• Saver to use:
cvs release –d <directory_name>
– Goes into directory checks for uncommited changes
– Deletes the directory and all its files and sub-directories if successful
– Warning: Still no check for added files and directories which have not
been “cvs add” to the repository!
M02:Using CVS
27
Tags
• CVS can attach a tag to a set of files (e.g. release version)
• Useful to retrieve this set of files in this form at a later stage
• Recipe:
– Go to the module base directory of your local working copy
– Issue:
cvs tag –c <tag_name>
– This will attach the tag to all the files of the module (incl. subdirs)
– The –c option enables checking for locally modified files
• To retrieve a tagged module with name mymodule:
cvs co –r <tag_name> mymodule
– Only do this to make a read-only copy, you need to make a branch to
edit an old version
M02:Using CVS
28
More advanced
topics
M02:Using CVS
29
How to define explicit modules (recipe)
• Modules are defined in CVSROOT/modules inside the
repository
• To look at the file and manipulate it, get it out of the
repository:
cvs co CVSROOT/modules
• This will create a directory CVSROOT with a file modules
inside – do it in a sensible place
• Step into CVSROOT and display/edit the modules file
• Once done, commit change(s) with
cvs ci modules
• Step out of CVSROOT and remove it with:
cvs release –d CVSROOT
M02:Using CVS
30
How does a module file look?
• Think alias! A simple module file:
# this is a comment
project1 project1
project2 project2
pro2subA project2/subdirA
• 1st column: name of module (alias) and placement of
contents
• 2nd column: position in repository
• More advanced:
myproject –d thesubpro project5/subdirB/subsubdirV
will place contents of project5/subdirB/subsubdirV in
thesubpro
M02:Using CVS
31
Creating a CVS Repository
• Choose where you want the Repository to live
• Set the CVSROOT environment variable
– bash$ export CVSROOT=$HOME/MY_CVS
• Run cvs init
• What does this do?
– Creates the directory specified by $CVSROOT
– Creates the subdirectory of administrative files,
$CVSROOT/CVSROOT
• Your CVS Repository is now ready for use
M02:Using CVS
32
Starting a project
• Typically two cases:
– Someone hand you a source you have to work with
– Place source in a “nice” directory
– You start your own project from scratch
– Start the project in a “nice” directory, a simple file will do for the
beginning
• Use cvs import to place it into the repository
• Define a module
• Check that ok, by checking in out into a different location
– Consider rename of the original
• If ok:
– Important: Work on a checked out version
– Seriously consider deleting the original source
M02:Using CVS
33
cvs import
• cvs 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”
• import adds to the Repository but does not provide a
proper working version...
• Before further hacking, must cvs co a working version
M02:Using CVS
34
cvs import
• A standard “recipe” is:
– cd ~/my_projects/project1
– cvs import project1 project1 baseline
Rem: Imports code to $CVSROOT/project1
– [add new entry to modules file if desired]
– cd ..
– mv project1 project1.old
– cvs co project1
Rem: Extracts a proper working version with CVS admin directory
– rm -rf project1.old
M02:Using CVS
35
Branches
• Some people love them others hate them (management)
• Can be useful:
– Bug fixes for old releases
– Private parallel universe to develop a (set of) new feature(s)
– The set of features should be limited (single feature?)
– Once tested and ok: merge into the main source
– Recommendation: Merged branches should die (multiple merges
messy)
• Don’t use for different code versions
– Different branches don’t “inherit” from each other
– e.g. fixes to shared I/O routine
– Use: switches, compiler directives, build procedures etc.
M02:Using CVS
36
What is a branch
• Consider a single file
–
–
–
–
–
At Rev 1.2: Branch created  1.2.2.1
The branch evolved, total of three versions
The trunk evolved independently
At Rev 1.5: Branch merged into trunk
Advise: Don’t touch the branch after merge
• CVS works on modules not files:
– Branches affect different files at different revision numbers
– Use branch tags (symbolic names)
M02:Using CVS
37
Merging
• Needs care and communication inside the project group
• Recipe
– Check out the branch you want to merge into (normally the trunk):
cvs co my_module
– Step into it: cd my_module
– Merge the side branch named “dev-branch”
cvs update –j dev-branch
– Crucial: Resolve conflicts and check that it works
– Only once happy: cvs ci
• Remarks:
– Merges can add files
– Merges can move files to the “Attic”
M02:Using CVS
39
Help, further info
• CVS inbuilt help for subcommands:
cvs –H ci
cvs –H co
• Documentation:
P. Cederqvist et al.: “Version Management with CVS”,
various formats, extensive (PDF: 173 pages)
http://ximbiot.com/cvs/manual/
M02:Using CVS
40
Summary
• CVS is a tool
– Removes the need for multiple copies of similar code
– Modules ease working with extensive sources
– Introduces security net to code development
– Easy to go back
– Repository in different location from working version
– Enable multiple people to work on a single source
• CVS is no replacement for communication, policies and
management
• A few core commands will go a long way
– ci, co, update, add, remove, diff, status, log
M02:Using CVS
41