CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

CVS Step by Step Introduction

(text adapted from http://www.nas.nasa.gov/~edavis/cvs/index.html by Eric A. Davis)

CVS is a version control system that records the history of source les throughout development. Using CVS, you can easily retrieve old versions of source les to nd bugs, retrieve deleted content, etc. The main CVS manual can be found at the Cyclic Software homepage. Cyclic Software supports and maintains CVS and presents a list of links to CVS manuals, GUI applications, and other related information. This manual presents a step by step introduction to the use of the dierent CVS commands. It is suggested that you read through and understand what is presented in this basic manual before using the GLAST-IS UDINE cvs repository. The repository is located on svr0lx.ud.infn.it and can be accessed via the secure shell protocol. To use this repository you must have an account on svr0lx. CVS oers a couple help commands which display the usage information. This is very useful when trying to gure out the dierent command line arguments used by each of the CVS commands.
% cvs --help % cvs --help-commands % cvs <command> --help

1. Environment Variables:

Using a remote repository: To access the central repository located on svr0lx using ssh, set the following environment variables as shown.
(using csh or tcsh) % setenv CVSROOT :ext:<username>@svr0lx.ud.infn.it:/repository/glast-is % setenv CVS_RSH ssh (using sh or bash) % CVSROOT=:ext:<username>@svr0lx.ud.infn.it:/repository/glast-is % export CVSROOT % CVS_RSH=ssh % export CVS_RSH

Using a local repository: If you are new to CVS and want to experiment with it before using the main central repository, you can set up and test on a local CVS repository. The

1 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

following steps can be used for setting up a local CVS repository. First create a local repository somewhere on your system. For example, using the path /u/wk/edavis/cvsroot as the location for the CVS repository, the CVS init command is used to create the repository.
% cvs -d /u/wk/edavis/cvsroot init

Then set the following evironment variable to access this new local repository.
(using csh or tcsh) % setenv CVSROOT /u/wk/edavis/cvsroot (using sh or bash) % CVSROOT=/u/wk/edavis/cvsroot % export CVSROOT

2. Importing your sources for the rst time: Each collection of sources managed by CVS is called a module. You can create a new module by importing one from scratch, from an existing collection of sources, or from an existing RCS Repository. Importing a new module from scratch: First create the directory structure that is needed. Then move any les to be included for this module to the directories.
% % % % % mkdir ~/foobar cd ~/foobar mkdir foo bar mv ~/x foo mv ~/y bar

Once you are done setting up the directory structure you can then import it to the CVS repository. Make sure you are directly under the top level directory.
% pwd ~/foobar % cvs import foobar INFN start cvs import: Importing /u/wk/edavis/cvsroot/foobar/bar N foobar/bar/y cvs import: Importing /u/wk/edavis/cvsroot/foobar/foo N foobar/foo/x No conflicts created by this import

This import command tells CVS to create a new module named 'foobar' with the vendor name 'INFN' and the rst release-tag 'start'. CVS will then import the entire directory tree you created. You can now delete the directory tree you created because it is now stored in the CVS repository. Importing a new module from an existing collection of sources:

2 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

Assuming you have a tar le that contains the sources for a specic application, you can import these sources to the CVS repository using the same method above.
% tar -xvf foobar.tar x foobar/bar/y, 0 bytes, 0 blocks x foobar/foo/x, 0 bytes, 0 blocks % cd foobar % cvs import foobar NAS start cvs import: Importing /u/wk/edavis/cvsroot/foobar/bar N foobar/bar/y cvs import: Importing /u/wk/edavis/cvsroot/foobar/foo N foobar/foo/x No conflicts created by this import

Importing a new module from an RCS Repository: Check the CVS manual on how to import RCS les into a CVS Repository. 3. Checking out sources: To checkout the sources for a specic module use the CVS checkout command. Note that the module must have already been imported to the repository.
% cvs checkout foobar cvs checkout: Updating foobar cvs checkout: Updating foobar/bar U foobar/bar/y cvs checkout: Updating foobar/foo U foobar/foo/x

This will create a local copy of the module in your current working directory. Now you add les to, delete les from, and edit the module sources. (See section 9 below on how to release the sources when you are done.) 4. Updating your sources: When multiple developers are working on the same module, it is good practice to periodically check if the sources in the CVS repository have been modied since you last checked them out. The CVS di and update commands are used to ensure that your local copy of the module is current. The di command shows you which les are dierent and how they dier. If some les are dierent, then use the update command to update your local copy of the les with the new modications.
% cvs diff -D now cvs diff: Diffing cvs diff: Diffing cvs diff: Diffing foobar foobar foobar/bar foobar/foo

The above di command shows that no les have been modied and the local copy of the module is up to date. The following happens when a le has been modied by someone else and committed to the repository.
% cvs diff -D now foobar cvs diff: Diffing foobar

3 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

cvs diff: Diffing foobar/bar cvs diff: Diffing foobar/foo Index: foobar/foo/x =================================================================== RCS file: /u/wk/edavis/cvsroot/foobar/foo/x,v retrieving revision 1.2 retrieving revision 1.1.1.1 diff -r1.2 -r1.1.1.1 1d0 < text here % cvs update foobar cvs update: Updating foobar cvs update: Updating foobar/bar cvs update: Updating foobar/foo U foobar/foo/x

Here the le x has been modied since the last checkout. Use the CVS update command to incorporate the new modications from the repository to the local copy of the module. Note that there are various formats to the CVS date string (-D). Using the date now tells CVS to di the latest module sources in the repository. If the date yesterday were used, then CVS would di the latest revision from the previous day. Check the man page for the various correct formats. 5. Committing your changes: Once you are done making any modications to the module sources, you need to commit your changes to the CVS repository. This is done using the CVS commit command. Modify the les foobar/foo/x and foobar/bar/y and then commit them to the repository.
% cvs commit foobar cvs commit: Examining foobar cvs commit: Examining foobar/bar cvs commit: Examining foobar/foo cvs commit: Committing foobar/bar Checking in foobar/bar/y; /u/wk/edavis/cvsroot/foobar/bar/y,v <-- y new revision: 1.2; previous revision: 1.1 done cvs commit: Committing foobar/foo Checking in foobar/foo/x; /u/wk/edavis/cvsroot/foobar/foo/x,v <-- x new revision: 1.3; previous revision: 1.2 done

The commit command recursively traverses the foobar directory and commits any changes you have made. Here CVS showed that both the x and y les have been modied and committed to the repository. 6. Adding and removing source les: A source tree is constantly changing and there is often the need to add new les and delete existing les within the directory tree. This can be accomplished for a module using the CVS add and remove commands.

4 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

% cd foobar/foo % ls CVS/ x % touch z % ls CVS/ x z % cvs add z cvs add: scheduling file `z' for addition cvs add: use 'cvs commit' to add this file permanently % cd ../.. % cvs commit foobar cvs commit: Examining foobar cvs commit: Examining foobar/bar cvs commit: Examining foobar/foo cvs commit: Committing foobar/foo RCS file: /u/wk/edavis/cvsroot/foobar/foo/z,v done Checking in foobar/foo/z; /u/wk/edavis/cvsroot/foobar/foo/z,v <-- z initial revision: 1.1 done

As shown above, to add a le to the module, simply create the new le and execute the CVS add command. The add command tells CVS to import the new le when the next commit operation is performed. Now let's see what happens when a le is added and another deleted.
% cd foobar/bar % ls CVS/ y % mv y a % ls CVS/ a % cvs remove y cvs remove: scheduling `y' for removal cvs remove: use 'cvs commit' to remove this file permanently % cvs add a cvs add: scheduling file `a' for addition cvs add: use 'cvs commit' to add this file permanently % cd ../.. % cvs commit foobar cvs commit: Examining foobar cvs commit: Examining foobar/bar cvs commit: Examining foobar/foo cvs commit: Committing foobar/bar RCS file: /u/wk/edavis/cvsroot/foobar/bar/a,v done Checking in foobar/bar/a; /u/wk/edavis/cvsroot/foobar/bar/a,v <-- a initial revision: 1.1 done Removing y; /u/wk/edavis/cvsroot/foobar/bar/y,v <-- y new revision: delete; previous revision: 1.2 done

Above is an example of how to rename a le within the repository. Simply rename the le, do a CVS remove on the old lename, do a CVS add on the new lename, and nally commit the change to the repository.
5 of 11 02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

7. Tagging sources for symbolic revisions: To create a snapshot of the current sources for later use, use the CVS tag command. The tag command generates a symbolic tag that is bound to each of the current revisions in your local copy of the module. Try creating the tag release-1-2 and releasing the module.
% cvs tag -R release-1-2 foobar cvs tag: Tagging foobar cvs tag: Tagging foobar/bar T foobar/bar/a cvs tag: Tagging foobar/foo T foobar/foo/x T foobar/foo/z % cvs release -d foobar You have [0] altered files in this repository. Are you sure you want to release (and delete) module `foobar': y

This created the symbolic tag release-1-2 for the module. Now this tag can be specied during future checkouts. If you don't specify a symbolic tag during a checkout, the latest sources are pulled out of the repository. Now try checking out the release you just created.
% cvs checkout -r release-1-2 foobar cvs checkout: Updating foobar cvs checkout: Updating foobar/bar U foobar/bar/a cvs checkout: Updating foobar/foo U foobar/foo/x U foobar/foo/z

The above checkout command specied to grab the sources bound to the tag release-1-2. Not only can you tag the sources but you can also create a whole new branch to develop o of. This allows future development of an existing revision without disrupting the current development on the main branch. This is most useful for importing bug xes to past revisions. Note that branches can only be rooted at a tag that has been applied to the sources. Assuming you have already checked out the release-1-2 version of the foobar module, try creating a branch called release-1-2-fix and then release the module.
% cvs tag -b release-1-2-fix foobar cvs tag: Tagging foobar cvs tag: Tagging foobar/bar T foobar/bar/a cvs tag: Tagging foobar/foo T foobar/foo/x T foobar/foo/z % cvs release -d foobar You have [0] altered files in this repository. Are you sure you want to release (and delete) module `foobar': y

Here a branch has been created from the symbolic tag release-1-2 named release1-2-fix. To check out the sources on a branch simply specify the branch tag during the checkout.

6 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

% cvs checkout -r release-1-2-fix foobar cvs checkout: Updating foobar cvs checkout: Updating foobar/bar U foobar/bar/a cvs checkout: Updating foobar/foo U foobar/foo/x U foobar/foo/z % cvs release -d foobar You have [0] altered files in this repository. Are you sure you want to release (and delete) module `foobar': y

If a branch is checked out then all changes made to the module are done to the branch and future commits will not aect the main development trunk. You can also merge a branch into the main trunk using the CVS update command. Be very careful when merging two trunks as many conicts will result. Check the CVS manual on how to merge two dierent development trunks. 8. Checking the status: The CVS log and status commands are used to display the current status of the locally checked out module. The CVS log command will display all the logs for the le/s and the status command will display the current revision numbers and any symbolic tags that have been created. Here is the output of both the log and status commands after all the examples above have been performed.
% cvs checkout foobar cvs checkout: Updating foobar cvs checkout: Updating foobar/bar U foobar/bar/a cvs checkout: Updating foobar/foo U foobar/foo/x U foobar/foo/z % cvs log foobar cvs log: Logging foobar cvs log: Logging foobar/bar RCS file: /u/wk/edavis/cvsroot/foobar/bar/a,v Working file: foobar/bar/a head: 1.1 branch: locks: strict access list: symbolic names: release-1-2-fix: 1.1.0.2 release-1-2: 1.1 comment leader: "# " keyword substitution: kv total revisions: 1; selected revisions: 1 description: ---------------------------revision 1.1 date: 1998/05/27 19:49:09; author: edavis; state: Exp; renamed the file y to a ============================================================================= RCS file: /u/wk/edavis/cvsroot/foobar/bar/Attic/y,v

7 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

Working file: foobar/bar/y head: 1.3 branch: locks: strict access list: symbolic names: start: 1.1.1.1 NAS: 1.1.1 comment leader: "# " keyword substitution: kv total revisions: 4; selected revisions: 4 description: ---------------------------revision 1.3 date: 1998/05/27 19:49:09; author: edavis; state: renamed the file y to a ---------------------------revision 1.2 date: 1998/05/27 19:20:49; author: edavis; state: changed the file y ---------------------------revision 1.1 date: 1998/05/27 18:47:12; author: edavis; state: branches: 1.1.1; Initial revision ---------------------------revision 1.1.1.1 date: 1998/05/27 18:47:12; author: edavis; state: Initial import of the foobar module

dead;

lines: +0 -0

Exp;

lines: +1 -0

Exp;

Exp;

lines: +0 -0

============================================================================= cvs log: Logging foobar/foo RCS file: /u/wk/edavis/cvsroot/foobar/foo/x,v Working file: foobar/foo/x head: 1.3 branch: locks: strict access list: symbolic names: release-1-2-fix: 1.3.0.2 release-1-2: 1.3 start: 1.1.1.1 NAS: 1.1.1 comment leader: "# " keyword substitution: kv total revisions: 4; selected revisions: 4 description: ---------------------------revision 1.3 date: 1998/05/27 19:20:55; author: edavis; state: Exp; changed the file y changed the file x ---------------------------revision 1.2 date: 1998/05/27 18:50:38; author: edavis; state: Exp; changed file x ---------------------------revision 1.1

lines: +1 -0

lines: +1 -0

8 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

date: 1998/05/27 18:47:12; author: edavis; branches: 1.1.1; Initial revision ---------------------------revision 1.1.1.1 date: 1998/05/27 18:47:12; author: edavis; Initial import of the foobar module

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html
state: Exp;

state: Exp;

lines: +0 -0

============================================================================= RCS file: /u/wk/edavis/cvsroot/foobar/foo/z,v Working file: foobar/foo/z head: 1.1 branch: locks: strict access list: symbolic names: release-1-2-fix: 1.1.0.2 release-1-2: 1.1 comment leader: "# " keyword substitution: kv total revisions: 1; selected revisions: 1 description: ---------------------------revision 1.1 date: 1998/05/27 19:43:14; author: edavis; state: Exp; added the file z ============================================================================= % cvs status -v foobar cvs status: Examining foobar cvs status: Examining foobar/bar =================================================================== File: a Status: Up-to-date Working revision: Repository revision: Sticky Tag: Sticky Date: Sticky Options: Existing Tags: release-1-2-fix release-1-2 1.1 1.1 (none) (none) (none) Wed May 27 19:49:09 1998 /u/wk/edavis/cvsroot/foobar/bar/a,v

(branch: 1.1.2) (revision: 1.1)

cvs status: Examining foobar/foo =================================================================== File: x Status: Up-to-date Working revision: Repository revision: Sticky Tag: Sticky Date: Sticky Options: Existing Tags: release-1-2-fix release-1-2 start 1.3 1.3 (none) (none) (none) Wed May 27 19:20:55 1998 /u/wk/edavis/cvsroot/foobar/foo/x,v

(branch: 1.3.2) (revision: 1.3) (revision: 1.1.1.1)

9 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

NAS

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html
(branch: 1.1.1)

=================================================================== File: z Status: Up-to-date Working revision: Repository revision: Sticky Tag: Sticky Date: Sticky Options: Existing Tags: release-1-2-fix release-1-2 1.1 1.1 (none) (none) (none) Wed May 27 19:43:14 1998 /u/wk/edavis/cvsroot/foobar/foo/z,v

(branch: 1.1.2) (revision: 1.1)

9. When you are done: When you are done making your changes to the module, use the CVS release command. Since CVS does not create locks, the release command isn't necessary although it is still a good idea to use. The release command will check to ensure that no uncommitted changes exist. Modify the le foobar/foo/z and let's see what happens when the release command is executed.
% cvs release -d foobar M foo/z You have [1] altered files in this repository. Are you sure you want to release (and delete) module `foobar': n ** `release' aborted by user choice.

Oops, the le z has been edited and not committed to the repository. Better nd out what has changed.
% cvs diff foobar/foo/z Index: foobar/foo/z =================================================================== RCS file: /u/wk/edavis/cvsroot/foobar/foo/z,v retrieving revision 1.1 diff -r1.1 z 0a1,2 > file changed >

If you don't care about the changes then simply release the local copy:
% cvs release -d foobar M foo/z You have [1] altered files in this repository. Are you sure you want to release (and delete) module `foobar': y

Else commit the changes and then release the local copy:
% cvs commit foobar cvs commit: Examining foobar cvs commit: Examining foobar/bar cvs commit: Examining foobar/foo cvs commit: Committing foobar/foo Checking in foobar/foo/z; /u/wk/edavis/cvsroot/foobar/foo/z,v

<--

10 of 11

02/24/2013 11:38 PM

CVS: step by step introduction

http://www.sica.uniud.it/~glast/sw/cvs/cvsintro.html

new revision: 1.2; previous revision: 1.1 done % cvs release -d foobar You have [0] altered files in this repository. Are you sure you want to release (and delete) module `foobar': y

11 of 11

02/24/2013 11:38 PM