10.4. Basic CVS Commands

After configuring your system to work with CVS, checkout the modules you will be working on.

[Tip]Tip

To see if you need a correctly-set $CVSROOT variable, or the -m repository command line switch, see if you have a CVS/ subdirectory in your working directory.

If you have a CVS/ directory, CVS ignores any $CVSROOT or -m command line switch.

10.4.1. Checking Out Modules

You only need to checkout a module once. After a local copy of the module is on your system, it is on your system.

To checkout a module, use the following command:

$ cvs co  <module-name>

For example, to checkout the example-tutorial module, change to your work directory, and execute the following command:

$ cvs co example-tutorial

A directory called example-tutorial/ is created in the current directory.

If a branch name is not specified when checking out a module, it is referred to as the HEAD of the CVS module.

10.4.1.1. Checking Out Branches of Modules

Think of a CVS branch as a version of the files for a particular version of a manual or package.

To checkout a branch of a module, use the following command:

$ cvs co -d  <directory> -r  <branchname> <module-name>

A directory named <directory> is created, and the files for the <branchname> branch of the <module-name> module are copied in the directory.

For example, to checkout a branch named BRANCH-VERSION-1.2 from the mymodule module, use the command:

$ cvs co -d mymodule-1.2 -r BRANCH-VERSION-1.2 mymodule

The BRANCH-VERSION-1.2 branch of the module is checked out in the mymodule-1.2 directory on your system.

To determine which branches and tags exist for a file, use the command:

$ cvs status -v <filename>

For example, the status of the file foo.sgml is as follows:


===================================================================
File: foo.sgml    Status: Up-to-date

   Working revision:    1.47
   Repository revision: 1.47    /cvs/docs/custom-guide/rhl-cg-en.sgml,v
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)

   Existing Tags:
        BRANCH-VERSION-1.2              (branch: 1.25.2)

Only tags marked as branches in the second column under the Existing Tags section can be checked out as a branch.

10.4.2. Updating Files

To retrieve the latest versions of the files in a module, change to the directory that contains the files for the module and execute the command:

cvs update

The latest versions of all the files in the module are downloaded into your local copy. If you notice a file conflict, refer to Section 10.4.8, “Resolving Conflicts”.

10.4.3. Committing Files

After modifying files in your local version of a module, commit them to save the changes on the CVS server:

$ cvs commit -m "some log message" filename
[Note]Note

If you would prefer to write your log message with your favorite text editor, as defined by the $VISUAL or the $EDITOR environment variable, just omit the -m "some log message". The buffer will already contain comments describing the change; you do not need to delete them as you enter your own text.

The log message should be as descriptive as possible so that you and anyone else working on the module understands what changed. Using a log message such as updated some files does not accurately describe what has changed and will not help you in the future. If you are correcting a bug, use the Bugzilla reference.

The <filename> can be one filename, a series of filenames separated by spaces, or a group of filenames specified using wildcards such as *.png or foo-*.sgml.

If no filename or group of filenames is specified in the commit command, all outstanding changes of any kind are committed to the server. The command is recursive and will include changes in any subdirectories of the module. Use caution when issuing the commit command without any filenames because you might not remember exactly what files changed.

If you notice a file conflict, refer to Section 10.4.8, “Resolving Conflicts”.

10.4.4. Adding Files

To add a file to a module, create the file in your local copy then execute the following command:

$ cvs add  file-to-add

After adding the file, you must commit the add to copy it to the server:

$ cvs commit -m "some log message" file-to-add

10.4.5. Managing Binary Files

The most commonly-archived files are simple text files but sometimes binary files are also archived. The cvs program recognizes most common filename extentions such as .png or .jpg, so cvs usually "does the right thing".

When a copy of a file is checked out of the repository, cvs scans it for special keywords, such as "$id:$" and replaces the string with a generated value, such as the file version number.

This keyword substitution usually corrupts binary files, so it must be turned off if cvs does not recognize your file as binary. To mark your file as being binary, and thus needing the keyword expansion turned off, use the command:

$ cvs admin -kk filename

Note that the file must already be checked in to the CVS repository before the admin command can be used. This is OK, since the keyword expansion is done as the file is checked out and copied to the local directory, not when the file is committed to the repository.

[Tip]Recovering a binary file

If you check a binary file into the repository and then find it corrupted when it is checked out, do not panic. Simply use the admin command as described above, delete your local file copy, and check it out again.

10.4.6. Removing Files

If a file is no longer needed in the module, use the remove command to remove it from your local copy and then commit the removal to the server. Even though the file is removed from current version of the module, an archived copy is still kept on the server and can be retrieved at any time with the add command.

$ cvs rm -f  file-to-remove

After removing the file, you must commit the removal:

$ cvs commit -m"some log message" file-to-remove

You can not use wildcards in the commit command to identify removed files. They must be specified with a exact filename.

If you need to rename a file, it is best to rename the file on the CVS server so that the history of the file is preserved. If you need to rename a file, send an email to cvsdocs-administrator@fedora.redhat.com asking to have the file renamed.

10.4.7. Status of Files

Sometimes it is necessary to view the status of a file in a CVS module. To view the status of a file, use the command:

$ cvs status  filename

The status report of a repository file is as follows:

Up-to-date

Your revision of the file is identical to the latest revision on the CVS server.

Locally Modified

You have updated to the latest revision from the server, but then you modified the file on your system.

Locally Added

You added the file with the cvs add command but have not yet committed the addition of the file.

Locally Removed

You removed the file with the cvs remove command but have not yet committed the removal.

Needs Checkout

A newer version of the file is on the server and needs to be retrieved. Even though the status includes the word checkout, it really means that you need to update your files with the cvs update command.

Needs Patch

The revision in your local checkout needs a patch to be the latest revision from the server. Issue the cvs update command to resolve.

Needs Merge

A newer revision exists on the server and your local version contains modification not yet committed. This status usually occurs if you don't have the latest revision of the file and edit it anyway.

File had conflicts on merge

Similar to Needs Merge, except when you tried to issue the cvs update command, the differences could not be resolved automatically. Refer to Section 10.4.8, “Resolving Conflicts” for more information on resolving conflicts.

Unknown

The CVS server does not know anything about this file. It has neither been added nor removed locally and has never been committed to the server. This status usually occurs for files you should not commit to CVS such as generated-index.sgml or for files that you want to add to the repository but have not yet issued the cvs add command.

10.4.8. Resolving Conflicts

If you modify a file and the same region is modified by someone else and committed first, you will probably see a message similar to the following when committing the file or updating your local copy of the module:


RCS file: /cvs/docs/module-name/filename.sgml,v
retrieving revision 1.12
retrieving revision 1.13
Merging differences between 1.12 and 1.13 into filename.sgml
rcsmerge: warning: conflicts during merge
cvs server: conflicts found in filename.sgml
C filename.sgml

To resolve the conflict, open the file, search for <<<<<<< and determine which version of the content is correct. For example:


<para>
Some sentence.
<<<<<<< filename.sgml
A sentence that was changed in the working copy.
=======
A same sentence that was changed differently and committed.
>>>>>>> 1.13
</para>

The content between the <<<<<<<, and the ======= is the content from your working copy. The content between the ======= and the >>>>>>> is the content from the server.

Resolve the conflict by editing your copy, and commit the file.

10.4.9. Summary

All commands assume you are in the proper directory for the CVS module.

CommandDescription
cvs checkout <module-name> or cvs co <module-name> Creates a directory called <module-name> with the contents of the module in the directory
cvs co -d <directory> -r <branchname><module-name> Creates the <directory> directory with the contents of the <branchname> branch of the <module-name> module
cvs update or cvs up Update your files with the latest files from the CVS server
cvs add <filename> Add a new file "filename" to the CVS server
cvs commit -m "My message" <filename> Update file <filename> with the latest copy from your computer
cvs log <filename> View the commit messages for the file <filename>
cvs status <filename> View status of the file, such as Locally Modified
cvs status -v <filename> View existing tags and branches for file
cvs diff <filename> Show diff of the working copy of the file and the latest version of the file for the branch
cvs diff -r1.1 -r1.2 <filename> Show diff of version 1.1 and 1.2 for file

Table 10.1. Basic CVS Commands

For more information, read the CVS manual available on your system at /usr/share/doc/cvs-<version-number>/cvs.ps (the CVS version might vary) and visit the CVS webpage available at http://www.cvshome.org/.

[Tip]Tip

Since CVS is using ssh to connect to the CVS server, you will be prompted your password before performing your CVS request. If you want to configure your machine so that you do not have to enter a password, refer to the Red Hat Linux 9 Customization Guide for details about using ssh-agent.