CMCVS is a Contextual Menu Module which allows you to use WinCVS.org's
public domain MacCVS
CVS client for source control from the Finder desktop.
CVS is a widely used POSIX-based source control system and CVS clients are
available on many platforms, including the Macintosh, making it a reasonable
choice for multiple platform development. CMCVS allows Macintosh developers
to use CVS from the Finder without arcane command line arguments or scripts.
CVS is not a simple system. We have attempted to make the interface in CMCVS fairly easy to use and we have automated a couple of gotchas (directory creation for example) but we strongly recommend reading the CVS documentation before getting in too deep.
If you are new to version control and determined to press on, you may
wish to start by reading the Version Control Basics
section. Otherwise, keep reading.
Return to the Contents.
CMCVS provides access to the the standard functions of most source-code control systems:
CMCVS also provides integration with Finder's labeling sytem via the VCSComments Pref panel.
Return to the Contents.
CMCVS requires a version of the MacOS that supports Contextual Menus, Navigation
Services and the Appearance Manager .
CMCVS also requires that you install a version of MacCVS on your machine.
MacCVS is a public domain implementation of a CVS client that is based on
the GNU implementation of CVS. We use the WinCVS.org
version 3.1 of MacCVS which can be downloaded
from the web. This version supports resource forks, an improved AppleEvent
suite and project files.
The current Desktop VCS architecture does not support creation of databases,
therefore you must either use existing CVS repositories or know how to create
new CVS repositories on the server. Moreover, CMCVS does not have a cvs
checkout facility, so you must use the MacCVS application to create
a workspace from an existing repository.
For those who wish to "roll their own" MacCVS from the public
domain source, CMCVS requires a local copy of an application with the creator
code specified in the CMCVS Options preferences panel that implements the
DoScript AppleEvent {'misc', 'dosc'} with the following parameters:
Do Command: Execute a CVS command
Do Command list -- Command line arguments, one per list item
[Mode AE/File] -- Mode (AE, File).
[Environment list] -- Environment variables.
[Filename string] -- Output file path.
[Pathway string] -- Starting pathway.
[NoLineBuffer boolean] -- if true, send each result line as separate AE.
Note that this is slightly different from the original event defined by
Mike Ladwig in that the arguments are no longer parsed from the list strings,
but copied directly. The keyword definitions are:
The environment variables are specified as pairs of adjacent entries in a list, namely <name> <value> <name> <value>... .
CMCVS also assumes that
Return to the Contents.
Before using CMCVS with a project, you must first have a CVS repository
that is available to you via TCP. Documentation
on how to do this can be found in many places, but the best place to start
is probably the Cederqvist
manual.
Next, you need to have a project folder created by the cvs checkout
command. We strongly recommend that you do the initial checkout with the
version of MacCVS that you will use with the plugin. We have found that
different versions of MacCVS have slightly different file formats which
are mutually incompatible.
If you are using the recommended version of MacCVS, you can check in project
files by using the .mcp extension, so you may wish to rename your project
files. Also, if you have MacCVS configured to use Internet Config for extension
mapping, make sure that all the extensions in your project have the correct
mappings.
Return to the Contents.
To configure a project for use with CMCVS, make sure that you have Desktop
VCS application running with a new configuration document open and set for
configuring CMCVS (directions). Then do the
following:
LOGNAME and $USER environment
variables);
Next, you should configure the VCS Environment Prefs panel. This tells CMCVS which repository you are talking to.To do configure it, do the following:
"CVSROOT=...";
CVSROOT environment variable;
Now, you should configure the VCSComment Prefs panel. This tells CMCVS how to color files using the Finder's labels. To do this, do the following:
If you are an experienced CVS user, you may wish to configure the default options for each command. To do this, do the following:
CVS maintains the "Local Root" directory specified above. It
is good practice to consider this directory as owned by CVS.
Return to the Contents.
This section is intended as a quick introduction to version control for the novice. We will take as a model an abstract programming project that may have one or more developers working on it and go through the entire process from start to finish. Note that this is not intended to be a comprehensive discussion of version control, nor is it our intention to imply that the Contexutal Menu model or GNU CVS are the last word in version control. For a list of all version control systems available for the Macintosh, as well as pointers to other online resources about version control and configuration management, please see our Macintosh VCS Page on the net.
Before we begin, a word about Contextual Menus. CMCVS is a Contextual Menu that you can access by holding down the control key and clicking on a file or folder on your desktop. The menu has a submenu called Advanced to bring up Advanced option dialogs for most commands. Folder (or Recursive) commands apply to all the files under version control inside that folder (or some obvious subset of them). You can also select a list of files from the same folder.
Version control allows you to track different versions (or snapshots, if you will) of the files used to make a program (or anything for that matter, but we will stick to programming). While it is often used to keep track of the work of several developers, it can also be used quite beneficially by a single developer working alone. CMCVS itself has one developer, but uses version control to keep the older versions of its source files, resource files, project files and documentation organized and backed up. This manual itself is one of the files kept under version control.
The most important thing that version control does is to specify a database for storing all the versions of all the files in the project that is separate from the versions being worked on by a developer. This database, in addition to organizing all the revisions of all the files, also serves as a backup for the project. The first thing you do (as described in the previous configuration section) is specify a location for the database. If the database you specify does not exist, CMCVS will not allow you to connect. See the CVS documentation for information on how to set up a repository.
So that now you have a database, how do you add files to it? After you have added a new file to the project itself and are ready to preserve a version of it, you add a new file to the database with the Add command in the CMCVS menu. CVS will then schedule the file to be added to the database. You commit the new file to the database with the Checkin command. After committing the change, CMCVS locks the file so that you won't accidentally make changes to it.
Later on, you may need to make further changes to a file, say to add a feature or fix a bug. To unlock a file, you use the Checkout menu command. The file will then be unlocked and you can start working on it. This is the part of the process that annoys many new users of version control. Try to remember that what you gain from tracking your changes and being deliberate about them generally outweighs the slight inconvenience of the checkout process.
Now, the bug is fixed and you want to save your changes in the database. You do this with the Checkin menu command. You will be prompted for a comment describing what you did to the file. After checking in the file, the version in your workspace is locked again to prevent you from making accidental changes to it.
Occasionally, you will start to make changes and realize that you have been making them to the wrong file. If you check out a file in error, just use the Undo Checkout command to back out your changes and get a fresh copy from the database.
If you are working with a group, or if you have several machines where you work on your project, you may occasionally need to get individual files or even the entire source tree from the repository. You do this with the Get and Recursive Get commands. These will make sure that you have the latest versions of all your files. You can even get older versions of a file by using the Advanced Get dialog.
One of the strengths of version control is that it enables you to track down changes by asking the database questions. CVS (on which CMCVS is based) allows you to ask it what files and revisions (snapshots) have certain properties. You make these queries with the History and Status commands. Another useful type of query is to compare the contents of a file that you have in your workspace with a version in the database, which is done with the Difference command. Finally, there is global information for the entire database (when it was created, etc.) and this is available from the Variables command.
Over the course of a project, files are created and added, but they are sometimes renamed, removed or even exported to another project. The Rename command allows you to rename a file. While CMCVS implements this operation for you, CVS has no rename operation, so a new file is created and the original history is part of the old file, which is deleted. The Delete command doesn't actually delete the file, but it makes it so that it will not be used in the project any more (you can undelete it in MacCVS, but Desktop VCS does not currently have an interface for this operation).
Files are usually organized in a directory hierarchy, and CMCVS allows you to create a matching hierarchical database as you add directories. To do this, simply add a new file from the directory to the database. Be warned that the directory on the server may be created with odd access permissions that may have to be sorted out before other users can view these directories.
It's now time for the first beta to be released. When you do this, you may want to take a snapshot of the entire database. The Recursive Label VCS command allows you to create a symbolic name (or label) for this snapshot. This snapshot can be retrieved later with the Recursive Get command by using the Advanced version of the command and typing in the label name.
While all the operations described above are quite simple, requiring at most a comment string or a label, there are sometimes other options that you might want to specify, such as updating administrative information etc.. Choosing a command from the Advanced submenu will bring up a dialog box allowing you to specify such options. Some of the options are obvious; others (such as branching) are beyond the scope of this discussion. See the CVS documentation for more information.
CVS stands for "Concurrent Versions System" which means that several developers can be working on a file simultaneously. CVS merges changes together when you check a file in, and notifies you of any conflicts. This is usually not a problem, but it is quite different from most version control systems. Of course, this doesn't work very well for binary files, but for text it is extremely convenient.
Return to the Contents.
CMCVS is a Contextual Menu that you can access by holding down the control key and clicking on a file or folder on your desktop. (Some other applications may also support the contextual menu context, used by CMCVS and you will also see the CVS submenu appear when you control-click in them.) You can only use CMCVS to operate on a folder or a set of files that are all in the same folder.
Once the contextual menu has appeared, you can choose any of the following commands from the CVS submenu:
All cvs commands use the directory of the file being manipulated as the cwd, or the local root directory for Recursive commands.
CMCVS attempts to make life pleasant for Kerberos users. Before each
command, $CVSROOT is checked to see if the ":kserver:" string
is present. If it is and if there is no valid ticket in the cache, the login
dialog is put up. Users who use Kerberos without the :kserver: option must
login separately.
Return to the Contents.
The Get command retrieves the current version of the file. The recursive
version updates all files in the project folder to their current versions.
All files are locked by default.
Advanced dialogs are also available for both versions of the Get command. These dialogs allow you fairly complete access to all the various update options provided by CVS. These options are in two groups. The first group is used to make changes to the sticky tags associated with the file (or with the entire project). As part of the Get, you can change the default keyword expansion and update all the sticky tags associated with the file(s) begin gotten. The option you are most likely to use here is "Reset sticky tags" to update how a file is treated (e.g. a file has been marked as binary and you need to copy that setting to your local workspace.)
The second group is used to specify which versions of the file and/or directories are retrieved. The first two checkboxes allow you to specify how any new or deleted directories in the repository are dealt with; the Revision popup allows to specify which date or revision you wish to update to; the last text fields allow you to merge branches of the source tree into the workspace. The most common options you would use here are the directory update options and specifying a particular revision to retrieve.
The cvs update command is quite complex and we recommend that you read the cvs documentation before attempting to do anything sophisticated.
The actual CVS commands are:
cvs -rq update [-k<keyword>] [-A] [-P] [-d] [(-r <revision> | -D <date>) [-f]] [-j<tag1> [-j<tag2>]] <file>
for the file version and:
cvs -rq update [-k<keyword>] [-A] [-P] [-d] [(-r <revision> | -D <date>) [-f]] [-j<tag1> [-j<tag2>]]
for the recursive version. None of the options are specified by default
Return to the Commands.
The Checkout command makes a file available for writing. This consists
of notifying cvs that you are about to edit the file.
Note that "Checkout" is the CMCVS's term for retrieving a file with write permission. This is completely unrelated to the cvs checkout command.
The actual CVS command used is:
cvs -w edit <file>
Return to the Commands.
The Checkin command commits the current version of a file to the
repository and locks it. The recursive version commits all locally modified
files. You will be prompted for a comment that describes what you are did
to the file(s). After checkin, the file(s) will be locked (including the
project file).
Advanced dialogs are also available for both forms of the command. the dialogs allow you to specify the branch or revision to commit to, and to turn off module processing for the checkin.
The actual CVS commands are:
cvs -r commit [-r <revision>] [-n] -m <comment> <file>
for the file version and:
cvs -r commit [-r <revision>] [-n] -R -m <comment>
for the recursive version.
Return to the Commands.
The Undo checkout command cancels the checkout of the file. It does
this by canceling the edit notification from the Checkout,
deleting the file and getting a fresh copy.
The actual CVS commands used are:
cvs -r unedit <file> cvs -r update <file>
Return to the Commands.
The History command displays a change history of the file obtained
from CVS. If you select multiple files, each one will appear in its own
window with a ".history" suffix. The recursive version returns
the history information for all files in the module.
The advanced dialog for the History command allows you to prune down the revisions and text displayed. Consult the CVS documentation for more information.
The actual CVS command used is:
cvs log [-h | -t | -R] [-N] [-b] [-d <dates>] [-s <status>] [-r<revisions>] [-w<editors>] <file>
for the regular version and:
cvs log [-h | -t | -R] [-N] [-b] [-d <dates>] [-s <status>] [-r<revisions>] [-w<editors>]
for the recursive version. No options are specified by default;
Return to the Commands.
The Status command displays the current state of the file, including
the revision numbers and sticky tags. If you select multiple files, each
one will appear in its own window with a ".status" suffix. The
recursive version of the command displays status information for the entire
project.
Advanced dialogs are also available for both versions of this command. They allow you to list all tags associated with a file.
The actual CVS command used is:
cvs status [-v] <filename>
for the regular version and:
cvs status [-v]
for the recursive version.
Return to the Commands.
The Properties command displays the watchers or editors of the file.
If you select multiple files, each one will appear in its own window with
a ".watchers" or ".editors" suffix. The recursive version
of the command displays watchers or editors for the entire project.
The advanced version of this command is used to toggle between displaying the watchers and editors. Hold down the command key to display the editors.
The actual CVS commands used are:
cvs watchers <filename> cvs editors <filename>
for the regular versions and:
cvs watchers cvs editors
for the recursive versions.
Return to the Commands.
The Difference command allows you to compare a file to the repository
version. There are two flavors of the Difference command, the original CVS Difference which uses the cvs
diff command, and a Helper Difference,
which uses helper applications to display differences. The flavor in use
is controlled by a checkbox in the CMCVS Options panel, and the default
is to use Helper Difference.
The regular version compares the local file to the current revision in the repository and the advanced version of the command allows you to specify which revision of the file to compare with the local revision, with a choice of revision, date or the main branch. The recursive version will show the differences for every file that is checked out or unlocked, comparing each to the current revision in the repository or to a version that you specify.
Difference is accomplished by use of helper applications. The default helper for text files is a helper application that translates the event for Bare Bones Software's BBEdit and the default for resource (RSRC, rsrc) files is Mathemaesthetics' Resourcerer.
The actual CVS command used is:
cvs checkout [-r <rev> | -D <date>] <repository file path>
By default, the -r <rev> option is used, where <rev> is the base revision for the file. The file is checked out to the temp directory on the same volume as the original file and then moved to the top of the temp folder. The cvs checkout folders are then deleted as they are not needed.
The helper applications mapping is described by the CTM# resource. The Compare Apple Event used is as follows:
Class: Comp Event: Comp Parameters: Newer file: kNew (typeFSS) Older file: kOld (typeFSS) Show difference: kShD (typeBoolean)
You may need to write a mapping applet to translate the event to your helper application.
The regular version compares the workspace version to the revision it was derived from. If you select multiple files, each one will appear in its own window with a ".diff" suffix. The advanced version of the command allows you to specify which revisions of the file to compare, how to expand RCS keywords and various diff options. The recursive version will show the differences for every text file that has been modified. The advanced recursive version will show all differences between any sets of files in just about any manner you could want.
The actual CVS commands used are:
cvs diff [-k<keyword option>] [-r <tag1> | -D <date1> [-r <tag2> | -D <date2>]] [-c] <file>
for the regular version and:
cvs diff [-k<keyword option>] [-r <tag1> | -D <date1> [-r <tag2> | -D <date2>]] [-c]
for the recursive version. Only the -c option is specified by default.
Return to the Commands.
The Label command allows you to label the state of a module so that
you can refer to it later. The command will prompt you for a label to use
for the module. You can later use the Recursive Get
command to retrieve this set of source and work with it.
CVS actually has two label commands: one labels the revisions currently in your workspace; the other labels the revisions currently in the repository. The regular Label command works with the revisions in the workspace and the advanced Label command (available from the Advanced submenu) works with the revisions in the repository.
The actual CVS commands used are:
cvs tag [-F] [-b] [-c] [-d] <tag>
for the regular command and:
cvs rtag [-F] [-a] [-c] [-d] [-R <rev> | -D <date>] [-f] <tag> <local root name>
for the recursive version. Only the -F option is specified by default.
Return to the Commands.
The Comment command allows you to change the checkin comment for
a version of a file. You will be asked for a new comment.
The regular version changes the comment for the file version that you re currently working on. The advanced version of the command allows you to specify which revision of the file to change the comment for.
The actual CVS command used is:
cvs admin -m<rev>:<msg> <file>
and for the Regular version of the command, <rev> is taken from the :CVS:Entries file.
Return to the Commands.
The Rename command changes a file's name in the repository. It does
this in the recommended manner, namely by renaming the file locally, deleting
the old file and adding the new file. After the rename, the file is labeled
as checked out and can now be checked in.
The actual CVS/POSIX commands used are:
mv <old name> <new name> cvs remove <old name> cvs add <new name>
Return to the Commands.
The Add command adds a new file to the local repository. It does
not commit it. After the add command, the file is labeled as checked out
and can now be checked in. By default, non-text files are checked in as
binary files. By using the verion of the command in the Advanced submenu,
you can specify a file description and a keyword option for the file.
Before adding a file, the Add command checks to make sure that the directories below the local root that contain the file are in the repository. If not, it will prompt you (from the top down) to add the directory.
The actual CVS command used is:
cvs add [-k<keyword> [-m <description>] <file name>
The -kb option is specified by default for non-text files. When adding a directory, the CVS command used is:
cvs add <directory name>
with the cwd set to the directory's parent. The test to determine whether the directory exists is simply to check for the CVS directory.
Return to the Commands.
The Delete command schedules a file to be deleted from the repository.
It does not commit the deletion. Use the Recursive
Checkin command to commit the deletion.
After committing, the file is still in the repository attic, but CMCVS currently
has no interface for recovering it.
The actual CVS command used is:
cvs remove <file>
Return to the Commands.
The Connect command makes sure that MacCVS is available and fails
if it is not. In addition, if you are using a pserver connection
method and you are not logged in using the username/password specified,
CMCVS will attempt to log you in. If your password is not valid, the connect
will fail.
If the connection method is pserver then a cvs login is faked by adding the password to the .cvspass file and then attempting to issue a
cvs -nq update -l
command. If this fails, the .cvspass file is restored and the connection fails.
Return to the Commands.
The Disconnect command is currently a nop.
Return to the Commands.
The About command displays a dialog box with version information.
Return to the Commands.
The Variables command displays information about the project, including
the status of all the files.
The actual CVS command used is:
cvs status
Return to the Commands.
This software should do what is described in this document. If it doesn't,
you can simply stop using it. If you pay for it, and within a year find
that it doesn't do what is described here, then you can notify us and we
will refund your money and cancel your license.
Electric Fish, Inc. hereby disclaims all warranties relating to this software,
whether express or implied, including without limitation any implied warranties
of merchantability or fitness for a particular purpose. Electric Fish, Inc.
will not be liable for any special, incidental, consequential, indirect
or similar damages due to loss of data or any other reason, even if Electric
Fish, Inc. or its agent has been advised of the possibility of such damages.
In no event shall Electric Fish, Inc. be liable for any damages, regardless
of the form of the claim. The person using the software bears all risk as
to the quality and performance of the software.
This code contains calls to the MIT KClient library for authentication only.
Such use is not prohibited for export by US law. Because of this, we are
required by MIT to include the following notice from them regarding the
KClient code:
Copyright (C) 1989 by the Massachusetts Institute of Technology
Export of this software from the United States of America is assumed
to require a specific license from the United States Government.
It is the responsibility of any person or organization contemplating
export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
notice appear in all copies and that both that copyright notice and
this permission notice appear in supporting documentation, and that
the name of M.I.T. not be used in advertising or publicity pertaining
to distribution of the software without specific, written prior
permission. M.I.T. makes no representations about the suitability of
this software for any purpose. It is provided "as is" without express
or implied warranty.
Government End Users: If you are acquiring the Software and fonts on behalf of any unit or agency of the United States Government, the following provisions apply. The Government agrees:
Return to the Contents.