Managing project source code

Getting started

If you are new to CVS, this help guide provides some basic quick reference information for administrative CVS tasks relevant to projects hosted this site. This guide by no means exhaustively documents CVS or the many broader project management issues imputed by versioning control. A wealth of published documentation for CVS exists, both online and in print. The following links lead to general CVS tool documentation elsewhere on this site, and these documents include many authoritative, external CVS resources.

CVS tool documentation

About CVS repository tasks

Much of the administrative work involved with setting up your project's source repository is handled "behind the scenes" when your project gains approval. If you are new to CVS, this means that you do not have to start from scratch to set up the CVS repository for your project.

The following tasks occur automatically:

For CVS experts, this automation means that the CVS administrative module is preconfigured for projects hosted on this site. That includes the following files:

All CVS repository tasks such as backing up, restoring, moving, or configuring remote repository access are also handled by site administrators. Should your project require editing CVS administrative files or other repository-level actions, you must contact a site administrator for support.

A few initial considerations for project owners

Starting from scratch

When your project is completely new or still in infancy, plan the overall directory structure at the front end of project evolution. Although the top level CVS module structure is predetermined, decide how you generally want to organize source files so that you can communicate this to existing and potential contributors. Considering source structure early on enables you to maintain consistency as the project grows, and makes it easier for new contributors to get up to speed.

Version control project management issues

As the project owner, you are likely to deal with developers who are grappling with the differences between RCS and CVS. Here are some key differences to clarify:

Managing CVS permissions

CVS read-access to your project's source code for site users is determined by whether your project is licensed open source or proprietary. Open source projects allow source file read access for any site user by default, whether or not they are project members. Proprietary project pages are not publicly viewable, so source code access is restricted to project members.

In both open source and proprietary projects, however, you as the Project Owner determine which project members will gain CVS write-access permissions through the roles you grant to them.

Observers, that is, users you have approved for project membership but who are not actually contributing source code to the project, have read-access but not write-access to your project's source repository . They can check out, view, compare revisions, and update source files, but they cannot contribute modified files or new files to the source repository.

All other project membership roles automatically confer CVS write-access to project members. This includes the ability to:

Read-write permissions associated with individual files are administered separately from CVS Note that these permissions cannot be altered for a file once it is checked into the project's CVS repository.

Using version control administration

The Version control administration feature provides project owners the ability to carry out operations against the project's CVS repository normally not supported by CVS. As the Project owner you can use the Version control administration feature to assist in project maintenance tasks.

To access the Version control administration feature click the Administer link under Version control in the left navigation menu of your project. From the Project source options page you can access any of the two features.

Using the permanent deletion feature

Use this to permanently remove a file and its history from the repository. Once a file is deleted using this feature the repository will have no knowledge of the file, as if the file had never been added to the repository.

One of the primary features of any version control application is the version history, even for files that are no longer needed in new versions. However, sometimes a file or directory is mistakenly added and must be completely removed, along with any history of its existence. For example, if a developer accidentally checks in a file that should never be checked in. Another example is if the source tree has been imported incorrectly and the developers would like a fresh start to do an import again.

Use this feature with extreme caution. After completing this process all previous tags will not contain the deleted file. Before permanently deleting a file you should send a message to the project's developers stating your intentions to delete the specific file and advising them to checkout a fresh version of the code after you are finished.

To permanently delete a file or folder:

  1. Click the Permanent deletion link from the Project source options page.
  2. Once on the Delete files from the repository page review the information provided on this page.
  3. Navigate to the pathname field and enter the pathname and file name of the file you would like to permanently delete from your project's repository.
  4. Once you have completed these steps click the Delete button.

NOTE: files with spaces in their names cannot be permanently removed using this feature. For instance, a file named "unit one" cannot be processed properly using this feature.

Using the permanent rename feature

Use this feature to permanently rename files and directories, as if they had always had those names. The version control component maintains file history and considers a renamed file to be the removal of one file and the creation of another. However, sometimes it is desirable to rename a file or directory along with any of its history.

For example, if an import is done with the wrong repository directory specified, renaming it could correct the problem immediately. Another reason to rename a file may be because it differs from a newly desired file only in capitalization. For instance, if you have a file named "image.jpg" and another named "Image.jpg" some version control clients will not distinguish these as distinct files. Using CVS rm' is not adequate to resolve capitalization conflicts because the old file name will be retrieved from the repository Attic when the new filename is added.

To permanently rename a file:

  1. Click the Permanent rename link from the Project source options page.
  2. Once on the Move/rename repository files page review the information provided on this page.
  3. Navigate to the Old pathname field and enter the pathname and file name of the file you would like to permanently rename.
  4. Enter the new file and pathname in the New pathname field
  5. Once you have completed these steps click the Rename button.

Using command line cvsadmin

Once a file has been committed to the repository it is a permanent member of that repository and the attributes of that file cannot be altered. However, as the Project administrator you can use the command line cvsadmin tool to make some adjustments to any committed file. Using the command line cvsadmin tool you can:

NOTE: while the cvsadmin feature has many available actions only those documented here are supported. Using any other action can result in corruption of the repository.

Fixing log messages

If a file with the wrong log message has been committed, you can change it afterwards with the "cvsadmin -m" command. First, you need to know the revision number of the relevant commit; if you do not have that number handy, you can run "CVS log" on the file to get it.

For example, assume that revision number "1.5" of file "foo.txt" has the wrong log message. Use the following command to alter the commit message:

cvsadmin -m1.5:"Here is the new log message." foo.txt

Using cvsadmin to control keyword substitution

By default, CVS will expand every keyword in a file, whenever that file is added or committed. However, in some circumstances keyword substitution is undesirable. For example, the string "$Author$" might appear in a binary file, where expanding it to "$Author: jrandom$" would corrupt the file. Or a keyword string might appear in a text file, but in a context where dynamic substitution would be inappropriate.

For non-binary files, you can turn keyword substitution off by passing the -k option when you add the file to the repository: e.g., "CVS add -ko". If, however, you need to substitution off at a different time you can use "CVS admin KO"

For binary files, the solutions are similar, except you pass "-kb" instead of "KO". The "b" treats the file as binary data and suppresses keywords expansion and any platform-specific line ending conversions. The "o" will maintain the keyword string in its original state, effectively doing nothing.

Additional useable actions are:

-kk:
Replace with just the keyword's name. For example, "$Author: jrandom $" becomes just "$Author$".
-kv:
Replace with just the value. Thus, either "$Author$" or "$Author: jrandom $" would become just "jrandom", and therefore would not be resubstituted in the future.

For more details about using keywords, see these links: