How Can I Use CVS?

CVS is your friend. CVS is a great tool for maintaining source code. Using CVS, you can keep track of changes you've made and revert back to a previous version of the code, if needed.

CVSWeb is a good friend of CVS.

Getting Started

• Create .cvsrc in your home directory that contains:

  diff -c
  checkout -P
  update -dP

  diff -c makes the output a bit more readable
  checkout -P prunes empty directories from the checked-out source
  update -dP adds new directories when adding new source code with update

• Choose a directory (preferably one that is backed-up by the department) to be the root of your repository.

• Set the environment variable CVSROOT to the previously chosen directory

• Help on each CVS command is available by "cvs --help COMMAND"

• If you've made changes to original source already and want to start using CVS, grab the original source and import it into CVS. Checkout a version and copy your changes over the checked-out version. Commit.

Importing Source into the Repository

• Make sure that the files you are including are only source files. Importing binary files is special (see CVS FAQ for more info).

• Change directory to the source that you want to import.

• Choose a MODULE (directory under the root repository), VENDOR_TAG (to identify this code -- no spaces or dashes), and RELEASE_TAG (to identify the version of this code -- no spaces or dashes).

• % cvs import -m "MESSAGE" MODULE VENDOR_TAG RELEASE_TAG
  example: [~clark/ns/ns-2.1b7a]% cvs import -m "ns-2.1b7a" ns-2 NS NS_2_1B7A

Checking Out Code from the Repository

• Change directory to where you want the directory created.

• % cvs checkout [-r REV] [-d DIR] MODULE
  example: [~clark/src]% cvs checkout -r HEAD -d ns-2.1b7a ns-2
  This example would checkout the head of the ns-2 module (latest revisions) to the directory ~clark/src/ns-2.1b7a/. This is called the working directory. If "-d ns-2.1b7a" hadn't been included, the source would have been checked-out to ~clark/src/ns-2/.

  You can also checkout a version based on the date and time. Use the -D option followed by the date.
  Example: -D "2001-09-04 21:00" One oddity is that the date you specify is 4 hours earlier than the date of the commit that is checked out (at least for me).
  More Examples: -D "yesterday", -D "tomorrow", -D "12 days ago"

Committing Changes to the Repository

• Change directory to your working directory.

• % cvs commit
  example: [~clark/src/ns-2.1b7a]% cvs commit

• If others had been working on the same code, you might have to resolve conflicts. But, that's not really our model of working (yet), so we don't have to worry about it (yet).

Tagging a Group of Changes

• Commit the changes.

• % cvs tag TAG_NAME
  example: [~clark/src/ns-2.1b7a]% cvs tag RSPTIME_1_0

Merging in a New Vendor Release

First, read up on the process. Useful links:

• CVS Manual entry on tracking third-party sources (It's what I use for my ns-2 vendor updates.)
• CVS FAQ entry on importing large vendor releases (This one is a bit longer and more confusing, I think, than the CVS Manual entry.)
• nano CVS hints sections on imports and branches

The basic idea is to import the new vendor source into the vendor branch and do a three-way merge (diff of original source and new vendor source get merged into your changed code).

Here's what I did to merge in ns-2-snapshot-20010903 into my modified source (ns-packmime), which was based on ns-2.1b8:

• Commit latest version of modifications:

  [~/ns-allinone/ns-packmime]% cvs commit

• Tag latest version of modifications:

  [~/ns-allinone/ns-packmime]% cvs tag NS_2_1B8_PACKMIME

• Release latest version of modifications:

  [~/ns-allinone]% cvs release -d ns-packmime

• Unpack ns-2 snapshot:

  [~/ns-allinone]% tar xzvf ns-snapshot.tar.gz

• Import the snapshot into the vendor branch (module name = ns, vendor tag = NS, release tag = NS_2_SNAPSHOT_20010903):

  [~/ns-allinone/ns-2-snapshot]% cvs import -m "ns-2-snapshot-20010903" ns NS NS_2_SNAPSHOT_20010903 >& import.log

• Check out the latest revision of ns and merge the changes made since the vendor releases into the working copy:

  [~/ns-allinone]% cvs checkout -jNS_2_1B8 -jNS_2_SNAPSHOT_20010903 ns >& checkout.log

• Look for conflicts and manually fix:

  [~/ns-allinone/ns]% grep -r "<<<" *

• Build and test. Commit changes.

  [~/ns-allinone/ns]% cvs commit

Making Patches

Here's what I did before (the new scripts are WAY easier!):

[~clark/src/ns-2.1b8]% cvs commit
[~clark/src/ns-2.1b8]% cd ..
[~clark/src]% cvs patch -kk -R -r NS_2_1B8 -D now ns-2 > packmime.patch

• "-kk" ignores the Header: comments at the beginning of each file
• "-R" recurses through the entire tree
• "-r NS_2_1B8" looks at the import tagged NS_2_1B8
• "-D now" compares the import against the latest commit

One problem I had was that the patch didn't work in directories below ns-2.1b8. So, I cut apart packmime.patch and created a patch file for each directory that needed patching. (This is also why I created the script to make the patch.)

Misc Commands

• cvs diff - compares the working directory against the current repository

• cvs update FILES - merges changes to the repository into your working directory, is most useful to us as a method of retrieving previous versions of files
  example: [~clark/src/ns-2.1b7a]% cvs update -p -r 1.1 Makefile > Makefile.original
  • "-p" sends the file to STDOUT
  • "-r REV" indicates which version of the file to retrieve

• cvs add FILES - add the files to the repository on the next commit

Useful Links

• CVS Home
• CVS FAQ

CVS Web

• Copy the contents of ~clark/public_html/cvsweb (AFS-land) into your public_html/cvsweb/ directory
  (or grab the latest source)
• Read INSTALL
• Edit cvsweb.conf so that it points to your CVSROOT and displays a web page title you'd prefer
• Copy ~clark/public_html/cgi-bin/cvsweb.cgi (AFS-land) to your public_html/cgi-bin/ directory
• Give all users read/write/execute permissions to your CVSROOT and CVSROOT/history
• The location of your cvsweb interface should be
  http://wwwx.cs.unc.edu/~yourusername/cgi-bin/cvsweb.cgi (Note: You must use wwwx)