Tools
Using Subversion with Xcode, Part III
In Part I, I walked through the process of setting up repositories and projects in Subversion, Part II covered configuring Subversion with Xcode, this part will provide an overview of the SCM tools within Xcode and also show you how to tag and branch your code within Subversion.
Xcode SCM Attributes
If you have your project successfully configured for use with Subversion, once you check-out your files and make any changes Xcode will identify these changes with attributes. Once you start editing a file, an ‘M‘ will show up next to the file in the Groups & Files window. Also, if you add any files to your project these will be identified with a ‘?‘. These attributes will remain until your changes are committed or if you discard your changes.
Committing & Discarding Changes
If you are familiar with other version control systems, you might know committing as ‘check-in’ and discard as ‘undo check-out’. You can commit or discard changes at the file level by right-clicking each file or folder and making the selection or by selecting ‘SCM‘ from the menu and selecting commit or discard changes. The ‘SCM‘ menu also allows you to commit all the changes in your project by selecting ‘Commit Entire Project‘.
Other SCM Tools
The Xcode SCM Menu provides a couple of ways to easily compare the contents of any file that you have checked-out with any revisions committed in Subversion, using FileMerge and the Unix diff tool.
Compare
By selecting ‘Compare With’ from the ‘SCM‘ menu, Xcode will open the FileMerge application that will show each file side-by-side and indicate the differences between each file. In File Merge, you can choose to add or remove any lines in your checked-out file.
Diff
If you have had exposure to the diff tool in Unix/Linux, it is available as an option to use within Xcode. By selecting ‘Diff With‘ from the ‘SCM‘ menu, Xcode will execute the diff command with your currently checked-out file and the revision file that you specify as arguments. The results of this command will be displayed in the current code window.
Subversion Tagging
In Part I, I mentioned that Subversion also has the following folders: tags and branches. The tag folder is used for storing releases or stable builds of your code and allows you recall the correct version of the project files if you need to fix any bugs. Here is a script that will allow you to tag your project, it assumes that whatever the is currently committed in the trunk folder is what you want to tag:
# A script to tag a SVN release
reporoot=/Library/Subversion/Repository/
projdir=Projects
# Prompt for repository name
print -n "Enter repository name:"
read repo
# Prompt for project name
print -n "Enter project name:"
read project
# Prompt for release number
print -n "Enter release number:"
read release
# Tag release
svn copy file://$reporoot/$repo/$projdir/$project/trunk file://$reporoot/$repo/$projdir/$project/tags/release-$release -m "Tagging the $release release of the ‘$project‘ project."
echo
echo Tagging the $release release of the $project project Complete!
echo
Subversion Branching
The branches folder is used for storing code that you want to develop new functionality with or experiment on without making revisions to the code in the trunk. Here is a script that will allow you to branch your code, also it assumes that whatever the is currently committed in the trunk folder is what you want to branch.
# A script to branch a SVN trunk
reporoot=/Library/Subversion/Repository/
projdir=Projects
# Prompt for repository name
print -n "Enter repository name:"
read repo
# Prompt for project name
print -n "Enter project name:"
read project
# Prompt for branch name
print -n "Enter branch name:"
read branch
# Create branch
svn copy file://$reporoot/$repo/$projdir/$project/trunk file://$reporoot/$repo/$projdir/$project/branches/$branch -m "Creating a branch of the ‘$project‘ project."
echo
echo Creating a branch of the $project project Complete!
echo
I hope you enjoyed reading this 3 part tutorial on setting up Subversion within Xcode. Please share your thoughts on how you use Subversion or any other SCM system with your development environment.
Using Subversion with Xcode, Part II
In my previous post, Using Subversion with Xcode, Part I, I covered how to create a repository and provided a set of scripts to use to automate these tasks. In this post I will demonstrate how to use the SCM client within Xcode to access your Subversion server.
SSH
Before you can use Xcode’s SCM client to connect to your Subversion server, you need to enable the SSH server on your Mac. SSH server is installed by default on OS X 10.5, to enable it open System Preferences.
From the Internet & Network section, select the Sharing icon, within the Sharing preferences check the box labeled Remote Login.
That’s it, at this point your SSH server is running.
Configuring SCM Repositories
After you launch Xcode, you can configure your SCM repositories by selecting SCM > Configure SCM Repositories… from the menu bar, this will open the Xcode SCM Preferences window.
Click the the plus sign ‘+’ to create your repository, it will prompt you for a name and ask you to select which SCM System you are using (Subversion in our case).
Now you need to build the URL to connect to the repository on your computer. Here you enter the Scheme, Host, Path, User and Password and have Xcode build the URL for you.
Scheme: svn+ssh
Host: either <computer name>.local or localhost
Path: the absolute path to your repository
Port: N/A
User: your login username
Password: your login password
If you entered everything correctly, you should see a green light indicator with the word Authenticated beneath the password box, click OK. If you are encountering errors, double-check that all information is entered correctly above. You can also try connecting to yourself through SSH via the Terminal: ssh username@localhost.
Configuring Projects
Before you import your projects in to Subversion, you may want to configure your project so that your build files are not located in the same directory as your project. It is normally not necessary to place these files under version control, as they can easy be regenerated by rebuilding your project.
Viewing SCM Repositories
Whenever you are ready to import into Subversion, you can add it through the Xcode SCM client by selecting SCM > Repositories from the menu bar, this will open the SCM client. If you ran my scripts from the previous post, you should see the following in each column:
Column 1: All of your configured Repositories.
Column 2: The Projects folder you specified when setting up your repository
Column 3: The Project you created
Column 4: The Subversion folders that were automatically created with the script
The horizontal window at the bottom will display the Subversion commands that are being run when you select an item from each column. This can be helpful troubleshooting tool if you are having access or permission problems.
Importing Projects
To add your project to Subversion, click the Trunk folder and then click the Import icon. This will display the directory import dialog, here you will want to select the folder of your local project and enter a meaningful comment.
Configuring Projects for SCM
Now that you’ve added your project to Subversion, you will want to configure it so you can start versioning any changes to your code. You may want to create a separate directory on your computer to store projects that are under version control. I recommend choosing a location that is separate from the directory where you initially imported from. Once you establish a location, select the Project folder under the Trunk folder and click the Checkout icon, here is where you will select the folder you created. After you click Checkout, you should receive a Checkout Complete dialog window where you are given the option to open the project. Congratulations! At this point your code should be under version control.
Part III will show you how to commit any changes that you make and will explore some of the SCM tools.
Using Subversion with Xcode, Part I
When you start learning new languages and work through different projects and problems, I find it helpful to have my code under version control (or SCM). Keeping on topic with my previous post about learning iPhone Application Development, it may be a good idea to version your code especially when working with the Stanford University projects. Currently Xcode supports three different SCM tools: CVS, Perforce and Subversion. You may choose to setup either tool, I have chosen Subversion because of its ability to integrate with a variety of development IDEs: Xcode, Visual Studio, Eclipse, NetBeans, etc.
The most detailed resource I have found on setting up Subversion within Xcode 3.1 is from the Apple Developer Connection. In this post I will keep it simple, as well as, provide shell scripts so you can avoid typing tedious commands to add new projects, branch, tag, etc.
This configuration will use svnserve, which is a lightweight Subversion server useful for individual developers, it is also installed by default on OS X. If you are looking to setup Subversion in a large development environment with multiple users, the Apple Developer Connection document will provide details for setting up Subversion with Apache.
This tutorial will cover the initial setup of configuring your Subversion repository and creating your first project via the command line.
Creating a Repository
A repository is the data store that will contain all of your projects. Because Xcode will only allow you to have one project folder at the root of the repository, I create a Projects folder that will contain all my individual projects. The following script will create your repository and a projects root folder:
# A script to create a new SVN repository
# Set this to the location where you want to store your repositories
reporoot=/Library/Subversion/Repository/
# This is the name of the projects root folder
projdir=Projects
# Create new repository
print -n "Enter new repository name:"
read repo
echo
echo Creating repository $repo
svnadmin create $reporoot/$repo
echo
echo Creating projects directory
svn mkdir -m "Directory for Projects" file://$reporoot/$repo/$projdir
echo
echo Repository Creation Complete!
echo Start adding new projects
echo
Creating a Project
The structure of a project in Subversion is setup with three sub-directories: branches, tags, and trunk. Each of these are used for the following:
Trunk
This is the location where you will import all your project files. The files contained in this folder will be the those that are checked-out and committed (checked-in).
Tags
This is the location where you will archive your releases of your project.
Branches
If you need to experiment with changes to your project and do not want to make changes to the files in the Trunk, the Branches folder is where you can store these project files.
This script will automate a lot of the work of creating the folders above. You can run this script each time that you need to add a new project to your repository.
# A script to create a new SVN project directory
# Replace this with the path of your Repository and Projects folder
reporoot=/Library/Subversion/Repository/YourRepositoryName
# Create new project
print -n "Enter new project name:"
read project
# Clean up local tmp directory
rm -rf /tmp/project
echo
echo Creating temporary directories
mkdir -p /tmp/project/$project/trunk /tmp/project/$project/branches /tmp/project/$project/tags
echo
echo Importing $project into Subversion
svn import /tmp/project/ file://$reporoot -m "Initial import"
echo
echo Cleaning up…
rm -rf /tmp/project
echo
echo "Directories Created!"
echo "Import your project through SCM in Xcode"
echo
Part II, will cover configuring Xcode to connect to add your project files to your Subversion repository.