Difference between revisions of "CVS Tips and Tricks"

From Audacity Wiki
Jump to: navigation, search
(Aded link to Richard's CVS Etiquette.)
(Trim some verbiage in the intro, few tweaks clarifying the distinction between this and the CVS Etiquette page)
Line 1: Line 1:
{{Introrel|1=CVS (Concurrent Versions System) is a tool used by many software developers to manage changes within their source code tree. CVS provides the means to store not only the current version of a piece of source code, but a record of all changes (and who made them) that have occurred to that source code. Use of CVS is particularly common on projects with multiple developers, since CVS ensures changes made by one developer are not accidentally removed when another developer posts their changes to the source tree.|2=Please use this page to add links to useful documents, and tips and tricks you learnt when working with Audacity CVS.|3=[[CVS Etiquette]]
+
{{Introrel|1=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.|2=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.|3=[[CVS Etiquette]] - how Audacity developers commit to and maintain the CVS build system
 
*{{external|[http://ximbiot.com/cvs/wiki/CVS%20FAQ Searchable CVS FAQ]}}
 
*{{external|[http://ximbiot.com/cvs/wiki/CVS%20FAQ Searchable CVS FAQ]}}
 
*{{external|[http://ximbiot.com/cvs/manual/cvs-1.11.22/cvs.html Searchable CVS Manual]}} by Per Cederqvist et al
 
*{{external|[http://ximbiot.com/cvs/manual/cvs-1.11.22/cvs.html Searchable CVS Manual]}} by Per Cederqvist et al
* ''Don't forget the documentation for your own [[#CVS interface clients|CVS client]]}}
+
* ''Don't forget the documentation for your own [[#CVS interface clients|CVS client]]
 +
* {{external|[http://en.wikipedia.org/wiki/Subversion_(software) SVN]}} - an alternative versioning system}}
  
  
Line 9: Line 10:
 
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 {{external|[http://audacity.sourceforge.net/community/developers#cvs Audacity source code]}} to their computer using a CVS tool called a '''''[[#CVS interface clients|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.  
 
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 {{external|[http://audacity.sourceforge.net/community/developers#cvs Audacity source code]}} to their computer using a CVS tool called a '''''[[#CVS interface clients|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.  
  
Committing code to Audacity requires a Sourceforge account with appropriate write permissions granted by us. Connection to the Sourceforge CVS server is made securely by the {{external|[http://en.wikipedia.org/wiki/Secure_Shell '''SSH''']}} client in the CVS tool, or through an external SSH client. To use the SSH client, you must generate an SSH {{external|[http://alexandria.wiki.sourceforge.net/SSH+Key+Generation#top '''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.
+
Audacity users are always free to check out the current code and so [[Developer Guide#Platform Specific Guides|'''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 {{external|[http://en.wikipedia.org/wiki/Secure_Shell '''SSH''']}} client in the CVS tool, or through an external SSH client. To use the SSH client, you must generate an SSH {{external|[http://alexandria.wiki.sourceforge.net/SSH+Key+Generation#top '''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.  
 
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.  

Revision as of 20:21, 25 April 2008

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):


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


CVS interface clients

Windows

Mac

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

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


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. The extract command ignores CVS related files allowing for a clean distribution tarball to be created. This command should be run in a scratch directory outside of the sandbox. This requires the -d cvs option to be passed, in addition to the -d command option passed to the export command.

cvs -d:ext:[email protected]:/cvsroot/audacity export -r logscan-0_2 -d logscan-0.2 logscan
# -r release or tag to checkout
# -d directory to extract to
tar -zcf logscan-0.2.tar.gz logscan-0.2



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.