When putting a file in CVS revision control with MacCVSClient, you have the choice to use one of three different storage formats.

Why do we have storage formats and why doesn't CVS on UNIX? The reason is the way resources are stored in resource forks in Mac OS files. Using the different storage formats, you can store resource forks of your Mac OS files in different ways depending on how you want to work with them.

This is important for "CVS Add" and "CVS Import" commands which both add files to your repository. The moment they are added to the repository, some decision has to be made about how the files should be stored.

In MacCVSClient, you have the choice of three storage formats:

Data fork only

This is good for text files. Also, graphics data like JPEG, GIF, or PNG files can be stored very efficiently using this storage format. The resource fork of the file is ignored though. This storage format is marked "DF" in the module window.

Resource fork and data fork in AppleSingle format

The AppleSingle format was introduced by Apple to store or process Mac OS files including resource fork, data fork, finder information, etc. on UNIX or other foreign platforms. This storage format is marked "DRF" in the module window.

Mergeable resource fork in RBL (Resource By Line) format

The RBL format was introduced in MacCVSClient 1.4. It is very useful, if you want to put resource files of types like PPOB or RSRC under revision control. The RBL format is CVS mergeable and diffable. This storage format is marked "RBL" in the module window.

If you use CVS to store your software development sources or your web pages, most of your files probably are TEXT files. For these, the "data fork only" storage format is the best choice. You are also free to CVS enable keyword substitution for text files. Depending on the editors you're using, CR/LF conversion can be disabled as well.

When keeping a set of web pages under CVS revision control, you might want to store your graphics like GIF or JPEG files in the CVS repository. These files and all other files that don't use the resource fork can be stored as "data fork only" as well. If redundant information (like custom icons that show the contents of a graphics file in the finder) is held in the resource fork, the "data fork only" storage format can be used as well. Keep in mind though that resources are not stored in the repository.

When a "data fork only" file is updated with new data from the CVS server, it's existing resource fork is kept unchanged. This is useful for e.g. TEXT files where cursor and window positions are stored in the resources by different editors.

Be sure that you disable CVS keyword sustitution and CR/LF conversion when adding a non-TEXT "data fork only" file to your CVS module. If you forget this, your binary data is quite likely to get corrupted by unwanted string replacement and/or CR/LF conversion.

If you have files that contain important data in both resource and data fork, you can add them to your CVS module in data and resource fork storage format. Here, in AppleSingle format, both data and resource forks plus finder information like e.g. file type and file creator are stored in the CVS repository. This format is supported by MacCVS Pro and MacCVS as well.

Be sure disable CVS keyword substitution and CR/LF conversion here as well. See also the last paragraph in Data Fork Only above.

If you have a file that uses the resource fork only, you can store it in RBL format in CVS repositories. Files in RBL format are CVS diffable and CVS mergeable.

Suppose in your Mac OS software developement project, you have e.g. PPOB or RSRC files storing the resources for your applications menus, windows, dialogs, etc. Wouldn't it be useful to have the same diff and auto merge functions for these resource files as CVS offers for source code files? This is where RBL comes in. It does that very job.

When adding a file as mergeable resources in RBL storage format to your CVS module, you can even enable CVS keyword substitution. If you put any CVS keyword string like "Id", "Revision", etc. between dollar signs into a resource's name and then commit the file, you have the keyword expansion result available in the resource name.

The resource data is encoded as text in a robust way. Robust here means that keyword expansion can not corrupt it. Note also that the RBL storage format does not only work for PPOB or RSRC files. Almost any resource only file should be storable in RBL, no matter what resource types are used.

Three restrictions apply to the RBL format:

1. When MacCVSClient stores a resource file as RBL in the repository, the resource names must not contain characters with codes lower than SPACE. All characters with codes lower than SPACE are replaced by SPACE characters.
2. Only resources can be stored in RBL. Data forks can't. Moreover, existing data forks will be deleted when the file is updated with new data from the CVS server.
3. The CVS server must support 8 bit text and loooooong text lines. In RBL, each resource is converted to a single long text line. Depending on the size of the resource, this can easily amount to several kilobytes or even more. We use CVS 1.10 on Linux and it works just fine here.

All three restrictions are minor issues that shouldn't really affect your choice here. In particular, I don't think the fact that RBL only supports resource forks is a real restriction. If I am wrong here, please let me know and we can discuss the issue, see what can be done and possibly extend RBL so it supports data forks as well.

When you want to add files to your module, you have to select them in your module window. The files you select to be added need to be unknown to CVS. (Otherwise they already are part of your module and obviously don't need to be added anymore.)

There are some minor restrictions to the "Sandbox/Add" command in MacCVSClient:

1. You can only add set of files OR a set of folders at the same time. You cannot add both files and folders in one "Sandbox/Add" command.
2. The set of files or folders you want to add need to be located in a single (sub)folder of the module. You cannot add files "aaa:bbb:xxx" and "aaa:ccc:yyy" at the same time.

None of these result in major inconveniences during the work with MacCVSClient. At times, you might just have to run several "Sandbox/Add" commands instead of a single one.

When adding files, you should use the "Automatic" setting which then uses to the Import Translators you have set in your MacCVSClient preferences.

If you really feel you can't resist, you can also use the manual settings. I discourage this, though, and recommend you maintain the Import Translators well and use the "Automatic" setting.

Well then, if you can't go with the "Automatic" setting, the following settings are recommended in the "CVS Add" dialog:

• TEXT files: Data Fork, you can select any CVS keyword substitution setting.
• non TEXT files using data fork only: Data Fork, be careful about keyword substitution! Safe and thus recommended is Keep Old Keyword String + Inhibit CR/LF Conversion.
• Files using both data fork and resource fork: Data + Resource Forks. If you select this, the file(s) will be stored in AppleSingle format on the CVS server. I highly recommend that you disable keyword substitution and CR/LF conversion when storing files in AppleSingle format.
• Use the Mergeable Resources setting for resource fork only files. With this option, the file(s) are stored in RBL format on the CVS server. Like in normal text files, any CVS keyword substitution setting can be used.

The "Repository/Import" command takes the Import Translators into account as well.

Remember that instead of running a true CVS Import, you can alternatively insert a new set of sources as a module into a repository by first CVS importing a new and and empty folder and then adding the files and sub folders manually.

How does does a manual import work then? If you haven't got any files in your project, the procedure is obvious. You simply import an empty folder.

If you already have files, manual import means:

0. Create a new and empty folder structure and name the folders like you want them to be called in the module.
1. Import this empty folder into your CVS repository.
2. Check out a working copy of this new and empty module.
3. Move all existing files and folders of your project into this freshly checked out working copy (some call this working copy the "sandbox").
4. Use "Sandbox/Add" to add the files one by one or in groups.

The advantage of importing manually is that your files' revisions all start at "1.1". If you import the standard CVS way, you'll get "1.1.1.1" as initial revision for the imported files. Some people don't like this. I personally don't care very much, though.

You will have noticed that the commands "Sandbox/Add" and "Repository/Import" have quite a far reaching impact. They insert new files and folders into the repository. Undoing these commands is difficult. So you want to be sure to run them with the correct settings.

To help you with this, neither dialog (add and import) has an "OK" button. There are "Check" buttons instead. This way you are guided through a preview of the CVS command before actually changing the repository contents. It shows how your files would be added/imported if you did add/import them now.

Here's an example import preview window:

The Add/Import Check Results window displays the storage format and keyword substitution settings of all items. After double checking the results window here, you can invoke the CVS Add or Import command from here.

How do you check that files are added/imported OK? Select an item in the list and you'll be shown a short comment on the item's settings. If an item is shown in red colour in the list, that signals a problem. To find out more about the problem, select the file in question and you'll be shown the explanation.

At the top of the Add/Import Check Results window, you find a popup menu to change the content of the file list. Here you can select display modes such as all items, folders only, ignored items only, etc.. This way the list of shown files can be shortend to help focus on exceptional files which need to be reviewed.

To correct an import problem press the "Filters/Translators" button which leads you the the file filters and translators preferences. Correct the settings there and you will be brought back the the import preview.

If the import problem is not related to MacCVSClient settings, it is best to cancel the import here, fix the problems outside MacCVSClient and start the import procedure again afterwards.