This HOW TO covers a complete method for interacting with a Subversion repository on Mac OS X, using the svnX GUI application.
First, download the svnX application from:
http://www.macupdate.com/info.php/id/15527
Next, you will need the subversion client binary, called simply svn. I have compiled a universal static binary (version 1.3.2) which should run on any OS X system. Download it here: svn.tar.bz2
Put this binary where you'd like to keep it. For now, I will assume it is in a folder called "/Users/myname/Applications/". Replace this path with wherever you decide to keep the svn binary.
Install the svnX application just as you would any other OS X application: Double-click the .dmg file to mount it, and drag the application to your Applications folder:
Run svnX by double-clicking its icon. You should see two windows appear, called Repositories and Working Copies:
First, an explanation. When working with version control, there is always a "central repository" which keeps a kind of "master copy" of the documents for your project. Workflow is as follows: You "check out" the documents you want from the repository, modify them, and then you "commit" your changes. The Subversion system takes care of tracking changes between versions, so that if you "commit" a change, but later decide you need a previous version, you can get it. Subversion also supports operations such as moving files, renaming files, deleting files, and adding new files. These must usually be done through svnX, rather than through OS X's Finder, so that the repository knows about your changes.
As it stands, svnX expects a copy of the svn binary to be located in your system at the wrong place. We must tell it where we put this file that you have downloaded. Go to Preferences under the svnX menu:
You should see the following dialog box:
In the text box called Path to svn binaries folder, insert the path to wherever you stored the svn file: /Users/myname/Applications/
Now svnX knows where to find svn. Let's try adding a repository. Click on the "+" symbol in the Repositories window:
→ 
Fill it out with your repository server information. The Name can be anything you want, and the Path must be a URL indicating the server and path where the repository is located. It usually begins with http:// for repositories hosted on the web, and with svn+ssh:// for repositories accessed through SSH. Another possibility is that your URL starts with https://. Unfortunately svnX has some problems with https, but they can be easily resolved, as described here.
Once you fill out this information, double click on the entry in the list at the top of the window. You will get a window displaying the contents of the repository:
You can see buttons for copying files, renaming (moving) files, making new diretories, and deleting files. We will revisit these concepts soon. For now we will deal with simply modifying an existing file.
To work on the project, you must first check it out. Click on the svn checkout button at the top. A file dialog will be displayed. You must enter the location where you wish to make your local copy of the project. (Your "working copy".) Usually you will create a new folder somewhere, and choose it. A new entry will appear in the Working Copies window.
You may now make any changes you wish. In the example, we have added a line to README.txt, using TextEdit. We now wish to commit our changes.
Going back to svnX, we see our working copy listed in the Working Copies window. Double-clicking it presents us with a list of modified files.
In this case, only README.txt has been modified. Double-clicking it will show us the local copy. More interesting is the FileMerge button. It shows you the differences between the working copy and the latest version in the repository:
In a case where two people have modified the same file, this window can be used to "resolve" conflicts. In most cases, two people will not edit the same lines of the same file, and thus the merge will be quite straight-forward. However, in such rare cases, the FileMerge dialog allows you to choose whether to use the lines in the repository or the edited lines in the working copy.
Clicking on the commit button, once you are satisfied with FileMerge, commits the changes to the repository. It also increases the revision number. You will be presented with a dialog allowing you to annotate your changes. It is highly recommended that you properly document your reasons for making a change. From experience, even if it is a single line explaining your reasoning, you will be rewarded later by not having to guess at your own (or others') reasoning. Additionally, comments entered here can later be retrieved for release notes and documentation purposes.
Once your changes are committed, they should disapear from the list of modified files.
Note that any commit increases the revision number for the whole repository. This is by design. It means that you can know exactly what state the project is in only by providing a single revision number.
Going back to the Repositories dialog, we can see that our annotated change has been noted:
This HOW TO will not cover every file operation possible in svnX. However, simply be aware that you must tell Subversion when you do things like delete files, rename files, or create new files. This can be done through svnX's Repositories dialog. When you perform these operations, you must commit the changes, and you will be presented with an opportunity to annotate your reasoning, just as for a normal file modification.
When you delete files, they will be deleted from that revision onwards. That means that you can always recover previous versions of files, once they have been added to the repository. Future check outs will not get that file, since it has been deleted, and is no longer considered part of the project. However, if someone recovers a previous revision, they will get the deleted file.
You can put binary files, such as images, into Subversion. However, with text files, it is simple for Subversion to analyze which lines have been modified from one revision to the next. Revisions will still be kept for binary files, but storage may not be as efficient. If this is of no concern, I recommend using it for images and other important files that should be kept with the project. However, you should assume that Subversion will keep a new copy of the whole file everytime you perform a commit on binary files. Therefore, be diligent with your changes — do not use it on temporary files. Version control is meant to really be used on the project itself. Sandbox files, tests, and temporary files should not be kept in version control. However, in many projects, images and other data files are as important to the project as the source code and documentation, and therefore I see no reason not to use version control on them, as long as disk space is available.
I must stress something here — do not commit "generated" files. Version control is meant for source code. This goes for things like LaTeX files as well. Any file which is the "source" for another file, be it .tex, .c, or whatever, should be version controlled. However, files which are produced, based on these sources, such as executables or PDFs, should not be kept in Subversion.
The idea is that someone should be able to check out the project, and have everything necessary to generate the executable or final product in one or a few steps. However, if they have not changed any source, doing an "svn commit" should not find any differences with the repository. If a "generated" file is in the repository, simply performing a compile on the project will incorrectly detect changes, since the resulting product (an executable, or PDF, etc.) would have been overwritten by compiling it.
It may seem a little too simplistic to specify this here, but I've seen too many source repositories that end up being misused as a simple deposit for any type of file, executables and binary libraries included. Remember, source control is only for source.
You will find that when you work with version control, on any project, be it software, documentation, or web sites, version control is essential for managing shared files. Personally, I find it useful even when I am by myself, since it allows me to keep folders synchronized between my desktop, my laptop, and my school account. I never have to guess which one is the most up-to-date copy, or which computer I made certain changes on. Subversion guarantees that I can always check out the latest version, or recover previous versions if I made some mistake. It also means I do not have to worry about deleting things -- a benifit to anyone who's suffered from "comment syndrome", wherein a programmer will leave 3 different copies of a piece of code commented-out for fear of deleting something important that a previous programmer did. With source control, you are free to make any changes, since mistakes can always be recuperated.
Last modified on Monday, Nov. 13, 2006.