click me  


  

CVS Commands

by Jeff Hunter, Sr. Database Administrator

Contents

  1. Overview
  2. CVS Quick Reference Card
  3. Creating a CVS Repository
  4. Logging into a CVS Repository
  5. Importing Projects into CVS
  6. Removing Projects from CVS
  7. Exporting Modules from CVS
  8. Viewing Changes / Updates To Your Sandbow But Without Actually Making Any Changes
  9. Adding Directories to CVS
  10. Adding Files to CVS
  11. Checking Out Files from CVS
  12. Tagging Files in CVS

Overview

This article provides many common CVS commands for administering and working with CVS. All commands were run on Sun Solaris 2.8 using CVS Release 1.11.14.

CVS Quick Reference Card

Before going into my CVS command summary and examples, I ran across an excellent CVS reference card that documents many of the useful commands and options for users of CVS. The reference card was written by Laurent Grégoire <laurent.gregoire@icam.fr>.

The latest version of Laurent's CVS reference card can be downloaded from http://tnerual.eriogerg.free.fr/ or here at www.idevelopment.info.


Creating a CVS Repository

The following set of commands will create a CVS repository in the directory /var/lib/cvsroot: 
# mkdir /var/lib/cvsroot
# chgrp cvsdev /var/lib/cvsroot
# chmod g+srwx /var/lib/cvsroot
# cvs -d /var/lib/cvsroot init
# chown -R cvs /var/lib/cvsroot

# ls -l /var/lib
total 2
drwxrwsr-x   3 cvs      cvsdev       512 Jan 23 19:22 cvsroot

# ls -la /var/lib/cvsroot
total 6
drwxrwsr-x   3 root     cvsdev       512 Jan 23 19:22 .
drwxr-xr-x   3 root     other        512 Jan 23 19:18 ..
drwxrwsr-x   3 cvs      cvsdev      1024 Jan 23 19:22 CVSROOT

Logging into a CVS Repository

Local Repository
With a local CVS Repository, you simply need to set your CVSROOT environment variable to the location of the CVS Repository as in the following example: 
% CVSROOT=/var/lib/cvsroot
% export CVSROOT
Remote Repository 
% CVSROOT=:pserver:<username>@<computername>:<repository>
Login to a remote CVS repository using the :pserver: protocol. The CVS server is named alex and my user name is oracle. Keep in mind that I needed to first create the local user, oracle, on the CVS host. (Which, again, in this example is named alex.) 
% CVSROOT=:pserver:oracle@alex:/var/lib/cvsroot
% cvs login
Logging in to :pserver:oracle@alex:/var/lib/cvsroot
CVS password: *******

Importing Projects into CVS 

% cd /tmp
% mkdir ProjectX
% touch ProjectX/File1.java
% touch ProjectX/File2.java
% touch ProjectX/File3.java
% cd ProjectX
% cvs import ProjectX INITIAL start
Ensure that you now backup and remove the original ProjectX working directory and checkout the newly imported module when you need to work on it: 
% rm -rf ProjectX
% cvs co ProjectX
U ProjectX/File1.java
U ProjectX/File2.java
U ProjectX/File3.java

Removing Projects from CVS

Removing a project (or other directory structure) from CVS can be done by logging into the CVS repository. 
% cd /var/lib/cvsroot

% ls -l
total 4
drwxrwsr-x   3 cvs      cvsdev      1024 Jan 23 19:30 CVSROOT/
drwxrwsr-x   2 oracle   cvsdev       512 Jan 24 19:38 ProjectX/

% rm -rf ProjectX

Exporting Modules from CVS

The syntax is: 
cvs export -r tag module
For example, to export from the HEAD of the ProjectX module: 
% cvs export -r HEAD ProjectX

Viewing Changes / Updates To Your Sandbow But Without Actually Making Any Changes

You will need to use the -nq argument.

For example, if there were no changes made by you (or by others that have committed changes to the repository), you would simply get your prompt back: 

% cvs -nq update
%
If there were changes, however, then you would see those changes that CVS would want to apply. Those changes, however, will not be made to your sandbox. 
% cvs -nq update
U TestCvsWS/TestCvsPRJ/src/info/idevelopment/PrintName.java
%

Adding Directories to CVS

To add a directory: 
cvs add <directory name>
In the following example, I created a directory called new_stuff: 
% cd ProjectX
% mkdir new_stuff
% cvs add new_stuff
Directory /var/lib/cvsrepos/ProjectX/new_stuff added to the repository

Adding Files to CVS

To add a file(s) to CVS: 
cvs add <file name(s)>
In the following example, I will use the directory I created above (new_stuff) and create several files within that directory: 
% cd new_stuff
% touch a.txt
% touch b.txt
% touch c.txt
% cvs add *.txt
cvs add: scheduling file `a.txt' for addition
cvs add: scheduling file `b.txt' for addition
cvs add: scheduling file `c.txt' for addition
cvs add: use 'cvs commit' to add these files permanently

% cvs commit -m "Added new files"
cvs commit: Examining .
RCS file: /var/lib/cvsrepos/ProjectX/new_stuff/a.txt,v
done
Checking in a.txt;
/var/lib/cvsrepos/ProjectX/new_stuff/a.txt,v  <--  a.txt
initial revision: 1.1
done
RCS file: /var/lib/cvsrepos/ProjectX/new_stuff/b.txt,v
done
Checking in b.txt;
/var/lib/cvsrepos/ProjectX/new_stuff/b.txt,v  <--  b.txt
initial revision: 1.1
done
RCS file: /var/lib/cvsrepos/ProjectX/new_stuff/c.txt,v
done
Checking in c.txt;
/var/lib/cvsrepos/ProjectX/new_stuff/c.txt,v  <--  c.txt
initial revision: 1.1
done

Checking Out Files from CVS

To checkout a project / module: 
cvs co <project / module name>
In the following example, I will checkout ProjectX: 
% cvs co ProjectX
cvs checkout: Updating ProjectX
U ProjectX/File1.java
U ProjectX/File2.java
U ProjectX/File3.java
cvs checkout: Updating ProjectX/new_stuff
U ProjectX/new_stuff/a.txt
U ProjectX/new_stuff/b.txt
U ProjectX/new_stuff/c.txt
You can also checkout individual files without including their directory structure. For example, I want to checkout the files a.txt, b.txt, and c.txt but without any of the directory structure. I want the files checked out to the current directory I am in: 
% cvs co -d . ProjectX/new_stuff
cvs checkout: Updating .
U a.txt
U b.txt
U c.txt
Or I can include a directory name to checkout to. For example, I want to checkout the same files into a directory named working: 
% cvs co -d working ProjectX/new_stuff
cvs checkout: Updating working
U working/a.txt
U working/b.txt
U working/c.txt

Tagging Files in CVS


Check Out Fresh Copy of ProjectX

For the examples in this section, I am going to checkout a fresh copy of ProjectX: 

% cvs co ProjectX
cvs checkout: Updating ProjectX
U ProjectX/File1.java
U ProjectX/File2.java
U ProjectX/File3.java
U ProjectX/File4.pl
U ProjectX/File5.c
cvs checkout: Updating ProjectX/documents
U ProjectX/documents/TestDocument.doc
cvs checkout: Updating ProjectX/new_stuff
U ProjectX/new_stuff/a.txt
U ProjectX/new_stuff/b.txt
U ProjectX/new_stuff/c.txt
cvs checkout: Updating ProjectX/new_stuff2

% cd ProjectX


Tagging Only One File

Let's start this example by tagging only one file. In most cases, this will not be what you will be doing when tagging files in CVS. CVS tags are generally used to record the history of a group of files, as when they apply to a certain version of a software package. This example should, however, provide a basic understanding to how tags work in CVS. With that in mind, let's tag the the file documents/TestDocument.doc (in our ProjectX example) with the tag name Prod1: 

% cvs tag Prod1 documents/TestDocument.doc
T documents/TestDocument.doc


Check Out Tagged Version of ProjectX

Now let's move up a directory and remove the entire ProjectX sandbox environment: 

% cd ..
% ls
ProjectX/
% rm -rf ProjectX
After removing our sandbox, let's see how to check out only those files (actually, there is only one file in our example named TestDocument.doc) into a sandbox area. To checkout files that belong to a tag, use the -r option of the cvs tag command: 
% cvs co -r Prod1 ProjectX
cvs checkout: Updating ProjectX
cvs checkout: Updating ProjectX/documents
U ProjectX/documents/TestDocument.doc
cvs checkout: Updating ProjectX/new_stuff
cvs checkout: Updating ProjectX/new_stuff2

% cd ProjectX
If you were to take a look at the sandbox that you checked out, there is only one file and that is documents/TestDocument.doc as this is the only file in our module that is contained within the Prod1 tag.


View Tag Information using cvs status

The easiest way to determine which tags exist on a file, is to use the cvs status -v command. Let's give an example of that: 

% cvs status -v documents/TestDocument.doc

===================================================================
File: TestDocument.doc  Status: Up-to-date

   Working revision:    1.4     Tue Jun  1 22:27:14 2004
   Repository revision: 1.4     c:/var/lib/cvsrepos/ProjectX/documents/TestDocument.doc,v
   Expansion option:    b
   Commit Identifier:   92840bd02c10000
   Sticky Tag:          Prod1 (revision: 1.4)
   Sticky Date:         (none)
   Sticky Options:      -kb
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.4)
As you can see, the cvs status command provides a wealth of information about files in CVS. In particular, we were looking for which tags where made on this file. (Keep in mind that a single revision of a file can be marked by many different tag names. For example, The same revision of the file (1.4 in our example above), can contain tag names like Prod1, QA1, Dev1. All of these tags would refer to the same file and revision.)


View Tag Information using cvs log

We can also use the cvs log command to determine which tags are marked on this file. Let's give an example of that: 

% cvs log -h documents/TestDocument.doc

RCS file: c:/var/lib/cvsrepos/ProjectX/documents/TestDocument.doc,v
Working file: documents/TestDocument.doc
head: 1.4
branch:
locks: strict
access list:
symbolic names:
        Prod1: 1.4
keyword substitution: b
total revisions: 4
=============================================================================
As you can see, the cvs log command provides a wealth of information about files in CVS. In particular, we were looking for which tags where made on this file. (Keep in mind that a single revision of a file can be marked by many different tag names. For example, The same revision of the file (1.4 in our example above), can contain tag names like Prod1, QA1, Dev1. All of these tags would refer to the same file and revision.)

Remove the Prod1 Tag

Now that we have played around with this one file, let's see how we would remove a tag from a file (or group of files). For this example, I want to remove the Prod1 tag name from documents/TestDocument.doc. To do this, we would use the -d option of the cvs tag command: 

% cvs tag -d Prod1 documents/TestDocument.doc
D documents/TestDocument.doc


Check Out Fresh Copy of ProjectX

% cd ..
% rm -rf ProjectX
Now let's checkout a fresh copy of ProjectX to demonstrate how tagging may work on a real software project: 
% cvs co ProjectX
U ProjectX/File1.java
U ProjectX/File2.java
U ProjectX/File3.java
U ProjectX/File4.pl
U ProjectX/File5.c
cvs checkout: Updating ProjectX/documents
U ProjectX/documents/TestDocument.doc
cvs checkout: Updating ProjectX/new_stuff
U ProjectX/new_stuff/a.txt
U ProjectX/new_stuff/b.txt
U ProjectX/new_stuff/c.txt
cvs checkout: Updating ProjectX/new_stuff2

% cd ProjectX
At this point, I am confident that I have all files (and their correct revision) checked out into my sandbox that should be considered stable and ready to tag as production - release 1. The tagging method I am going to perform will tag all files in the repository according the revision numbers of each file checked out in my sandbox. 
% cvs tag Prod1
cvs tag: Tagging .
T File1.java
T File2.java
T File3.java
T File4.pl
T File5.c
cvs tag: Tagging documents
T documents/TestDocument.doc
cvs tag: Tagging new_stuff
T new_stuff/a.txt
T new_stuff/b.txt
T new_stuff/c.txt
cvs tag: Tagging new_stuff2
The tag process in the above example, took note of all files (and their revision number) in ProjectX and tagged them in the CVS repository.


View Tag Information using cvs status

Now let's take a look at the status of all files in our project (using the -v argument to capture tag information): 

% cvs status -v

cvs status: Examining .
===================================================================
File: File1.java        Status: Up-to-date

   Working revision:    1.4     Wed Jun  2 15:32:39 2004
   Repository revision: 1.4     c:/var/lib/cvsrepos/ProjectX/File1.java,v
   Expansion option:    kv
   Commit Identifier:   dd040bdf3160000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.4)
        release-1                       (revision: 1.2)
        start                           (revision: 1.1.1.1)
        INITIAL                         (branch: 1.1.1)

===================================================================
File: File2.java        Status: Up-to-date

   Working revision:    1.3     Wed Jun  2 17:30:42 2004
   Repository revision: 1.3     c:/var/lib/cvsrepos/ProjectX/File2.java,v
   Expansion option:    kv
   Commit Identifier:   d6040be0ec10000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.3)
        release-1                       (revision: 1.2)
        start                           (revision: 1.1.1.1)
        INITIAL                         (branch: 1.1.1)

===================================================================
File: File3.java        Status: Up-to-date

   Working revision:    1.2     Mon Mar 15 22:17:12 2004
   Repository revision: 1.2     c:/var/lib/cvsrepos/ProjectX/File3.java,v
   Expansion option:    kv
   Commit Identifier:   112040562b5d0000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.2)
        release-1                       (revision: 1.2)
        start                           (revision: 1.1.1.1)
        INITIAL                         (branch: 1.1.1)

===================================================================
File: File4.pl          Status: Up-to-date

   Working revision:    1.3     Wed Jun  2 17:52:19 2004
   Repository revision: 1.3     c:/var/lib/cvsrepos/ProjectX/File4.pl,v
   Expansion option:    kv
   Commit Identifier:   d7840be13d20000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.3)

===================================================================
File: File5.c           Status: Up-to-date

   Working revision:    1.1     Wed Jun  2 17:52:19 2004
   Repository revision: 1.1     c:/var/lib/cvsrepos/ProjectX/File5.c,v
   Expansion option:    kv
   Commit Identifier:   d7840be13d20000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.1)

cvs status: Examining documents
===================================================================
File: TestDocument.doc  Status: Up-to-date

   Working revision:    1.4     Tue Jun  1 22:27:14 2004
   Repository revision: 1.4     c:/var/lib/cvsrepos/ProjectX/documents/TestDocument.doc,
   Expansion option:    b
   Commit Identifier:   92840bd02c10000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      -kb
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.4)

cvs status: Examining new_stuff
===================================================================
File: a.txt             Status: Up-to-date

   Working revision:    1.1     Tue Jun  1 21:30:50 2004
   Repository revision: 1.1     c:/var/lib/cvsrepos/ProjectX/new_stuff/a.txt,v
   Expansion option:    kv
   Commit Identifier:   de840bcf5890000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.1)

===================================================================
File: b.txt             Status: Up-to-date

   Working revision:    1.1     Tue Jun  1 21:30:50 2004
   Repository revision: 1.1     c:/var/lib/cvsrepos/ProjectX/new_stuff/b.txt,v
   Expansion option:    kv
   Commit Identifier:   de840bcf5890000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.1)

===================================================================
File: c.txt             Status: Up-to-date

   Working revision:    1.1     Tue Jun  1 21:30:50 2004
   Repository revision: 1.1     c:/var/lib/cvsrepos/ProjectX/new_stuff/c.txt,v
   Expansion option:    kv
   Commit Identifier:   de840bcf5890000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.1)

cvs status: Examining new_stuff2
OK. So at this point, we have tagged the revision's of files that I have checked out into my sandbox with the Prod1 tag. Think about this as "Saving" a stable copy of our project using the file revision numbers that I have checked out in my sandbox. Someone could now come along and check out this stable release of our project by checking out the project using the Prod1 tag.


Checking Out A Tagged Version of the Project

The syntax one would use to check out this tagged version of our project: 

% rm -rf ProjectX

% cvs co -r Prod1 ProjectX
cvs checkout: Updating ProjectX
U ProjectX/File1.java
U ProjectX/File2.java
U ProjectX/File3.java
U ProjectX/File4.pl
U ProjectX/File5.c
cvs checkout: Updating ProjectX/documents
U ProjectX/documents/TestDocument.doc
cvs checkout: Updating ProjectX/new_stuff
U ProjectX/new_stuff/a.txt
U ProjectX/new_stuff/b.txt
U ProjectX/new_stuff/c.txt
cvs checkout: Updating ProjectX/new_stuff2

% cd ProjectX


Editing Already Tagged Files

Although not very popular to do, it is sometimes necessary to "force" a CVS Tag onto a version of a file that may already be tagged for a lower revision. (Actually, in most cases, you would want to create a branch off of the Prod1 tag for a patched release.) But management is insistent on getting this fix into the Prod1 release of our project.

Consider our example so far. We felt pretty good about the stability of our project with the files I had checked out into my sandbox, so we tagged those revisions of the files with the Prod1 tag. But wait, one of our developers approached us a few minutes before we were ready to burn the CD and send the project out the customers. This developer found an error in one of the files - File3.java. In our example above, we applied the Prod1 to revision 1.2 of this file. 

% cvs status -v File3.java
===================================================================
File: File3.java        Status: Up-to-date

   Working revision:    1.2     Mon Mar 15 22:17:12 2004
   Repository revision: 1.2     c:/var/lib/cvsrepos/ProjectX/File3.java,v
   Expansion option:    kv
   Commit Identifier:   112040562b5d0000
   Sticky Tag:          Prod1 (revision: 1.2)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.2)
        release-1                       (revision: 1.2)
        start                           (revision: 1.1.1.1)
        INITIAL                         (branch: 1.1.1)
The developer wants to make changes to this file to correct the error and then apply the Prod1 tag to this new revision of the file. The way in which I would accomplish this is to have the developer make the necessary changes to the file and then perform a force tag update to the file. Let's see an example. First let's assume that we already have the Prod1 version of our project checked out into our sandbox.

We will want to first, remove the sticky tag on this file in our sandbox and update it to the current version (from HEAD). Notice that in the output of the cvs status -v command (above), that the file in our sandbox has a sticky tag: Prod1 (revision: 1.2). We want to remove this sticky tag so we can edit and commit a new revision to the CVS repository. To remove the sticky tag, use the -A option to the cvs update command: 

% cvs update -A File3.java
Now let's see if that removed the sticky tag from the file in my sandbox: 
% cvs status -v File3.java
===================================================================
File: File3.java        Status: Up-to-date

   Working revision:    1.2     Mon Mar 15 22:17:12 2004
   Repository revision: 1.2     c:/var/lib/cvsrepos/ProjectX/File3.java,v
   Expansion option:    kv
   Commit Identifier:   112040562b5d0000
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.2)
        release-1                       (revision: 1.2)
        start                           (revision: 1.1.1.1)
        INITIAL                         (branch: 1.1.1)
Yep, that worked! We can know go ahead and make the fixes to File3.java. For the purpose of this example, I am simply going to add a System.out.println("Bla blah blah"); statement to the file.

After making all required modifications to File3.java, we should commit this changes to the CVS repository: 

% cvs commit -m "Last minute modifications" File3.java
Checking in File3.java;
c:/var/lib/cvsrepos/ProjectX/File3.java,v  <--  File3.java
new revision: 1.3; previous revision: 1.2
done
After checking in the file, we want to tag the latest revision of File3.java in CVS. You can also think about this as "moving" the Prod1 tag from revision 1.2 to 1.3 for the file. Here is how we perform a "force tag" of the file: 
% cvs tag -F Prod1 File3.java
T File3.java
We have now tagged the latest revision of File3.java with the Prod1 tag. To complete this example, let's checkout the tagged version of this file into our sandbox and check it's status: 
% cvs update -r Prod1 File3.java
% cvs status -v File3.java
===================================================================
File: File3.java        Status: Up-to-date

   Working revision:    1.3     Wed Jun 30 20:22:49 2004
   Repository revision: 1.3     c:/var/lib/cvsrepos/ProjectX/File3.java,v
   Expansion option:    kv
   Commit Identifier:   61440e321180000
   Sticky Tag:          Prod1 (revision: 1.3)
   Sticky Date:         (none)
   Sticky Options:      (none)
   Merge From:          (none)

   Existing Tags:
        Prod1                           (revision: 1.3)
        release-1                       (revision: 1.2)
        start                           (revision: 1.1.1.1)
        INITIAL                         (branch: 1.1.1)


Last modified on: Tuesday, 26-Jul-2005 18:22:51 EDT
Page Count: 192790