CMProjector is a Contextual Menu Module which provides access to the MPW
Projector system from the Finder desktop.
CMProjector provides an easy to use source-code control system, at minimal cost, using established technology from Apple. It is well suited for individuals and small organizations which want the benefits of source-control with a minimum of hassle and expense.
If you are new to version control, you may wish to start by reading the
Version Control Basics section. Otherwise, keep
reading.
Return to the Contents.
CMProjector provides the standard functions of most source-code control systems:
and several additional features:
Return to the Contents.
CMProjector requires a version of the MacOS that supports Contextual Menus,
Navigation Services and the Appearance Manager .
CMProjector also requires that you install a version of MPW SourceServer
on your machine. SourceServer, a standalone application that provides access
to most of the Projector commands found in the MPW shell, is included with
CodeWarrior. You can download
the latest version from Apple's ftp site. For system 8.5 we recommend at
least SourceServer version 3.5 from Apple.
Important: When running MacOS 9 or later, SourceServer
version 3.5 is required, and you should delete any older copies of SourceServer
. Older versions may corrupt your files and will crash when they quit.
The default application for doing text-based Differences is Bare
Bones Software's BBEdit.
The default application for doing resource-based Differences is version 2.2 of Mathemaesthetics' Resourcerer.
Return to the Contents.
Prior to using CMProjector with a project, you must first decide where
you wish to keep the Projector database. If your project already has one,
you only need to make sure that the volume is mounted. If you don't have
a Projector database, CMProjector can create on for you, but you must create
an empty folder in the desired location with the desired name (so
that the Desktop VCS application can be pointed at it). The first time you
connect, CMProjector will convert this folder to a Projector database. CMProjector
works with subdatabases, but it requires that the main database be a top-level
database.
The Desktop VCS version control model assumes that all the files subject
to version control are in a single directory hierarchy. CMProjector interprets
this as a directory hierarchy that matches the Projector database hierarchy,
so make sure that your files are in this form. This also means that while
CMProjector can easily handle a database with multiple subdatabases, it
does not let you switch to a different top-level database or use multiple
top-level databases.
Return to the Contents.
To configure a project for use with CMProjector, make sure that you have
Desktop VCS application running with a new configuration document open (directions). Then do the following:
At this point, you should configure the VCSComment Prefs panel. To do this, do the following:
If you are an experienced Projector user you may wish to configure the default options for each command. To do this, do the following:
CMProjector maintains the "Local Root" directory specified
above. It is good practice to consider this directory owned by CMProjector.
For example, CMProjector will delete obsoleted files from this directory
when performing a Recursive Get operation.
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 MPW Projector 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. CMProjector 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. CMProjector 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, CMProjector will create one for you when you start up version control for a project.
So that now you have a database, how do you add files to it? After you are ready to preserve a version of it, you add a new file to the database with the Add command in the CMProjector menu. A copy of the file is then added to the database and the version you have in your workspace is locked to prevent you from making accidental changes to it. When you add the file, you must specify a change comment describing what you did. This happens every time you submit a file to the database, making it easier to go back and find when you made certain changes.
Later on, you may need to make further changes to a file, say to add a feature or fix a bug. You need to tell the database that you want to make changes to the file and keep other developers from making changes to that file while you are working on it. You do this with the Checkout menu command. You will be asked for a comment describing what you intend to do with the file (which can be very useful if you forget before you check it in) and 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 usually 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 again be prompted for a comment describing what you did to the file. The checkout comment is the default in the dialog. 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.
If you are working with a group, or if you have several machine 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.
CMProjector provides a useful feature called "Header Comments" as part of the checkout/checkin process. If you enable this feature, CMProjector will place a running history of the checkin comments with dates and initials at the top of each source file. This can be very handy for tracking down changes quickly. You can also get this information from the database, but it is a separate command and requires the database. CMProjector can also change the Finder Label of files to match their checkout state, which can be a useful way of tracking what files you are modifying.
One of the strengths of version control is that it enables you to track down changes by asking the database questions. Projector (on which CMProjector is based) allows you to ask it what files and revisions (snapshots) have certain properties. You make these queries with the Properties, 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. 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 MPW, but Desktop VCS does not currently have an interface for this operation). The Purge command is used to remove the version control information from a file so that it can be added to another database.
Files are usually organized in a directory hierarchy, and CMProjector 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.
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 menu command allows you to create a symbolic name (or label) for this snapshot. This snapshot can be retrieved later by using the Get command from the Advanced submenu on a folder and choosing the label from the popup. Files can also be labeled one at a time with the Label command to allow you to refer to a group of related changes as a unit.
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 keeping a file checked out when checking it in and so on. Choosing a command from theAdvanced submenu will bring up a dialog box allowing you to specify such options for the command. Some of the options are obvious; others (such as branching) are beyond the scope of this discussion. See the MPW Command Reference for more information.
Return to the Contents.
CMProjector 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 CMProjector
and you will also see the Projector submenu appear when you control-click
in them.) You can only use CMProjector 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 Projector submenu:
Note that the command names are taken from the CodeWarrior IDE. If you are
a devoted Projector user, please refer to the command descriptions to determine
what each one does.
Note also that the default behavior for each command can be customized
in the "CMProjector Options" preferences panel. The options in
this panel correspond to the check boxes in the advanced dialogs and are
the options used in the regular versions of the commands.
If you are unfamiliar with the Projector commands and would like to learn
more, please refer to the Apple manuals "Building
and Managing Programs in MPW, 2nd edition", "MPW
Command Reference" and "SourceServer
Reference".
Return to the Contents.
The Get command retrieves file versions from the Projector database.
It has a folder version that allows you to update an entire folder and advanced
versions that allow you to customize the checkout. The Get command will
also check to see if the file is ModifyReadOnly and ask you if you wish
to discard the changes. If the file does not exist, CMProjector will still
attempt to get the file.
The regular Get command simply gets the latest version of a file from the
database. The regular Recursive Get command refreshes the entire project
folder with the latest versions of all files and deletes any obsolete files.
These are the most common operations that you would want to perform.
The advanced Get commands (available from the submenu) allow simple access
to the Projector CheckOut command in all its baroque glory. We have attempted
to provide options that we believe that most users will want access to.
The advanced version of the regular Get command allows you to specify several
options and to choose which version of the file you wish to CheckOut. The
advanced version of the Recursive Get command again allows you to select
among various options, but also to choose between getting the latest versions
of all the files or getting a particular NameRevision (which is called a
Label by CMProjector). You can define NameRevisions from CMProjector using
the Label command.
The actual Projector commands are:
CheckOut <options> -d <dir> -project <project> <file>
for the single file version and:
CheckOutDir -r -project <project> <dir> CheckOut <options> -r -project <project>
for the recursive version. The default options for the regular version of these commands are described below.
The advanced options available for the Get command are:
[-history] [-noTouch] [-verify]
-noTouch is specified by default. In addition, specific
versions of the file may be chosen from a list.
The advanced options available for the Recursive Get command are:
[-deleteObsolete] [-history] [-noTouch] [-verify] [-newer | <label>]
-deleteObsolete, -noTouch and -newer are specified by
default.
The commands:
OrphanFiles <file> CheckOut -y -d <dir> -project <project> <file>
are used for MRO files.
Return to the Commands.
The Checkout command retrieves the latest version of the file from
the Projector database and makes it available for writing. You will be prompted
for a comment that describes what you are doing. If you are using header
comments, this comment will be added to the header. The Checkout command
will also check to see if the file is ModifyReadOnly and ask you if you
wish to discard the changes. The advanced Checkout command allows you to
specify various Projector Checkout options such as the task name and file
verification.
There is also a Recursive version of the Checkout command. All this does is a tree walk allowing you to check out all the files you have locally. The Advanced version will put up the checkout dialog for each file. This Recursive variation should not be used casually as this tends to defeat the purpose of Version Control (not to mention being highly obnoxious in a shared environment!) It is mostly useful for when you have to change every file at once. If there is any file that you do not need to modify in the edit, you should strongly consider checking the files out individually.
Note that this is slightly different from the Projector CheckOut command which also allows you to retrieve a file read-only. In CMProjector this functionality is provided by the Get command.
The actual Projector command used is:
CheckOut -m <options> -cs <comment> -d <dir> -project <project> -u <user> <file>
The advanced options dialog (available from the Advanced submenu) brings up a dialog that allows you to specify the following options:
[-b] [-history] [-noTouch] [-verify] [-t <task>]
as well as the version you wish to check out. -noTouch
and the latest version are specified by default.
The commands:
OrphanFiles <file> CheckOut -y -d <dir> -project <project> <file>
are used for MRO files.
Return to the Commands.
The Make Writeable command allows you to modify a file without checking
it out of the database. This can be useful if the database is not available
or if you want to make temporarly local changes.
The actual Projector command used is:
ModifyReadOnly <file>
Return to the Commands.
The Checkin command returns the edited version of the file to the
Projector database and locks it. You will be prompted for a comment that
describes what you are did to the file. If you are using header comments,
this comment will be added to the header. If you specified a task name during
Checkout or later via the Advanced Comment command, that task will be used for the checkin.
The Advanced Checkin command allows you to specify several checkin options, including changing the task name and a new version name. If you specify a new version name it must be numerically greater than the current version.
The recursive versions of the checkin command walk the specified directory searching for files that are checked out or MRO. It then prompts you to check in each one. It is just as if you selected all the checked out files in the project window and chose Checkin.
The actual Projector command used is:
CheckIn <options> -cs <comment> -project <project> -u <user> <file> [-t <task>]
The advanced options dialog (available from the Advanced submenu) brings up a dialog that allows you to specify the following options:
[-b] [-m | -delete] [-touch] [-verify] [-t <task>]
None of these options are specified by default, except the task as described
above.
Return to the Commands.
The Undo Checkout command cancels the checkout of the file. It can
also be used with an MRO file by holding down the command key.
The recursive version prompts you to cancel the checkout of all checked out or MRO files. It is just as if you selected all the checked out or MRO files in the project window and chose Undo Checkout.
The actual Projector command used is:
CheckOut -cancel -y -d <dir> -project <project> <file>,<rev>
The commands:
OrphanFiles <file> CheckOut -y -d <dir> -project <project> <file>
are used for MRO files.
Return to the Commands.
The History command displays a change history of the file obtained
from the Projector database. It displays information for each revision in
the database, including the author, checkin date, task and comment fields.
If you select multiple files, the history for each file will be displayed
one at a time in a scrolling text field that you can save. The recursive
version returns the comment information for all file revisions in the project
that are checked out for modification (this is because returning all information
for all files will probably overflow the SourceServer return buffer). The
History command also supports advanced versions of both the regular and
recursive commands.
The Advanced version of the command allows you to filter the reporting of the versions of the selected files by giving a matching pattern for the author, comment, modification dates, task and name, or by specifying the latest trunk version. Leaving a field blank means that no filtering is done with it. You may also specify whether the history of each file appears in its own window or in a single window; that file information only be displayed; and that a short listing be given. The latter causes the comments to be stripped out, giving you only a list of version or the history.
The Advanced Recursive version of the command allows you to specify the versions of the selected files as in the Advanced version, as well as specifying which files are reported on. Files can be specified by author, comment and date, and by various version tests. The popup allows you to ask for all files or files that there are newer versions of in the database than the ones you have, including or excluding any new files you don't have copies of yet. You can also ask for only the files that someone has open for modification, which can be very useful for making sure you have everything checked in (finding "lurkers"). Finally, you can specify short listings as for the regular version of the command.
For the author, comments and task, you can specify a pattern that the field must contain, either a literal string, or a regular expression enclosed in forward slashes (/).
The date can be specified as follows:
A date used in a date expression can be specified as
mm/dd/yy [ hh:mm [:ss ] AM|PM ]
where mm, dd, and yy represent the month, day, and year; hh, mm, and ss represent the hour, minute, and second; and AM and PM indicate an A.M. or P.M. time.
For the name, you can specify either a label name or a version number. The name can be specified as follows:
The actual Projector command used is:
ProjectInfo <filename> -project <project> -comments <file name>
for the regular version and:
ProjectInfo <filename> -project <project> -comments -r
for the recursive version. The Advanced version adds the options:
[-a <author>] [-c <comment>] [-d <date>] [-n <name>] [-t <task>] [-latest] [-f] [-s]
and the Advanced Recursive version adds the options:
[-newer | -update] [-af <author>] [-cf <comment>] [-df <date>] [-m] [-s]
Return to the Commands.
The Status command displays the current state of the file, as recorded
in the 'ckid' resource and updates the displayed status in the Finder. If
you select multiple files, the status for each file will displayed one at
a time in a separate window that you can save.
The recursive version checks the status of every file in the specified directory and places the results in a single window. Only files with 'ckid' resources are reported, but the Finder status of every file is updated. This is very useful for synchronizing the status with the disk and also for forcing the Finder to update.
The Advanced version of the command allows you to specify that a single window is used.
The Advanced Recursive version doesn't actually put up a dialog, but reports only those files that are checked out or MRO.
No Projector commands are used.
Return to the Commands.
The Properties command displays the current state of the file, including
the author, creation and modification dates and whether the file can be
checked out. If you select multiple files, the status for each file will
displayed one at a time in a separate window with that you can save.
The Properties command is actually almost identical to the History command, except that Properties doesn't display the checkin comments for non-short listings.
The actual Projector commands used are the same as for the History command, except that the
-comment
option is not specified.
Return to the Commands.
The Difference command displays the differences between the version
of a text or resource file in your workspace and a version in the database.
The regular version compares the main trunk revision and the advanced version
of the command allows you to specify which version of the file to compare
with the disk version. The recursive version will show the differences for
every file that is checked out or MRO as compared to the main trunk revision.
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 Projector commands used are:
CheckOut -d <temporary dir> -project <file project> <file name>[,<version>]
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.
Return to the Commands.
The Comment command allows you to change the Checkout comment for
a file. The comment is changed in the 'ckid' resource and in the header
comment. The advanced version of the command changes the Checkout Task Name
for a file in the 'ckid' instead of the comment.
The recursive versions of the command specify the comment/task name for all checked out or MRO files in the specified folder.
No Projector commands are used.
Return to the Commands.
The Label command allows you to label a group of files so that you
can refer to them later as a group. The regular versions of the command
simply list all the labels associated with the file or project in question.
The advanced versions of the command will prompt you for a label to use
for all selected files. You may later use a label you have defined in the
advanced recursive Get command. Note: This is
not the same as Finder coloring (which is also called Labeling).
In addition to the name of the Label, you may also specify whether you wish to replace an existing label with the same name, have the label always refer to the latest version of a file or specify that the local revision that you have in your workspace be the revision used. The last two options are mutually exclusive, and if neither is specified, the labeled revision will the the latest version checked in.
The actual Projector commands used are:
NameRevisions -project <project> <file>
for regular files,
NameRevisions <label> [-replace] [-dynamic] -u <user> -project <project> <revision>...
for advanced files and for the advanced recursive version with local revisions specified,
NameRevisions -project <project> -r -only
for the recursive version and
NameRevisions <label> [-replace] [-dynamic] -u <user> -project <project> -r -a
for the advanced recursive version. When specified, the replace option
is only used for the first Projector command used in the VCS command.
Return to the Commands.
The Rename command allows you to rename a file in the Projector database.
CMProjector will prompt you for a new name for each file, renames the file
in the database, orphans the old file and checks out the new file for you.
The actual Projector commands used are:
RenameProjectorFile -project <project> -u <user> <filename> <new name> OrphanFile <file> CheckOut -d <dir> -project <project> <new file>
Return to the Commands.
The Add command checks a new file into the Projector database. If
you are using Header Comments, you will be asked to give a brief description
of the contents of the file for the header. If the file already has a header
comment, you will be asked whether you wish to reuse it. if you answer yes,
the entire header (including the old change history) will be kept and a
new history started at the top of the change history section.
If the file is in a folder for which there is no corresponding subdatabase,
CMProjector will attempt to create subdatabases. For each subdatabase, you
will be asked if you wish to create it and for a creation comment. If you
cancel at any point, the Add will fail and that particular subdatabase will
not be created. Previously created databases will not be backed out.
The actual Projector command used is:
CheckIn [<options>] -new -cs <comment> -project <project> -u <user> <file>
The advanced options dialog (available from the Advanced submenu) brings up a dialog that allows you to specify the following options:
[-m | -delete] [-touch] [-verify] [-t <task>]
The task is set to the last task you entered (if any). None of the options
are specified by default.
For subproject creation, the command used is:
NewProject -u <user> -cs <comment> <database path>
Return to the Commands.
The Delete command removes a file from the Projector database and
orphans the file.
After deletion, the file is still in the database as an obsoleted file,
but CMProjector has no interface for recovering it. You must use the MPW
command UnObsoleteProjectorFile.
The actual Projector command used is:
ObsoleteProjectorFile -project <project> -u <user> <file> OrphanFiles <file>
The MPW shell syntax for the Projector UnObsoleteProjectorFile command is:
UnObsoleteProjectorFile -project <project> -u <user> <file name>
Return to the Commands.
The Purge command orphans the file but does not remove it from the
database. The Recursive version orphans every file in the specified directory.
You will be prompted for each file and can specify "Yes" to orphan
the file, "No" to skip a file and "Cancel" to abort
the rest of the operation.
After purging, the file is still in the database, but the local copy has
no 'ckid' resource and the Finder will display it as not being in the database.
To recover the file, you must use the Get command.
Purge is most useful for importing files from another database. You copy the file into the local source directory and add it to the project. After Purging the file, you can now add it to the current database.
The Recursive Purge command is most useful for exporting a source tree. After getting copies of all the files to export, you can issue the Recursive Purge to orphan all the files. You can then connect to a new database and start adding the files again.
The actual Projector command used is:
OrphanFiles <file>
Return to the Commands.
The About command displays a dialog box with version information.
Return to the Commands.
The Variables command displays information about all the member databases.
The information appears in a scrolling text box that you can save.
The actual Projector command used is:
ProjectInfo -project <projectName> -only -r
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.
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.