A primer to using CVS

Rob M Baxter, Stephen P Booth,

Joachim Hein

M02:Using CVS 2

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 3

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 4

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 5

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 6

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 7

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>/cvsroot'

• This will query password, unless you set up an ssh-agent

• If cvs is not on the default PATH on remote machineexport CVS_SERVER=/opt/local/bin/cvs

• There are other mechanisms but this is the most common

M02:Using CVS 8

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 9

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 10

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 11

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 12

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 13

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 14

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 15

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 16

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 17

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 18

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 19

cvs add

• Schedule files for addition:cvs add init.c map.c fcbridge.F

• Can also add new subdirectories:bash$ cvs add subdirbash$ cd subdirbash$ cvs add <files>

• Must add subdir before adding files

• Important: – Only after cvs ci will these be in the Repository!

M02:Using CVS 20

cvs remove• cvs remove testHarness.c hacks.c

• Must actually delete working files firstbash$ rm oldfilebash$ cvs remove oldfile

– Otherwise CVS complains (nice safety net!)

• To cvs remove subdirs, they must be emptybash$ 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 21

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 last-

checked-out versions of files in standard Unix diff format

M02:Using CVS 22

cvs status

• cvs status gui.hcvs status: Examining .

============================================================

File: gui.h Status: Locally Modified

Working revision: 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 23

cvs log

• cvs log init.cRCS 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 24

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 :-(.

----------------------------

...

M02:Using CVS 25

cvs diff

• cvs diff db.hIndex: 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 26

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 27

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 28

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 29

More advanced topics

M02:Using CVS 30

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) withcvs ci modules

• Step out of CVSROOT and remove it with:cvs release –d CVSROOT

M02:Using CVS 31

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 32

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 33

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 34

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 35

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 project1Rem: Extracts a proper working version with CVS admin directory

– rm -rf project1.old

M02:Using CVS 36

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 37

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 39

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 40

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 41

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