Introduction

For any type of software product development, version control is essential. This is true even when there is only one software developer working on the project (as in many of the iPhone/Android projects). Having a version control has the following advantages,

• An efficient incremental backup – A version control system only stores changes between versions and hence is a very efficient incremental backup solution.
• Complete history of a source file – Version control maintains the entire change history of a source file. It is also easy to do comparisons betweens two versions to see what has changed in the past. You can also attach comments to each version that is added to version control.
• Complete freedom to change working copy – Since version control acts as a just in time backup, you can freely change the working copy. At any point if you want to revert, you can replace working copy with the repository copy.
• Developer responsibility – Since each version in version control also contains the user id of the developer who made the change, it is easy to assign responsibility for a change.

Typically a version control tool has two parts. A server side component installed on a remote machine and a client side component installed on the developer machine. However in case of projects done by a single developer(iPhone, for example), both can be on the same machine.

Subversion Basics (Basic Concepts You Need to Know)

To work with Subversion you need to have a fairly good idea about the following concepts,

• Repository – The data store where version controlled files are stored. This is completely managed by Subversion.
• Import – The process of adding a new project to Subversion repository.
• Working Copy – The local copy in a developers machine which has Subversion version control information.
• Checking out – The process of creating a working copy from repository.
• Commit – The process of applying changes in a working copy to the repository.
• Update – The process of applying changes in a repository to the working copy. These changes usually come from working copies of other users.
• Branch/Tag/Copy – These all refer to the same underlying operation and just creates a new version in Subversion.
• Merging – The process of merging changes done in a specific version to another version in Subversion.

Using Subversion on a Mac OS X Machine

In this article, I will explain how you can use Subversion as a version control tool in Mac OS X. I will also assume that the Subversion repository is installed son the same machine that is used for development. This means that you don’t need a server running on your machine. For the local file system access, the repository permissions are dependent on file system permissions. This is the simplest setup for a single developer and all repository URLs will begin with file:///

Installing Subversion on Mac OS X

Subversion binaries for Mac OS X can be downloaded from the community downloads section of Collabnet site. Ensure that you download the correct version for your Mac OS X machine (there are separate downloads for Leopard and Snow Leopard). Unfortunately, in order to download you need to register an account at Collabnet site.

Collabnet installer is a universal build and contains Subversion client, Subversion servers (apache modules and svnserve), Repository datastores (Berkeley DB, FSFS) and svn language bindings.

Click on the downloaded dmg file to install Subversion on Mac OS X. Subversion binaries will be added to /opt/subversion/bin folder. You need to add the following line to the ~/.bash_profile file to ensure that this folder is available in the PATH variable. (.bash_profile is located in your home folder. This is a hidden file which can be edited using the pico or vi text editors.)

export PATH=/opt/subversion/bin:$PATH

Close and open terminal window again. Check that the path variable is properly updated by issuing the command,

Creating a Subversion Repository

The first step after installing Subversion is to setup a repository. Repository is a special folder created by Subversion system and it will contain all your projects. Open a terminal window and then change the current directory to the directory in which you need the repository created. In our case, we decided to setup subversion repository under the following directory,

/Users/jay/subversion

To create repository, issue the following command from the terminal window,

This will create a subversion repository named repo under the current folder. If you inspect this folder you will notice that there are a number of folders and files inside this. However, you will never interact with these directly.

Now your Subversion repository is ready for use. Following URL is used for accessing this repository using local file system access (the format is file:///<path to repository>/<repository name>,

file:///Users/jay/subversion/repo

Organizing Repository Folders in Subversion

On the local file system I have the following folder structure to organize all my projects. At the root of the folder structure is the projects folder. As you can see there are two projects – Writing an SRS and My Expense Tracker.

The bottom most folder in each of the trees is the individual project. While using Subversion repository for your projects ensure that you have the same folder structure in the repository. This enables you to keep everything organized. So the above local structure is mirrored in the Subversion using the following repository structure.

You might be surprised to find a lot of additional folders! When it comes to individual project folders, Subversion requires a different structure. This is because you may have more than one active version of each project and your local copy is just one of them. Subversion convention specifies that your project should be organized in 3 different folders,

• trunk – Trunk contains the main branch for the development of your project. When you start your project, everything goes in here.
• branches – Branches are created for a separate line of development. This is to develop new features without disturbing the main trunk folder used for development. Once complete, files in branches are finally merged back to the trunk.
• tags – Tags folder contains versions which corresponds to each production release of your project. Whenever you decide that the code in trunk is ready for release, you copy it to a sub folder inside the tags folder. The folder name usually is the release number or version number.

Important – Note that inside trunk/branches/tags, project folder name doesn’t appear. This is ok since we will be adding the contents of the project folder directly into trunk (for branches/tags in a subfolder indicating the version).

So let us see how we create the above Subversion repository folder structure from command line. I assume that the local folder structure is already there (created using Finder application). The following commands with create the folder structure that we need in repository.  The -m switch in svn command specifies a comment.

Now the Subversion repository is ready for adding and managing individual projects. In our case we are ready with one iPhone project and also with an articles project for jay.

Whenever you decide on the folder structure, think about the individual pieces that you want to release as a unit. This can be modeled as a single project.

Adding Project Folders/Files to Subversion

Let us now add the "writing an SRS" project to the repository (Which is already created in the local system using Finder). Open terminal and change directory to  "Writing an SRS". Then execute the following command.

The above command will import the "Writing an SRS" folder/project contents to the Subversion trunk folder specified. Now "Writing an SRS" project is available in repository for version control. However the local copy is not yet a working copy. To make changes that can be committed to Subversion, you need to check out the project.

Checking out a Project from Subversion to Create a Working Copy

Let us now checkout the project we just added to repository. Let us check out the folder to the same directory from where we uploaded the project to repository. First delete the contents of the folder "writing an SRS" from the local system (This is necessary only if you want to check out to the same parent folder). Then from the same folder execute,

Now we have a local working copy of "writing an SRS". Any changes made locally can be easily committed to the Subversion repository.

Committing a Modified File to Subversion

Now in order to commit any changes made to any of the files inside the project "writing an SRS", you can execute the following command from the "writing an SRS" working copy folder.

Updating Working Copy from Subversion

If you have multiple users accessing the subversion repository from different working copies, you need to update your local working copy by taking latest versions from repository. You can update an entire project using,

Note that update is never required if you have only one working copy for the project (single developer setup).

Creating a Tagged Version in Subversion

When the code in your trunk is ready for release, you can copy it to the tags folder. This version can be kept as the snapshot of the application for the release. Let us copy the current trunk version of “writing an SRS” project to the tags/1.0 folder (Important – Ensure that there is no folder 1.0 already in Repository, otherwise trunk folder will be created inside 1.0 folder!"

Creating a Branch in Subversion

Subversion internally doesn’t have any difference between tags and branches. Hence the command for branching is same as that of tagging (see previous section). The only difference is that the project will be copied inside branches and not tags. The difference between branching and tagging is only conceptual. The release version snapshots will go into tags folder and alternate development tracks will be managed in branches folder.

Merging a Branch to a Trunk in Subversion

At some point in development, you would require changes in a branch applied to the trunk. For example, Assume that the branch was created for production bugs and the trunk was maintained for the next version release. Now before pushing out the new release, you would need all the branch changes applied to the trunk. Subversion merge command can be used for this. However there is limited support for merging in Subversion and you need to manually keep track of the versions already merged (to avoid merging branch changes twice). Also it is better to merge changes in regular intervals to manage the complexity of dealing with conflicts.

Here is a sample process we usually follow in our projects,

• Update the working copy with trunk code.
• Merge the branch version to the working copy using the following command. We know that  we have already merged till version 1210 and that the current version (head) in branch is 1222.

• Now review all the changes done in working copy and resolve any conflicts. The command svn status will display conflicts if any. Once you have resolved the conflict manually, issue the command svn resolved.
• Finally commit the entire project back to trunk with a label clearly indicating the merging details including from and to revision numbers (1210 and 1222 in this case).

Miscellaneous Subversion Commands

• svn status – Check status of the local file/project.
• svn diff – Compare two versions. See help for more details.
• svn revert – Revert all local changes.

To get more details on any Subversion command, use the svn help option. For example, the following will print the details of diff command,

Using Xcode as the Subversion GUI Tool

Even though all operations in Subversion can be executed using terminal commands, it becomes a hassle when you are using an IDE for your development. Almost all IDEs these days support subversion and Xcode is not an exception. Xcode provides excellent Subversion integration including file comparison. You can invoke the repositories module from the "SCM" menu of Xcode. This tool supports import, check out, copy, move and create directory operations. This tool can also be used to verify contents of an existing Subversion repository.

Other standalone Subversion GUI clients for Mac OS X are,

• svnX (free)
• ZigVersion (free)
• Corner Stone (Commercial)
• Versions(Commercial)