You find basic concepts of MacCVSClient here. As MacCVSClient has no command line based interface, there are some differences in operating MacCVSClient compared to other CVS clients. Check this short CVS bibliography for more general information.

Let's assume you have set up a login profile and would like to check out a working copy of a project form server this login profile points to.

Use the "Repository/Check Out" menu command to check out a working directory of source files. This will bring the CVS Check Out dialog up on the screen:

In the "Login" popup menu in the check out dialog box above, the login profile "Joerg Testing" is selected and specifies all information about our intended user identity on the CVS server we want to connect to.

Assuming there is a source module "Example" in the CVS repository specified in the selected login profile, pressing OK will create the folder "Example" (or a list of folders the module "Example" is defined as on the server) in "Hulot:ProjectExperiments" and fill it (or them) with the module's contents.

The folders you get as a result of check out operations are often called sandboxes. They are your own copies of the files from the repository and you can mess with them, change them, play with them. You are (almost literally) sitting in your own little sandbox there — do as you please!

How do you now commit stuff, look at diffs, etc.? You have to open the sandbox. The easiest way to do this is to locate the sandbox folder in the finder and drop it onto the icon of the MacCVSClient application (or an alias pointing to it). Alternatively you can use the "File/Open" menu entry. A dialog to open a folder will show up. Find and select the the sandbox folder of the module you want to work with.

In the status area of the window you find the authentication/CVS server information that was used to check out this working copy.

Below that, the local working folder location ("Folder:") and some statistics about the files in the sandbox are displayed.

The "Folder:" shows one of two paths:

1. If some entries in the sandbox window are selected and all selected entries are located in the same (sub) folder, the path to this folder is displayed in italics.
2. If there is no selection or the selected items are spread over different folders, the path to the top level folder of this CVS sandbox is displayed in normal text.

In the sandbox window's main area, a single line (for a single CVS item) contains the following information.

1. Status flags.
2. File/Folder Name.
3. File Storage Format. See also: Storage Formats.
4. Sizes of data fork and resource fork in bytes.
5. Modification date and time of the file.
6. The file's CVS revision number.
7. Sticky options, if any.
8. Sticky Tag/Date information, if any.

How can such a CVS item look like? Here is an overview of the possible status flags.

Unknown

Marked with a '?' in the first column, drawn in light grey. These files are new and are not under CVS control.

Modified or Locally Changed

Marked with a bullet, drawn in red. These files have been changed locally and need to be committed.

Needs Update

Marked with a star '*'. A newer revision exists on the server and running an update would merge those new changes from the server into the file in this sandbox. When a "Sandbox/Status" or "Sandbox/Get Info" command is run, the resulting output is used to determine whether a file is up-to-date or not.

Lost

Marked with an 'L', drawn in red. These files are missing in the Mac folder. MacCVSClient has found a CVS entry for those files but the file itself is missing.

Conflict

Marked with a 'C', these files contain conflicts.

Normal

Unmarked, drawn in black.

Other CVS Folder

Marked with a '!' in the first column, drawn in light grey. Such a folder has been checked out using a different Login Profile than its surrounding folder. Thus, it can't be opened and worked with as subfolder. To access it, open it in a separate sandbox window.

Some CVS commands like diff, log or annotate produce file specific output which is stored in hidden temporary files. This output can be viewed from within MacCVSClient.

In case file specific output is available for a file, this is indicated in the status flag area of the file:

Diff Output

Indicated by the Greek letter delta. [see Collecting Comments and CVS Diff]

Log Output

Indicated by the ® sign. [see The Log Window]

Annotation Output

Indicated by the @ sign. [see The Annotation Window]

When the CVS team collaboration commands Edit, Watch and friends are being used, the following flags might be shown as well:

Edited (by me)

Indicated by the letter 'E'. The command "Sandbox/Edit" has been run on this file in this sandbox. [see Team Collaboration Features]

Edited by others

Indicated by the letter 'e'. [see Team Collaboration Features]

Watched by me

Indicated by the letter 'W'. [see Team Collaboration Features]

Watched by others

Indicated by the letter 'w'. [see Team Collaboration Features]

If a module is defined in the CVS modules database, it may not have a real module folder in the CVS repository. In a checked out sandbox, all folders defined in the modules database (and thus not having a real folder in the CVS repository) are marked with a small cross just next to the module name on the right.

If you have modules with many files, you sometimes do not want to see all of them. You might be interested only in e.g. locally changed files or unknown files. Or you might want to see only files that match a certain name pattern.

The filtering options in the filter settings dialog should be self explanatory. The listed criteria can be AND and OR joined. Filtering can be done in a HIDE or SHOW mode, the former hiding matching items, the latter showing matching items (and hiding everything else).

Use the commands "Special/Filter (Show Matching Items)", "Special/Filter (Hide Matching Items)" and "Special/Filter File Settings...".

The picture above shows the same module as before in the same state. This time, file filtering is activated and locally changed, added, removed, lost or unknown files are displayed. All other files are suppressed. Bear in mind that filtering affects only the display in the module window, no file or folder is deleted at all.

The current filter mode is displayed in the status area on the bottom left side of the module window.

When a folder is displayed with filtering switched on and not all the folder's files are displayed, the folder is described as "Partial Folder" in the module window. If you select this folder and run a CVS command like "Sandbox/Update" on it, the command is run on the whole folder. In the "Sandbox/Update" case, all files in the folder would be updated and not only the few files that are displayed.

In the sandbox window, file status information is displayed in form of flags in the flags column.

Some of the status informaion behind these flags is persistent, i.e. is preserved after a sandbox is closed in MacCVSClient. This information then is immediately available the next time the sandbox is opened in MacCVSClient.

The persistent flags are: Edited, Lost, Conflict, Modified, Need Update, Unknown.

Other information is of transient nature. That means its lifetime is limited to the time the sandbox is open in MacCVSClient. After closing and re-opening the sandbox, the transient information needs to be regenerated usually by reconnecting to the server, e.g. logs, diffs, annotations, editors or watchers lists.

For each folder the persistent flags for all its contents are countedand the counts are shown in the folder's line in the sandbox window.

Overall counts of persistent flags in a sandbox are shown in the sandbox window's status area at the top of the window. If the folder itself contains subfolders, number pairs "A/B" will be shown instead of single numbers. Here, A is the number of files Lost, Modified, etc. in the folder itself and B for the folder and all its subfolders (recursively).

When you switch away from MacCVSClient to another application or the finder to do other work there and then switch back, MacCVSClient automatically refreshes the cached states and modification dates of the files in the currently opened CVS sandboxes. This refresh operation can take some seconds depending on size of the module folders and speed of the machine.

As an example, to refresh a project of about 300 files on a 7300/200 Mac's local disk takes about two seconds.

So when you're in the finder or another application and then switch to MacCVSClient, there will be a short delay if you have open sandbox windows in MacCVSClient.

While working with MacCVSClient, you should make sure that none of the files that are (or might be) in use by MacCVSClient is currently in use by another application. It is evident that if you have e.g. a file opened in CWIE or BBEdit while updating it in MacCVSClient you might lose data.

My recommendation therefore is to e.g. close all editing windows in your text editor(s) before switching to MacCVSClient. This is nothing special to MacCVSClient but a general principle to obey when working with different applications on the same files at the same time.

See also: Error -47.