ServicesSoftwareAbout Us |
Go to the first, previous, next, last section, table of contents.
2 Basic UsageThis chapter will demonstrate basic usage of CVS, using a small example program to motivate the tutorial(1). Since learning something as complex as CVS requires a bit of experimentation, the example program serves as a "sandbox" where you can play and try out the various features of CVS, without affecting any of your existing source code in the process. 2.1 PreliminariesBefore you can begin the tutorial, you must first prepare the sandbox directory structure used for the tutorial: $ T=$HOME/sb # For csh use: setenv T $HOME/sb $ mkdir $T $ cd $T $ mkdir $T/d Notice that the T environment variable has been defined; this variable is not required by CVS. However, this variable will make it easier to refer to the tutorial sub-directories further on. Download the sample files used for the tutorial and place them in your tutorial distribution directory `$T/d'. Once you've done this, you'll be ready to set up CVS. 2.2 Setting up CVSOnce the preliminaries are out of the way, three tasks must be completed before you can start the tutorial:
2.2.1 Setting CVSROOTYou need to set the CVSROOT environment variable from a shell command line. If you're using a Bourne-compatible shell (e.g. bash, zsh, ksh), use the following command to set CVSROOT for the CVS examples: $ CVSROOT=$T/r $ export CVSROOT
If you're using a % setenv CVSROOT $T/r The CVSROOT variable is usually set in your shell's initialization file. However, to make the tutorial simpler to follow, you can set the value directly from the command line. 2.2.2 Initializing CVS repositoryOnce the CVSROOT variable has been set, the next step is to create and initialize the directory specified by CVSROOT. The directory specified by CVSROOT is where the "version database", or repository is kept. The following commands will prepare the CVS repository: $ mkdir $T/r $ cvs init Once this step is complete, you'll need to create a CVS work directory. 2.2.3 Creating initial CVS work directoryFinally, once the CVS repository has been set-up, you need to create a CVS work directory; this directory will be where you will check-out files to which you will be making modifications. Use the following command line to create and initialize your work directory: $ mkdir $T/w $ cd $T/w $ cvs checkout -l . cvs checkout: Updating . The CVS checkout command creates a `CVS' directory in the `w' directory. The `CVS' sub-directory is used to store various CVS administrative files related to your work directory and its sub-directories. In fact, it's the presence of these sub-directories (and their contents) that make a user directory a CVS "working" directory. Once you've created your CVS work directory, you're ready to try the CVS examples. 2.3 Initial check-inFor the duration of this guide, you'll be working with a small sample program, a `hello' program written in C, published by a fictional organization named Acme Corporation. The sample program's purpose is not to be a sophisticated programming example, but rather to embody various traits (e.g. the use of sub-directories) present in more complex software. The sample is purposely simple-minded to help you focus on CVS and its use as a software configuration management tool. The `hello' sample files should be located in the `$T/d' directory. Before you can add the `hello' source code into your CVS repository, you must first unpack the archive: $ tar xzvf $T/d/hello-1.0.tar.gz hello-1.0/ hello-1.0/src/ hello-1.0/src/hello.c hello-1.0/doc/ hello-1.0/doc/README hello-1.0/Makefile hello-1.0/Changelog Now that the `hello' sample has been unpacked, there are two ways to add the files to your CVS repository:
Since both methods work but have different behavior, it's worth looking at each one. 2.3.1 Adding source filesThe primary method for adding files to your CVS repository is using the add and commit commands. This method is preferred if you're adding files to an existing project repository. First, you'll need to add the source code directory to your repository: $ mv hello-1.0 hello # rename source sub-directory first $ cvs add hello Directory /home/alcocer/sb/r/hello added to the repository Note that the source code directory is renamed before adding it to your CVS repository. In general, it's bad practice to include version information in your directory or file names; after all, CVS will be tracking the version information for you. Next, add the files stored in the source code directory to your repository: $ cd hello $ cvs add Changelog Makefile cvs add: scheduling file `Changelog' for addition cvs add: scheduling file `Makefile' for addition cvs add: use 'cvs commit' to add these files permanently At this point, you could use the commit command to save these files in the CVS repository. However, it's easier to use a single commit later to add all the files in one step. You'll need to add the other files stored in the `doc' and `src' sub-directories now: $ cvs add doc Directory /home/alcocer/sb/r/hello/doc added to the repository $ cd doc $ cvs add README cvs add: scheduling file `README' for addition cvs add: use 'cvs commit' to add this file permanently $ cd .. $ cvs add src Directory /home/alcocer/sb/r/hello/src added to the repository $ cd src $ cvs add hello.c cvs add: scheduling file `hello.c' for addition cvs add: use 'cvs commit' to add this file permanently $ cd .. As you can see, the `hello', `hello/doc' and `hello/src' sub-directories have to be added to the CVS repository using add before the files that they contain can be added. The commit command is required to actually add the files to your repository: $ cvs commit -m "Initial revision." cvs commit: Examining . cvs commit: Examining doc cvs commit: Examining src RCS file: /home/alcocer/sb/r/hello/Changelog,v done Checking in Changelog; /home/alcocer/sb/r/hello/Changelog,v <-- Changelog initial revision: 1.1 done RCS file: /home/alcocer/sb/r/hello/Makefile,v done Checking in Makefile; /home/alcocer/sb/r/hello/Makefile,v <-- Makefile initial revision: 1.1 done RCS file: /home/alcocer/sb/r/hello/doc/README,v done Checking in doc/README; /home/alcocer/sb/r/hello/doc/README,v <-- README initial revision: 1.1 done RCS file: /home/alcocer/sb/r/hello/src/hello.c,v done Checking in src/hello.c; /home/alcocer/sb/r/hello/src/hello.c,v <-- hello.c initial revision: 1.1 done Note that commit's `-m' option was used; this option is used to specify a check-in comment on the command line. If the `-m' option is not used, the program specified by the EDITOR(2) environment variable is run to allow a check-in comment to be provided. 2.3.2 Importing source filesAn alternate method to add files to a CVS repository is using the CVS import command. The CVS import command is meant to add a directory tree of source code. As the name suggests, import is meant to add third-party source code to your local CVS repository. However, since import also allows you to add an entire directory of source code in one step, you can use it to add your own locally developed source code as well. NOTE: Before you can try this method in the tutorial, you'll need to first remove the existing repository you've created with add and commit. The following commands are not recommended in normal usage. They're only used here to allow adding the `hello' source code a second time. $ cd $T $ rm -fr $T/r/hello $ rm -fr $T/w/hello Once the existing source code repository and working sub-directory have been cleaned out, you can add the files again, this time using the import command. Your first step is to extract the sources: $ cd $T/w $ tar xzvf $T/d/hello-1.0.tar.gz hello-1.0/ hello-1.0/src/ hello-1.0/src/hello.c hello-1.0/doc/ hello-1.0/doc/README hello-1.0/Makefile hello-1.0/Changelog
Notice that you're unpacking the source code in your working directory;
however, CVS doesn't require this. In fact, the `hello' source
code could be unpacked in any directory where there is sufficient disk
space to do so. Also, note the directory structure created by unpacking
the source archive will correspond to the directory structure created by
the Now that the source code archive has been unpacked, it can be imported into your CVS repository: $ cd hello-1.0 $ cvs import -m "Imported sources" hello acme hello-1_0 N hello/Makefile N hello/Changelog cvs import: Importing /home/alcocer/sb/r/hello/src N hello/src/hello.c cvs import: Importing /home/alcocer/sb/r/hello/doc N hello/doc/README No conflicts created by this import The CVS import command requires three arguments in the following order: a repository sub-directory, a vendor tag, and a release tag. The last two arguments are meant specifically for third-party source code; they're not as important if adding locally developed source code(3). However, the vendor and release tags become important if you start using branching to track local and third-party changes to the source code.
The vendor tag is set to `acme' to indicate that the `hello'
sample is published by Acme Corp. Since you're importing the 1.0
version of `hello', the release tag is set to If you examine the repository directory `$T/r/hello', you'll see that it mirrors the directory structure present in the original source code directory tree. The CVS import command does not convert the source directory into a CVS working sub-directory, so the source directory is useless, as far as CVS is concerned. Since the source code has now been imported, you can safely delete this directory: $ cd .. $ rm -fr hello-1.0 The source code is now stored in the CVS repository. In order to make changes to the source, you must first check out a copy from CVS: $ cvs checkout hello U hello/Changelog U hello/Makefile cvs checkout: Updating hello/doc U hello/doc/README cvs checkout: Updating hello/src U hello/src/hello.c $ cd hello 2.4 Making simple changes
Now that the `hello' sample source has been put into your CVS
repository, it's time to see how to check-in simple changes. The first
change you will make will be to modify Once you've made the require changes, you're ready to check your change in. (Of course, normally you would compile the program first to verify your changes worked. However, this isn't a C tutorial, so assume that the changes are correct.) However, before you check-in your changes, it's nice sometimes to review the changes you made so you can write an accurate check-in comment. The CVS diff command allows you to see difference between your working copy and the revision you started with(4). If you run the CVS diff command now, you should see output similar to this:
$ cvs diff -ub
cvs diff: Diffing .
cvs diff: Diffing doc
cvs diff: Diffing src
Index: src/hello.c
===================================================================
RCS file: /home/alcocer/sb/r/hello/src/hello.c,v
retrieving revision 1.1.1.1
diff -u -b -r1.1.1.1 hello.c
--- src/hello.c 2002/08/05 17:29:19 1.1.1.1
+++ src/hello.c 2002/08/05 18:33:05
@@ -1,6 +1,7 @@
#include <stdio.h>
-void main(void)
+int main(int argc, char *argv[])
{
printf("Hello, world.\n");
+ return 0;
}
Looking at the output of diff, you'll see that CVS looked at the `doc' and `src' directories; most CVS commands recurse into sub-directories. Also, the `-u' (unified diff output) and `-b' (ignore white-space differences) options of the CVS diff command are used to tailor the output. You're now ready to check-in your changes to your CVS repository. Use the commit command to check your changes in: $ cvs commit -m "Made main() ANSI compliant." cvs commit: Examining . cvs commit: Examining doc cvs commit: Examining src Checking in src/hello.c; /home/alcocer/sb/r/hello/src/hello.c,v <-- hello.c new revision: 1.2; previous revision: 1.1 done Notice that the check-in comment refers to a file-specific change. Normally this would be bad, especially since the commit didn't specify any particular files (most CVS commands recurse into sub-directories by default, if no files are specified on the command line.) However, since the commit only applied to the specific file, it's fine in this instance. However, you should be careful when writing your own check-in comments. 2.5 Using symbolic revisions
Now that you've made and checked in your first change, it's time to see
how you can record the collection of file revisions that correspond to a
particular version of source code. CVS, uses dotted numeric revision
labels like
For instance, the current version of the `hello' sample is a
modified version of $ cvs tag hello-1_0_1 cvs tag: Tagging . T Changelog T Makefile cvs tag: Tagging doc T doc/README cvs tag: Tagging src T src/hello.c
In order to see the actual numeric revisions that correspond to the tag
$ cvs log -r hello-1_0_1 . cvs log: Logging . RCS file: /home/alcocer/sb/r/hello/Changelog,v Working file: Changelog head: 1.1 branch: 1.1.1 locks: strict access list: symbolic names: hello-1_0_1: 1.1.1.1 hello-1_0: 1.1.1.1 acme: 1.1.1 keyword substitution: kv total revisions: 2; selected revisions: 1 description: ---------------------------- revision 1.1.1.1 date: 2002/08/05 17:29:19; author: alcocer; state: Exp; lines: +0 -0 Imported sources ======================================================================== RCS file: /home/alcocer/sb/r/hello/Makefile,v Working file: Makefile head: 1.1 branch: 1.1.1 locks: strict access list: symbolic names: hello-1_0_1: 1.1.1.1 hello-1_0: 1.1.1.1 acme: 1.1.1 keyword substitution: kv total revisions: 2; selected revisions: 1 description: ---------------------------- revision 1.1.1.1 date: 2002/08/05 17:29:19; author: alcocer; state: Exp; lines: +0 -0 Imported sources ======================================================================== cvs log: Logging doc RCS file: /home/alcocer/sb/r/hello/doc/README,v Working file: doc/README head: 1.1 branch: 1.1.1 locks: strict access list: symbolic names: hello-1_0_1: 1.1.1.1 hello-1_0: 1.1.1.1 acme: 1.1.1 keyword substitution: kv total revisions: 2; selected revisions: 1 description: ---------------------------- revision 1.1.1.1 date: 2002/08/05 17:29:19; author: alcocer; state: Exp; lines: +0 -0 Imported sources ======================================================================== cvs log: Logging src RCS file: /home/alcocer/sb/r/hello/src/hello.c,v Working file: src/hello.c head: 1.2 branch: locks: strict access list: symbolic names: hello-1_0_1: 1.2 hello-1_0: 1.1.1.1 acme: 1.1.1 keyword substitution: kv total revisions: 3; selected revisions: 1 description: ---------------------------- revision 1.2 date: 2002/08/05 19:16:07; author: alcocer; state: Exp; lines: +2 -1 Made main() ANSI compliant. ========================================================================
Examining the output of the log command, you can see there is
a symbolic names section for each file. In particular, the symbolic
name 2.6 Managing your work directoryOne confusing aspect of CVS is how sub-directories are handled. CVS is designed to deal directly with either files or with modules, the sub-directories of the repository directory. If you need to access any sub-directories present in one of your modules, CVS usually requires you to specify the repository-relative path of the sub-directory. (There are exceptions to this rule; for example, the update command allows you to specify sub-directories while in a module directory, but only if the sub-directory is already present in your working directory.) Assume for the moment that you've been asked to update the sparse documentation for `hello', but you are short of disk space. You'd like to delete the `src' sub-directory from your working directory for a while, at least until you finish the documentation. CVS provides a way to remove a sub-directory from your working directory via the release command: $ cvs release -d src You have [0] altered files in this repository. Are you sure you want to release (and delete) directory `src': y The `-d' option to release tells CVS to delete the directory after it's been released. Before CVS actually releases the sub-directory, it checks to see if you have any uncommitted changes that need to be checked in. In this case, no files have been altered or added (if there were any, they'd be listed by release), so can safely answer yes and delete the sub-directory. Days go by, and you've completed the documentation. Now you'd like to continue working with the source, so you try getting it back: $ cd $T/w/hello $ cvs checkout src cvs checkout: cannot find module `src' - ignored CVS is telling you that it doesn't recognize `src' as a valid module, which is true, because `src' is in fact a sub-directory of module `hello', the only module you have in your CVS repository. What you need to do is specify to CVS is the repository-relative path of `src' instead: $ cvs checkout hello/src cvs checkout: Updating hello/src U hello/src/hello.c Unfortunately, CVS didn't create the `src' sub-directory, but instead created a `hello' sub-directory which contains `src'. In order to get CVS to create the sub-directory, you'll need to use the `-d' option to checkout: $ cvs checkout -d src hello/src cvs checkout: Updating src U src/hello.c The `-d' option tells CVS to put the contents of `hello/src' into the `src' sub-directory; if the sub-directory doesn't exist, CVS will create it. CVS can now access the source files correctly because it recognizes `hello/src' as a correct path relative to the repository directory. Now that you have the source files you need, you can get rid of the extraneous `hello' sub-directory: $ cvs release -d hello You have [0] altered files in this repository. Are you sure you want to release (and delete) directory `hello': y 2.7 Making concurrent changesIt's time to examine a more complicated change scenario: concurrent changes made to a source code project. This scenario will help demonstrate how CVS supports parallel development by multiple developers. NOTE: First, you will need to create a duplicate work directory for the `hello' sample; this additional work directory will simulate another user making concurrent changes: $ cd $T/w $ mkdir hello2 $ cvs checkout -d hello2 hello cvs checkout: Updating hello2 U hello2/Changelog U hello2/Makefile cvs checkout: Updating hello2/doc U hello2/doc/README cvs checkout: Updating hello2/src U hello2/src/hello.c Obviously, having more than one work directory for a repository can be confusing, and in general should not be used, but for the purposes of this tutorial, it's useful.
Now, assume that you've been asked to add a Once you've completed the changes to both files, move to the second work directory `$T/w/hello2' and check-in the changes: $ cd $T/w/hello2 $ cvs ci -m "Added test target" Makefile Checking in Makefile; /home/alcocer/sb/r/hello/Makefile,v <-- Makefile new revision: 1.2; previous revision: 1.1 done There are two things to note here: first, notice that instead of using commit, its alias ci is used instead, as in "check-in" (CVS commits can be thought of as check-ins.) Secondly, notice that you can specify files (in this case, a single file) to commit. This can be used to informally group changes, or to make a single check-in comment make sense for a group of files checked in together. This particular check-in simulates the other developer checking in their changes. Now that the other user has completed their check-in, it's time to try to check in your changes: $ cd $T/w/hello $ cvs ci -m "Added clean target" Makefile cvs commit: Up-to-date check failed for `Makefile' cvs [commit aborted]: correct above errors first!
While performing your check-in, CVS has noticed that the current
revision of `Makefile' is different than the revision you started
with. Therefore, CVS concludes that the repository has new changes not
incorporated into your working copy (in this case, the additional
In order to bring your working copy up-to-date, you'll need to use the CVS update command: $ cvs update cvs update: Updating . RCS file: /home/alcocer/sb/r/hello/Makefile,v retrieving revision 1.1.1.1 retrieving revision 1.2 Merging differences between 1.1.1.1 and 1.2 into Makefile M Makefile cvs update: Updating doc cvs update: Updating src
As the output of the update command indicates, the changes
added in revision Now that you've updated your working copy with respect to your CVS repository, you can now retry commiting your changes: $ cvs ci -m "Added test target" Makefile Checking in Makefile; /home/alcocer/sb/r/hello/Makefile,v <-- Makefile new revision: 1.3; previous revision: 1.2 done This example went smoothly because the two changed regions in `Makefile' did not overlap. Because of this, CVS handled the required merging automatically. If the changed regions had overlapped, CVS could still perform the required merging, albeit with a little help. 2.8 Managing change conflictsNow that you've seen how CVS handles merging of non-overlapping changes, you can try your hand at overlapping changes. You'll be working with `src/hello.c' again; in `$T/w/hello/src/hello.c' you'll be adding an optional name argument to `hello', while in `$T/w/hello2/src/hello.c' you'll simulate another developer adding an optional greeting argument. Refer the files `$T/d/hello-1.0.1-name-arg.patch' and `$T/d/hello-1.0.1- greeting-arg.patch' for the specific changes. Once you've made the required changes, move to each work directory and review the changes:
$ cd $T/w/hello2
$ cvs diff -ub
cvs diff: Diffing .
cvs diff: Diffing doc
cvs diff: Diffing src
Index: src/hello.c
===================================================================
RCS file: /home/alcocer/sb/r/hello/src/hello.c,v
retrieving revision 1.2
diff -u -b -r1.2 hello.c
--- src/hello.c 2002/08/05 19:16:07 1.2
+++ src/hello.c 2002/08/06 13:12:00
@@ -2,6 +2,11 @@
int main(int argc, char *argv[])
{
- printf("Hello, world.\n");
+ char *greeting = "Hello";
+
+ if (argc > 1)
+ greeting = argv[1];
+
+ printf("%s, world.\n", greeting);
return 0;
}
$ cd ../hello
$ cvs diff -ub
cvs diff: Diffing .
cvs diff: Diffing doc
cvs diff: Diffing src
Index: src/hello.c
===================================================================
RCS file: /home/alcocer/sb/r/hello/src/hello.c,v
retrieving revision 1.2
diff -u -b -r1.2 hello.c
--- src/hello.c 2002/08/05 19:16:07 1.2
+++ src/hello.c 2002/08/06 13:15:19
@@ -2,6 +2,11 @@
int main(int argc, char *argv[])
{
- printf("Hello, world.\n");
+ char *name = "world";
+
+ if (argc > 1)
+ name = argv[1];
+
+ printf("Hello, %s.\n", name);
return 0;
}
As you can see, both changes overlap; they both change To see how CVS handles this situation, move to the alternate work directory and check in the changes: $ cd ../hello2 $ cvs ci -m "Added optional greeting argument" src/hello.c Checking in src/hello.c; /home/alcocer/sb/r/hello/src/hello.c,v <-- hello.c new revision: 1.3; previous revision: 1.2 done Now, move back to your work directory and check in your changes: $ cd ../hello $ cvs ci -m "Added optional name argument" src/hello.c cvs commit: Up-to-date check failed for `src/hello.c' cvs [commit aborted]: correct above errors first! The commit doesn't work, since you've made concurrent changes. It's time to update your working copy: $ cvs update cvs update: Updating . ? hello cvs update: Updating doc cvs update: Updating src RCS file: /home/alcocer/sb/r/hello/src/hello.c,v retrieving revision 1.2 retrieving revision 1.3 Merging differences between 1.2 and 1.3 into hello.c rcsmerge: warning: conflicts during merge cvs update: conflicts found in src/hello.c C src/hello.c
Notice the last line of update's output: `src/hello.c' is
marked with a
$ cat src/hello.c
#include <stdio.h>
int main(int argc, char *argv[])
{
<<<<<<< hello.c
char *name = "world";
if (argc > 1)
name = argv[1];
printf("Hello, %s.\n", name);
=======
char *greeting = "Hello";
if (argc > 1)
greeting = argv[1];
printf("%s, world.\n", greeting);
>>>>>>> 1.3
return 0;
}
CVS modified your working copy(5) of `src/hello.c' to include the conflicting changes. Each area of conflict is surrounded by `<' and `>' characters, and the conflicting changes are separated by `=' characters. The changes above the separator are your uncommitted changes, and the changes below are the changes checked into your CVS repository. These markers are meant to aid you while you perform the necessary changes to complete the manual merge. In this case, you need to keep both features; some tinkering to each change is necessary. In other cases, you may want to delete one or both of the changes. Since CVS cannot determine the intent of the changes, it can only help by delimiting the conflicting areas, deferring the actual decision to you.
Now, resolve the conflict by making your argument
$ cvs diff -ub
cvs diff: Diffing .
cvs diff: Diffing doc
cvs diff: Diffing src
Index: src/hello.c
===================================================================
RCS file: /home/alcocer/sb/r/hello/src/hello.c,v
retrieving revision 1.3
diff -u -b -r1.3 hello.c
--- src/hello.c 2002/08/06 13:26:26 1.3
+++ src/hello.c 2002/08/06 14:12:54
@@ -2,11 +2,16 @@
int main(int argc, char *argv[])
{
+ char *name = "world";
char *greeting = "Hello";
if (argc > 1)
greeting = argv[1];
- printf("%s, world.\n", greeting);
+ if (argc > 2)
+ name = argv[2];
+
+ printf("%s, %s.\n", greeting, name);
+
return 0;
}
Now that you've resolved the conflict, you can check in your changes: $ cvs ci -m "Added optional name argument" src/hello.c Checking in src/hello.c; /home/alcocer/sb/r/hello/src/hello.c,v <-- hello.c new revision: 1.4; previous revision: 1.3 done Now that the merge is complete, it's a good idea to tag the version that you have now: $ cvs tag hello-1_0_2 cvs tag: Tagging . T Changelog T Makefile cvs tag: Tagging doc T doc/README cvs tag: Tagging src T src/hello.c What you've seen so far probably covers a majority of what CVS is used for in daily usage. However, there are other common CVS tasks that deserve to be covered. While these additional tasks don't occur on a daily basis, when they do occur they're often critical tasks that must be completed quickly and efficiently. Go to the first, previous, next, last section, table of contents. |