CVS Tips and Tricks

Overview
CVS allows multiple developers to work simultaneously on a project. CVS does this by keeping a master version of the source code in a central repository. Each developer checks out a copy of the to their computer using a CVS tool called a client. The local copy of the source is called a sandbox. Developers test and work on the source in their sandboxes until they reach a milepoint, such as implementing a new feature or fixing a bug. Developers then update their sandbox and commit their local changes back to the central repository.

Audacity users are always free to check out the current code anonymously (no password required) and so compile the latest Beta development version of Audacity for themselves. However, committing code changes to Audacity requires a Sourceforge account with appropriate write permissions granted by us. Connection to the Sourceforge CVS server is made securely by the client in the CVS tool, or through an external SSH client. To use the SSH client, you must generate an SSH. When you commit, the CVS server automagically merges changes together. Other developers periodically update their sandboxes to merge changes others have committed to the server.

Conflicts normally are prevented by developers communicating and working on different areas of the source code. It is also important that only working code is committed back into the repository.

Most of the time there is only a need for a single development trunk on a project. However, sometimes it is useful to develop a project in multiple directions at the same time (for example, to fix bugs in an older branch while also working on the next release). This is done by forking a project to create multiple branches which can be worked on separately.

Tips

 * Don't make the mistake of checking out the "audacity-src" module. This only contains Audacity code and lacks the third-party libraries that Audacity depends on. What you need is the "audacity" module, which is a virtual module wrapping all the elements needed to build.

Windows

 * TortoiseCVS
 * (needs an external SSH client such as to commit code to the repository)

Mac

 * (needs an external SSH client such as to commit code to the repository)

Linux/Unix
On Linux, Unix-like, BSD and other open source operating systems, it's more common to use the command-line CVS clients typically included in the default installation (or which are available directly from the operating system repository).

CVS commands
These are some of the most common and useful commands as they would be run from within the local sandbox using a command line CVS client. However if you are using a GUI client with an interface and buttons, the following explains what is going on underneath the hood!

update (with no changes)  Compares a local sandbox with the repository (to see if someone else has made changes). Does NOT modify your files, simply reports what has changed.

cvs -n -q update -AdP &#35; -n - don't change any files &#35; -q - be quiet &#35; -d - create and update subdirectories &#35; -A - reset sticky flags (just in case) &#35; -P - prune empty directories

update   Update a local sandbox with changes from the CVS repository one by  removing the -n flag.

cvs -q update -AdP

To bring only changes for specified files, list those files at the end of the command: cvs -q update FILE1 FILE2

commit   Commits your code changes back to the CVS repository. NOTE: before commiting changes, an update (described above) should be done and the project tested to make sure it runs with the new changes from other developers (with the goal of leaving the repository in an always working state).

cvs commit

To commit only specified files, list them at the end of the command: cvs commit FILE

remove   Removes a file from the project. NOTE: the file is still retrievable from CVS at this stage. To remove it permanently from CVS, run "commit" as above.

cvs remove -f FILE  (# -f removes the file in the sandbox)

add   Adds a file or folder to a project. Run "commit" (as above) after adding the file or folder.

cvs add FILE (FOLDER)

rename    Renames a file in a project. Unfortunately this cannot be done directly at the command line. A file must be removed and then added with the new name. Note that whichever way this is done, a break occurs in the change history of the file, you have to know the name of the old file in order to locate changes to it before it was renamed.

cvs remove -f FILE   (# -f removes the file in the sandbox) cvs add FILE

status   View the difference in revision number in the local sandbox compared with the repository. This is useful in combination with "diff" (see below).

cvs status FILE

To get the list of tags associated with a file (useful for checking out an older version of the source), preface the file list with the -v flag.

log   Gets a log of changes to a directory or file.

cvs log

Add specified files or directories to the end of the command if required.

diff     Gets the differences (in patch file format) between the sandbox and repository versions of a file, or between two repository versions. The log command (above) can be used to get the revision numbers when comparing two version of a file in the repository.

To see changes made to sandbox against what was checked out from the repository: cvs diff FILE

To see the difference between two versions of a file in the repository: cvs diff -r VERSION_NUMBER -rVERSION_NUMBER FILE

To see changes in unified diff format (which includes context information as well as the changed lines) add -u to the options. The output of this command can be captured to for a patch suitable for submitting for inclusion in Audacity.

tag   "Tags" or marks a snapshot of a project when making a new release. This allows older releases of a project to be checked out or even branched. NOTE: tags cannot have periods (.) so underscores (_) are used instead. The command should be run from the topmost directory of the sandbox.

cvs tag logscan-0_2

export   Extracts a project and creates a distribution tarball. Note that this is not how Audacity builds release tarballs, because we make more complex changes. See Building Release Tarballs for more information.

CVS return values
This is what the letters returned by the CVS client after an operation mean: