Cornerstone

Frequently-Asked Questions

  1. What do I do if I have lost my license key?
  2. I enter my license information into the License Registration window but the 'Register' button is disabled
  3. Which version of Subversion do I need to use Cornerstone?
  4. Why doesn't Cornerstone use the copy of Subversion which came with my Mac?
  5. Can I use the version of Subversion which comes with Cornerstone?
  6. What version of Mac OS X does Cornerstone support?
  7. Can I run Cornerstone on a PowerPC Mac?
  8. I can't connect to a repository when my user name contains an @ character. What can I do?
  9. I'm having difficulties connecting to an old Subversion repository. What can I do?
  10. Why is moving working copy items so slow?
  11. Why is working copy access so slow?
  12. Why aren't items in external directories committed along with the rest of my working copy?
  13. Why do I get an error stating Unable to contact repository at <server> when checking out a working copy?
  14. I can't rename a directory which contains an external directory. What gives?
  15. Why are files with accents and diacritics in their names displayed twice in my working copy?
  16. Cornerstone complains that my working copy is out-of-date even though nobody has changed the files in the repository. Why is this?
  17. What are all these .svn folders doing in my working copy?
  18. Can I use Subversion to manage package files from applications like Pages and Number?
  19. How do I uninstall Cornerstone?

What do I do if I have lost my license key?

Send an e-mail to our support e-mail address, and include the e-mail address you used when purchasing your license and we'll get back to you as soon as we can.

I enter my license information into the License Registration window but the 'Register' button is disabled

Make sure that all the information you have entered into the window is exactly as it appears in the license mail you received.

Also note that you must specify the e-mail address that was used to purchase the license. If the license was purchased by someone else in your organization then you will have to use their e-mail address when registering the license.

Which version of Subversion do I need to use Cornerstone?

You don't need to have Subversion installed to run Cornerstone because it comes with its own copy of Subversion baked into the application. This applies to both Mac OS X 10.4 Tiger and 10.5 Leopard (which includes Subversion 1.4.4 out of the box).

Why doesn't Cornerstone use the copy of Subversion which came with my Mac?

Mac OS X 10.5 Leopard includes the Subversion command-line tools (svn and svnadmin) but does not include the libraries required by Cornerstone. In addition, Mac OS X 10.4 Tiger doesn't include Subversion at all. The simplest solution (and the one which ensures consistency across versions of Mac OS X) is for Cornerstone to include its own version of Subversion.

This has the added benefit of allowing us to include the latest and greatest version of Subversion with our application without you having to worry about upgrading your Mac OS X installation.

Can I use the version of Subversion which comes with Cornerstone?

No. Cornerstone doesn't use the Subversion command-line tools and therefore doesn't contain them. Instead, Cornerstone uses the same libraries used by Subversion's tools, enabling the tightest possible integration.

The downside? If you need to use Subversion's command-line tools then you will need to either be running Mac OS X 10.5 Leopard or install Subversion yourself on 10.4 Tiger.

What version of Mac OS X does Cornerstone support?

Cornerstone has been tested on 10.4.11, 10.5 - 10.5.4. Zennaware recommends running Cornerstone on a recent Intel Mac with OS X 10.5 Leopard for the best experience.

Can I run Cornerstone on a PowerPC Mac?

Yes. Both PowerPC G4 and G5 processors are supported.

Cornerstone should run fine on any Mac bought in the last 5 years with a sensible amount of RAM. That means at least 512 MB for 10.4 Tiger and 1024 MB for 10.5 Leopard.

If you're doing serious development or graphic design on your Mac with tools such as Xcode or Adobe's CS3 suite then your computer most probably meets these requirements anyway.

I can't connect to a repository when my user name contains an @ character. What can I do?

URLs which contain a user name are specified in the following form:

scheme://user@server/path

Attempting to specify a user name which contains an @ character (i.e. in the form user@domain) causes the host name to be incorrectly interpreted as domain@server.

RFC 1738 (a public specification which defines how URLs should be formed) stipulates that @ characters in user names should be replaced with %40, e.g. scheme://user%40domain@server/path.

Many thanks to Erik Aigner for the tip.

I'm having difficulties connecting to an old Subversion repository. What can I do?

Cornerstone can't connect to the root directory of a pre-v1.2 Subversion repository. This is because the server doesn't correctly report information about the repository. One workaround is to specify a sub-directory with the repository URL (e.g. http://svn.server.com/repos/project/trunk instead of http://svn.server.com/repos).

The likelyhood that we can provide a solution to this issue in the future is slim as the issue lies in the interaction between the repository and version of the Subversion client as used by Cornerstone.

The only alternative is to ask your Subversion administrator (very nicely) if it would be possible to upgrade the repository to a newer, more current version.

Why is moving working copy items so slow?

Subversion ensures that changes made to a working copy are time-stamped to the minimum resolution of the file system. On Mac OS X this defaults to one second. Copying or moving multiple files therefore takes approximately one second per file or folder.

Why is working copy access so slow?

Browsing a working copy in Cornerstone can become slow when:

  1. A working copy is very large (i.e. contains many thousands of files).
  2. Access to the working copy's originating repository is slow due to poor server performance or slow connection type.

Performance issues with large working-copies can be solved by:

  1. Suppressing evaluation of external folders in working copy. This is done by disabling Show Contents of Externals on the View menu.
  2. Reducing the size of the working-copy. For example, if a project has a top-level directory (such as trunk with numerous sub-directories containing modules, libraries or frameworks) then you can try checking out the project into several working copies.

Connectivity-related performance problems can be solved by disabling the display of files' repository status until absolutely necessary. Do this by disabling Show Repository Status on the View menu.

The view changes described here will remain in effect even after the application is restarted.

Why aren't items in external directories committed along with the rest of my working copy?

When committing a directory (or an entire working copy) which contains a directory mapped to an external reference using the svn:externals property, changes in the external directory are not committed. To commit these changes, select either the external directory or the files with changes and commit them explicitly.

This behavior is inherited from Subversion and is by design: it prevents changes to external files or directories from being inadvertently committed when committing changes to the working copy that contains them.

Why do I get an error stating Unable to contact repository at <server> when checking out a working copy?

If you encounter this error message when checking out a project even though the check out process appeared to complete successfully, check that repositories referenced by svn:externals can be reached and that the URLs are correct. This error is particularly likely if you are using a local repository and then attempt to check out a project with external references to a public repository on the Internet when you do not have Internet access.

I can't rename a directory which contains an external directory. What gives?

Renaming a directory which contains an external reference causes Subversion to become somewhat confused. On the one hand, it thinks the newly renamed directory is unversioned. On the other hand, the existence of Subversion admin files (that pesky hidden .svn folder) in the renamed directory causes no end of problems.

As a work-around, you can do the following to rename an external directory:

  1. Create a new directory using the Finder or Terminal.
  2. Add the directory to the working copy (done automatically if you create it with Cornerstone).
  3. Edit the svn:externals property to point to the new directory.
  4. Update the new directory. The directory will be populated with files from the external reference.
  5. Moved any new or modified files from the previous directory to that which you created.
  6. Delete the original directory.

Why are files with accents and diacritics in their names displayed twice in my working copy?

The Problem

The root cause is that Mac OS X's HFS file system stores filenames containing accents in a manner which confuses Subversion. As a result, such files are displayed twice in working copies, once as unversioned and once as missing.

This is obviously a severe issue for those in non-English speaking countries who (quite logically) like to use all the letters in their alphabet in their filenames. Unfortunately, the issue lies out of Cornerstone's hands and squarely with the Subversion developers. They have acknowledged the issue (see Subversion issue #2464 if you want to get involved in the resolution process).

Background

Here's some technical background for those who are interested:

File systems such as Windows' NTFS and Mac OS X's HFS store the text for filenames using a character set called Unicode. Unicode can be represented (or encoded) in any number of ways. When it comes to accents, they can either be expressed as a single accented character (e.g. a German-language ä) or as two distinct characters, one of which describes the base character (in this case a) and the other the accent (umlaut). Both are perfectly legal forms, with the former known as Normal Form Composed (or NFC) and the later as Normal Form Decomposed (or NFD).

The difference between the Mac's HFS file system and others in the Windows and Linux worlds is that instead of accepting the accent form specified by an application when creating a file and then giving it back verbatim when reading from the file system at a later date, HFS converts all filenames to the decomposed form. As a result, the application encounters decomposed strings when it subsequently obtains filenames from the file system.

This presents a problem to Subversion which is comparing a working copy file list it obtained from the repository (in composed form) against filenames from HFS which are in decomposed form. High-level programming frameworks like Cocoa, Java and .NET handle these encoding differences automatically, but systems like Subversion which are written in low-level C need to be explicitly programmed to take such encoding differences into account. And this isn't currently the case with Subversion.

See the Note on Unicode Composition for Filenames from the Subversion developers for even more detailed background information and the complexities involved in implementing a solution.

The Subversion developers are aware of the situation but a solution isn't currently in sight as of late-2008.

If this matters to you then we suggest that you get in contact with the Subversion developers and voice your interest in getting this solved sooner rather than later. The majority of Subversion developers and users are probably English-speaking and use computers other than Macs so the issue may not be being addressed with suitable priority.

It can't hurt to raise the profile of the situation by letting them know that it affects you!

Recommendations

Our recommendation is to simply not use accented characters in your filenames. We realize this is draconian (we're located in German/French/Italian/Romansh-speaking Switzerland after all) but it's the only workable solution at the moment.

Alternatively, you could try storing your working copies on a volume (such as an external drive) which is formatted with Microsoft's FAT32 format as Mac OS X supports writing to such volumes out of the box on both 10.4 Tiger and 10.5 Leopard.

A more adventurous alternative might be to use the MacFUSE file system to add NTFS write support to your Mac and then store your working copies on an NTFS-formatted drive. Be warned that MacFUSE installs a kernel extension on your Mac and while it may work well is not something we recommend to our users.

What we certainly don't recommend is storing your working copy on a remote volume on a file server.

Cornerstone complains that my working copy is out-of-date even though nobody has changed the files in the repository. Why is this?

Subversion updates the revision of folders in the repository to reflect that of the newest contained file, but this updated revision number is only picked up by the working copy when updated.

This will cause Subversion to complain that the working copy's folder is out-of-date when attempting to commit folder modifications such as file addition/removal or property modification.

Update the working copy to bring the folder up-to-date with the repository and then retry the commit.

What are all these .svn folders doing in my working copy?

When a folder is added to a working copy or checked out of a repository, Subversion stores additional information about the folder in a hidden .svn sub-folder which is termed the Subversion admin area.

As is the case with all hidden files and folders, these folders are not visible in Finder. However these hidden folders can be seen in the Terminal.

Subversion needs this information in order to know where the files came from in the repository when committing changes. It also compares your working versions against their original versions in the admin area to deduce which files you have changed.

You should never manually remove these folders (or the folders that contain them) from your working copy. Doing so will result in your working copy become corrupted, requiring that you update the working copy to allow Subversion to re-creating the missing admin files.

Can I use Subversion to manage package files from applications such as Pages and Number?

In general, Subversion can't be used to manage files in the package file format which is common on Mac OS X. Examples of package files include Pages' .pages files, Numbers' .numbers files and Keynote's .key files.

Background Information

While package files appear to be files when displayed by Finder, they are in fact folders, which contain structured information about the file, often several folders deep. You can browse the folder with Finder by selecting Show Package Contents from the file's right-click menu.

Subversion treats package files like normal folders, creating hidden .svn admin folders to record information about the source of folder's contents from the repository (see What are all these .svn folders doing in my working copy? for more information about these admin folders).

So far, so good. You can add package files to a working copy and check them out from your repository without issue. Problems only start when you edit the files with Pages, Numbers, Keynote etc.

When these applications save the changes you have made to the file, instead of leaving the folder intact, they create a complete new package folder hierarchy on disk and then delete the original. In the process, the hidden .svn folders are cleaned from the package file. As a result, Subversion no longer has the information it needs to manage the package's contents and will raise errors whenever operations are attempted.

In reality this means that the working copy has become corrupted. You can no longer commit changes to the package file and Subversion provides no way to recover from the situation.

The Root Cause of The Problem

The primary issue here is that the application editing the file insists on deleting the entire contents of the package every time it is saved.

The application certainly doesn't have to do this, and indeed there are applications whose package files can happily be stored in Subversion exactly because they don't do this. Apple's Interface Builder (.nib) and OmniOutliner (.oo3) are good examples of this.

Recommendation: Complain to your application vendor about this behavior. Request that they change the way the application saves files to maintain the existing folder structure.

Subversion could also handle this situation more robustly, for example automatically restoring a backup of .svn folders that go missing. Or even better, by not littering the user's working copy with .svn folders in the first place.

The Subversion developers are aware of this issue and are working on working copy improvements which could solve this problem for a future version, although it is extremely unlikely that a solution will be available any time soon (as of 11/2008).

Recommendation: Get involved in the issue resolution process. Let the Subversion developers know that this issue affects you and that you would like to see a solution as soon as possible.

Workarounds

  1. Use a script to restore the missing .svn folders

    Use this Unix shell script to restore the missing admin folders after saving changes to the package file.

  2. Store a .zip file in the repository

    Circumvent the issue altogether by zipping up the file and storing that in the repository. Unzip the file before editing it and add the unzipped file to the working copy's ignore list. Finally, zip up the file again before committing changes to the repository.

  3. Store the file in a different format

    If appropriate, store your Pages file as an RTF or Microsoft Word document (oh, the irony!). Use Microsoft Excel format for Numbers files.

How do I uninstall Cornerstone?

Perform the following steps to remove all trace of Cornerstone from your Mac:

  1. Move the application to the Trash.
  2. Move ~/Library/Preferences/com.zennaware.Cornerstone.plist to the Trash.
  3. Move ~/Library/Preferences/ByHost/com.zennaware.Cornerstone.*.plist to the Trash (the exact name of the file is specific to your Mac).
  4. Move ~/Library/Application Support/Cornerstone to the Trash.
  5. Move ~/Library/Caches/Cornerstone to the Trash.

Note that Cornerstone does not store any repository or working copy data in these locations by default (i.e. not unless you explicitly direct it to). No user data (other than application configuration information) will be lost by removing these files.