Difference between revisions of "CVS Tips and Tricks"

From Audacity Wiki
Jump to: navigation, search
(CVS commands: add a few comments, note that we don't use export.)
(SVN notice)
Line 5: Line 5:
* {{external|[http://en.wikipedia.org/wiki/Subversion_(software) SVN]}} - an alternative versioning system}}
* {{external|[http://en.wikipedia.org/wiki/Subversion_(software) SVN]}} - an alternative versioning system}}
== Overview ==  
== Overview ==  

Revision as of 20:49, 29 January 2010

CVS (Concurrent Versions System) is a tool used by many software developers to manage changes within their source code tree. CVS stores not only the current version of a piece of code, but a record of all changes to it (and who made them). CVS is common in projects with multiple developers, ensuring changes made by one developer are not accidentally removed when another developer posts their own changes to the tree.
Please use this page to add links to useful documents, and general tips and tricks on working with Audacity CVS. Help for users checking out anonymously is especially welcome.
Related article(s):

WIP.png Audacity is of course now hosted on GitHub, not SVN or CVS and this page needs revision to reflect that.


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 Audacity source code  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 unstable 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 SSH  client in the CVS tool, or through an external SSH client. To use the SSH client, you must generate an SSH public/private key pair . 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 stable 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.


  • 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.

CVS interface clients




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
# -n - don't change any files
# -q - be quiet
# -d - create and update subdirectories
# -A - reset sticky flags (just in case)
# -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:

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:

? File is in sandbox but not in repository.
A File is in sandbox but not in repository, however it has been added with a "cvs add" command. The change will take effect when "cvs commit" is run.
C There is a conflict between the sandbox version of this file and the version on the CVS server.
M Sandbox file was modified. If there were changes in the repository they were merged without conflicts.
P Sandbox file was patched to the CVS server without conflicts. This is like an update, but does not send the complete file, only a difference file called a "diff".
R File has been removed from the sandbox using "cvs remove". Changes will take effect in the repository when "cvs commit" is run.
U Sandbox file was updated with changes from the CVS server without conflicts.