You can’t modify the files in the repository directly so you need to obtain your own copy of the files if you intend to work on them. This copy is located on your computer and is termed the working copy.
Subversion and Cornerstone are designed to be used with working copies stored on your computer.
This means that working copies should be located on your Mac’s local disk (although you may also store them on USB or Firewire-attached external disks.)
Attempting to use working copies on remote drives can result in performance and stability issues, especially with unreliable network connections.
In addition, working copies should never be accessed concurrently by multiple users. Attempting to do so will almost definitely result in file corruption and data loss.
A working copy is linked to the original location of the folder in the repository which is then automatically reference during subsequent commit and update operations. This link is persistent and, in most cases, will not change during the course of the working copy’s life.
A working copy need not (and indeed probably shouldn’t) contain the entire contents of the repository. Working copies should probably only contain the files you need to work on at any given time.
The repository should be structured to facilitate this organization. For example, a new folder should be created for each project managed by the repository. You can then check out multiple working copies (one for each project) as and when you need them rather than maintaining a working copy with the entire contents of the repository.
For the most part, working copy folders can be treated much like any other folders. You can modify the files using your favorite editor or build your projects using IDEs such as Xcode and Eclipse.
However, you generally shouldn’t move and rename the working copy’s files and folders using Terminal or Finder. Instead, you should use Cornerstone to manage the files in your working copies.
Don’t rename, copy or move working copy files using apps such as Finder or Terminal. Doing so can confuse Subversion making it difficult to commit changes to the repository or update the working copy’s contents.
Files in working copies are identified by the same paths as used by your Mac’s file system.
Getting a copy of the files to work on is referred to as checking out a working copy.
In some version control systems (such as Microsoft Visual SourceSafe and IBM Rational ClearCase the term checking out refers to exclusively locking a file for editing.
Note that checking out a folder from a Subversion repository does not lock the folder or the files that it contains but simply obtains a local copy of the files for you to work on. Other team members can still check out their own working copies and work on their copies of the repository’s files.
Changes made to working copy files are not immediately stored in the repository, instead requiring an explicit step known as a commit. This allows you to work in parallel to others in your team, only pushing changes back upstream to them when they are in a state suitable for sharing.
By default, all files in a working copy are expected to be placed under version control. As a result, all unversioned files (i.e. those not yet placed under version control by being added to the working copy) are displayed with a special status which is designed to attract your attention.
However you may not want to place some files under version control at all. Typically, such files include the products of build processes such as object files emitted by compilers and executables created by linkers.
By default, these files will be continuously brought to your attention by being marked as unversioned. This is distracting and makes it more difficult to isolate the interesting changes made to your working copy.
The solution is to tell Cornerstone that you want to ignore these items. As a result the items are not displayed by default in the working copy.
Cornerstone can only ignore unversioned files. Once a file has been added to a working copy it can no longer be ignored.
The global ignore list is a Subversion option which defines files and file types that should automatically be ignored. The list can contain both filenames such as .DS_Store and patterns (or globs) such as *.o and *.pbxuser.
Files and folders which match items in this list will automatically be ignored when encountered in a working copy.
The global ignore list can be edited in the Subversion section of Cornerstone’s preferences window.
The global ignore list is a global preference which will affect all Subversion apps.
You pull other people’s changes from the repository to your working copy by updating your working copy.
Files and folders present in a working copy which have not yet been place under version control are described as unversioned.
Generally, files should only be left unversioned until the next commit, at which point they should either be added to the working copy (i.e. placed under version control) or ignored.
A very common error in team environments is to forget to add files to version control before committing, resulting in an inconsistent state in the repository which potentially prevents other team members from continuing their work when they next update their working copies.
By default, Cornerstone will prompt you to deal with unversioned files before performing a commit in an attempt to reduce the risk that such mistakes will be made (this behavior can be disabled in the app’s preferences).
Switching refers to changing a working copy (or a part of its contents) to refer to a different folder in the same repository. There are a number of situations where switching a working copy is appropriate:
It is not possible to switch a working copy (or part of it) to a location in a different repository.
Consider using an external definition to pull content from a separate repository into a working copy. Use relocate to point a working copy at the same repository via a different URL.
A switch operation is generally faster than a check out for the same files. The initial working copy and target location are frequently descended from a common ancestor, so Subversion will retrieve only the changes which are necessary to convert the working copy to the state of the new location.
Relocating a working copy refers to changing a working copy to point at the same location in the same repository via a different URL. Relocation is appropriate when:
A working copy’s contents are not modified during relocation—only the working copy’s metadata is rewritten to point to a different URL. Cornerstone will however verify that the new URL is valid by attempting to contact the repository.
Subversion expects the new location to identify the same folder in the same repository that the working copy originated from, but via a different URL.
Consider switching if you need to point a working copy at a different location in the same repository.
A tree conflict occurs when one user makes a change to a file or folder that has already been moved or deleted by another user.
Like textual and property conflicts, tree conflicts must be resolved before any further changes to the conflicted item can be committed to the repository.