A Quick and Dirty Guide to CVS (ZZ)

A Quick and Dirty Guide to CVS

//z 2012-07-06 10:11:29 AM is2120@csdn.T319929945 [T13,L149,R5,V166]
Contents

•     Overview
      Setting up Your Environment
      General Syntax of CVS commands
      Checking Files Out
      Editing Files
      Refreshing Local Copies
      Seeing What's Changed
      Committing Changes
      Adding Files
      Merging Revisions
      Resolving Conflicts
      Backing out a Bad Commit
      Deleting Files
      Other Useful Commands
      Branching
• 
  

Overview

Like RCS, CVS is a version control system. Unlike RCS, it allowsmultiple developers to work on a file at the same time; theCin CVS stands for "concurrent".

This document is a simple introduction from a user's point of view.It assume that a repository already exists. That is to say, someonehas already runcvs init, to initialize the repository, andcvs import to add the first group of files.

As a general reference, the main CVS manual is available online athttp://ximbiot.com/cvs/manual/feature.

Setting up Your Environment

Before using CVS, you'll need to set up a environment variables.

setenv CVSROOT /path/to/cvsroot          # C-shell syntax
CVSROOT=/path/to/cvsroot; export CVSROOT # Bourne syntax

CVSROOT should be the directory path to the repository.Place these in your .cshrc, .profile, or where ever you normally putsuch things.

//z 2012-07-06 10:11:29 AM is2120@csdn.T319929945 [T13,L149,R5,V166]

Another useful variable is CVSEDITOR. When ever you commitfiles, cvs will invoke this program and allow you to provide commentsabout the change you are making. As a personal preference, I like"emacs -nw --no-init-file"

General Syntax of CVS commands

CVS commands take the following form

cvs cvs-options subcommand subcommand-options

subcommand is the thing you are asking cvs to do -- check files in, check files out, do diffs, etc. To see the syntax of a givencommand

cvs -H subcommand

cvs --help will tell you how to get a list of what the different subcommands are.

Checking Files Out

When working with CVS, there are 2 copies of files that you need to beconcerned with:

1. The repository, which is visible to everyone
2. Local copies, which are visible to you

Before doing anything else, you'll need to checkout a local copy ofthe repository files. Here's an example:

$ cvs checkout mymodule
cvs checkout: Updating mymodule
U mymodule/file1

$ ls
total 1
   1 mymodule/

So what just happened? "mymodule" is a module in therepository. Checking the module out placed a local copy in the currentdirectory. Changes can be made to files here, then put back (committed)to the repository.

Modules are really just directories underneath $CVSROOT. In otherwords:

$ ls $CVSROOT
total 2
   1 CVSROOT/     1 mymodule/

CVSROOT contains configuration and administrative files used by CVS.We won't worry about that now.

Editing Files

Editing files is easy - once you have local copies, just edit them.None of your changes will be visible to other users until after you'vecommitted them.

If you mess up a local copy of a file, starting over is easy. Deletethe file, and usecvs update to get a fresh copy from therepository.

Refreshing Local Copies

If you're working with a group of developers, remember that they'remaking changes too. Periodically, you'll want to update your workingcopies. This is done with thecvs update command.

$ cvs update -P -d
cvs update: Updating .
U file1

Above, we see that someone had modified file1, and the copy in thecurrent directory was out of date; cvs updated file1 to the currentversion. The flags to update are optional. -P "prunes"directories that are empty, and -d tells cvs to include any newdirectories that aren't in your local workspace (the default behavioris only to include directories that you have checked out). Once youhave a local copy,cvs checkout andcvs update -d aremore or less equivalent.

update can also take arguments, if you want to update specificdirectories, or specific files with a directory. If no arguments aregiven, cvs recursively updates the directory tree rooted at thecurrent directory.

Seeing What's Changed

To see if someone has changed a particular file, use cvsstatus.

$ cvs status file1
===================================================================
File: file1             Status: Up-to-date

   Working revision:    1.2     Thu Oct 10 14:49:15 2002
   Repository revision: 1.2     /home/srevilak/c/mymodule/file1,v
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)

"Up-to-date" means that the file is current.

To get a quick look at everything, the following command is handy:

$ cvs -n update

The -n option tells cvs "don't change the disk". Wherelocal files don't match the repository copies, you'll see the name ofthe file and a status code (M for locally modified,? forsomething that's not in the repository, and so fourth).

Committing Changes

Okay, you've done some work and you're happy with the results. Toincorporate your changes into the repository, usecvs commit.

$ cvs commit filename

CVS will invoke CVSEDITOR so that you can make comments. Once youquit the editor, the changes will be put back into the repository.

Commit comments should be a short description of what you did, enoughto allow other developers to look at the file's log and get a sense ofwhat's been done to it. The GNU folks have an entire articlededicated to the subject of documenting changes:http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs.

Adding Files and Directories

Files and directories are added with the cvs add command.To add a directory:

mkdir newdir
cvs add newdir

To add a file

# create the file, edit it
cvs add newfile
cvs commit newfile

To add a binary file

cvs add -kb newfile
cvs commit newfile

-kb tells cvs that the file is a binary file, and that it shouldn'ttry to expand tags (such as $Id$.) that appear in the file's body. CVSunderstands many of the same tags that RCS does. Seehttp://ximbiot.com/cvs/manual/feature/cvs_12.html#SEC100, or theco(1) manpage.

Merging Revisions

Normally, it's best to edit files in the directory that you're usingfor checkouts. This way, cvs will automatically take care of mergingin changes, just by runningcvs update. However, in somecases that might not always be possible.

Hypothetical Situation: you took a copy ofMyfile.java home, and did some work on it. In themeantime, your fellow developers have committed changes to the file.The dilemna - you'd like to incorporate what you've done, but yourcopy of the file is now out of date. Of course, you also don't wantto undo work that others have done. Here's a way to deal with thissituation.

1. Find out what revision your copy of the file is based on. This willbe the revision number in the$Id$ or$Revision$ tags. If you can't determine therevision, this approach won't work, and you'll need to do a manualmerge.
2. Run cvs update to refresh your repository copy.
3. Run cvs log MyFile.java (in the appropriate directory) toget the revision number of the copy that you just checked out of therepository.

For the sake of illustration, lets say that the copy ofMyFile.java that you were working on at home is revision1.6, and the current repository version is 1.10.

Copy the MyFile.java that you worked on at home to yourcheckout directory. We now have the following arrangement:

• Repository version is 1.10, which you've just checked out. As far ascvs is concerned, your local copy is up to date.
• The actual file in your checkout area is revision 1.6 + changes.
• You're missing the differences from 1.7 - 1.10. (Note: this is whyyou don't want to commit the file yet. Doing so wouldremoveanything done between 1.7 and 1.10).

To pick up the modifications made from 1.7 - 1.10, you need to merge:

cvs update -j 1.7 -j 1.10 MyFile.java

In cvs-speak, this means "take the changes from revision 1.7 throughrevision 1.10, and apply them to the local copy of the file."Assuming that there were no merge conflicts, examine the results:

cvs diff -w MyFile.java

Make sure it compiles, then commit.

If things didn't go well, you'll need to examine the results andresolve any conflicts that happened as aresult of the merge.

On a related note, update -j ... can also be used to back out a bad commit, simply by reversing therevision order.

Resolving Conflicts

Eventually, something like this will happen:

$ cvs commit foo.java
cvs commit: Up-to-date check failed for `foo.java'
cvs [commit aborted]: correct above errors first!

Here, you've made changes to the foo.java, but someone else hasalready committed a new version to the repository (eg - the repositoryversion has a higher number than your local copy). Before you cancommit the file, you'll need to update your working copy.

If you and the other developer were working on different areas of thefile, cvs is pretty intelligent about merging the changes together; itmight see that the last set of modifications are in lines 75-100, andyour changes are in lines 12-36. In this situation, the file can bepatched and your work is unaffected.

However, if the two of you changed the same area of the file it'spossible to have conflicts:

$ cvs update foo.java
RCS file: /home/srevilak/c/mymodule/foo.java,v
retrieving revision 1.1
retrieving revision 1.2
Merging differences between 1.1 and 1.2 into foo.java
rcsmerge: warning: conflicts during merge
cvs update: conflicts found in foo.java
C foo.java

Oh dear! What do we do now? The answer is "fix themerge". Two things have been done to help you with this.

1. A pre-merge copy of the file has been made.

   $ ls -a .#*
      1 .#foo.java.1.1
   

   However, being a dotfile, it's presence isn't immediately obvious
2. cvs has inserted a conflict marker in your working copy.

   <<<<<<< foo.java
     static final int MYCONST = 3;
   =======
     static final int MYCONST = 2;
   >>>>>>> 1.2
   

The conflict lies between the rows of greater than and less thansigns. The thing to do now is decide what version is right, removethe conflict markers, and commit the file.

Backing out a Bad Commit

Let's suppose that you've commited a file, but this ended up breakingsomething horribly. Here's how to undo your commit:

1. Get the version number from after the commit. You can use an$Id$ tag within the file, or cvs status. Let's say that thenew version is 1.5.
2. Get the version number from before the commit. Typically, this willbe one lower than the current version. Let's say that the old versionis 1.4.

Now do this:

cvs update -j 1.5 -j 1.4 filename
cvs commit filename

The above is an example of a merge. You've asked cvs to takethe difference between versions 1.5 and 1.4 and apply them to yourworking copy. The ordering of version numbers is significant - thinkof it as removing changes, or going backward in version history.

Deleting Files

To get rid of files, use cvs delete:

rm filename         # must remove working copy first
cvs delete filename
cvs commit

CVS uses a "lazy" system for file deletion; delete justchanges the way that the file is stored in the repository. It's stillpossible to undelete the file, or to check out revisions that existedbefore the file was deleted. However, the file will no longer appearwhen you do checkouts or updates.

Because of this, it's not possible to delete a directory entirely.However, one can use the -P flag with cvs checkout and cvs update toprevent empty directories from being retrieved.

Other Useful Commands

There are a variety of other useful cvs commands. Here are a fewexamples:

cvs diff filename	Shows differences between your local copy of filename andthe repository version thatfilename was based on.
cvs diff -r 1.2 filename	Shows differences between your local copy of filename andversion 1.2 offilename.
cvs diff -r 1.2 -r 1.3 filename	Shows differences between versions 1.2 and 1.3. (regardless ofwhat version your local copy is).
cvs log filename	Show the commit log for filename (like rlog does with rcs).
cvs annotate filename	Shows each line of filename, prefixed with the version numberwhere the line was added, and the name of the person who added it.Useful for seeing who made a particular set of changes.

Branching

Branching is a process that allows different versions of a file to bedeveloped in parallel. The cvs manual gives a visual representationhere:http://ximbiot.com/cvs/manual/feature/cvs_5.html#SEC60.

[srevilak - I'll hold off on this section until it's needed. Whycomplicate things prematurely ;]

---

$Id: cvs.html,v 1.10 2009/07/17 01:13:03 srevilak Exp $
contact //z 2012-07-06 10:11:29 AM is2120@csdn.T319929945 [T13,L149,R5,V166]