Subversion With Mac OS X Tutorial

ubversion is a version control system that allows you to work with other people on a project and switch back easily to every version ever made. It can be used for all kinds of projects like application source code, web sites, even images or just simple text documents. Once you have it all set up and followed all the steps described below, it is easy to handle and a very useful thing – not just for computer geeks.

About This Tutorial

This tutorial explains the basics from installing subversion and getting started toworking with other people on the same project. It is written primarly for Mac OS X users, but since Subversion itself works the same on all platforms, most of this tutorial should apply to Linux or Windows users, too.

The Concept of Subversion

Subversion works by setting up a central repository on a server or local computer that every user connects to and downloads a personal working copy from. When changes are made to the working copy, they can be uploaded to the repository. If these changes conflict with changes other people may have uploaded since the last time you updated your working copy, subversion tries to merge these files and solve the conflicts.

Downloading and Installing Subversion

I recommend downloading the Subversion Mac OS X package from Collabnet

Download and run the installer. Note that Subversion itself doesn't feature a graphical user interface, so you won't find any new files in your application directory after installation. Instead it installs some command line commands into the directory/opt/subversion/bin* on your hard drive. *Note: For other Subversion packages this path is usually /usr/local/bin.

To be able to call the Subversion commands from every directory, you must add it to your path. If you don't know what that means, don't worry. Just follow the instructions.

Open the Terminal application. It can be found in the /Applications/Utilities folder. Whenever you see below a line starting with a dollar sign, you should type the text after the dollar sign in your terminal and hit return.

Start by creating a new text file called '.bash_profile', i.e. with the command line text editor pico:

$ pico .bash_profile

Add the following line to the text file:

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

Now hit Control-X, then confirm saving the file with 'y', followed by return.

You have just added Subversions's location to your path. Let Terminal read this file to know the path has changed (there's an empty space between the dots):

$ . .bash_profile

Creating a Sample Subversion Project

First we will need to set up a Subversion repository on our local computer. That is the place to store all versions of our project. Now create your repository like this:

$ svnadmin create SVNrep

This will create a repository named 'SVNrep' in your your home directory, although svnadmin won't give you any feedback. If you don't trust me on this, you can check the existence of this folder by typing 'ls' in the terminal or looking for it in the Finder.

Next we create our sample project. Create a new folder and an empty file named 'test.txt' inside this folder:

$ mkdir test
$ touch test/test.txt

Let's import this project into the repository. Type in your terminal, by replacing 'sara' with your own user name:

$ svn import test file:///Users/sara/SVNrep/test -m "Initial import"

This will output:

Adding test.txt
Committed revision 1.

We have just imported the folder 'test' into the repository 'SVNrep'. Each version in the repository is called a "revision" and is identified by a unique number. Always provide a short message ('-m') of the changes you made to the repository like we just did!

Retrieving Files From Subversion

Now we get a copy to work on from the repository. This process is called "check out":

$ svn checkout file:///Users/your_user_name/SVNrep/test test-copy

The output will show all files added ('A') to our working copy:

A test-copy/test.txt
Checked out revision 1.

Change into the working copy directory by typing:

$ cd test-copy

Next check the content of our working copy in the terminal:

$ ls -a1

This will output the directory including hidden files:

.
..
.svn
test.txt

Note the hidden directory '.svn'. This holds some subversion info like the name of the repository, so you don't have to type that in the future. If you would like a copy of your repository without this hidden directory in every folder, you have to export a copy:

$ svn export file:///Users/your_user_name/SVNrep/test test-copy

This copy is now safe to deploy on the web. It is not a working copy though, so you can't commit changes back to the repository from this folder.

Time For Changes

It is time to make some changes to our file and save it back to the repository. Open 'test.txt' from the working copy with your favourite text editor and type "Hello world" or whatever you are up to, then save the file.

You can then query Subversion to find out the differences between the repository and your copy:

$ svn status

This will state that our file has been modified ('M'):

M test.txt

Now we want to update the repository with the changes we made. This process is called "committing":

$ svn commit -m "Added some text"

This will output:

Sending test.txt
Transmitting file data .
Committed revision 2.

Dealing With All These Versions

Let's assume, that someone else working on your project made changes to the repository. You will want to update your local working copy to incorporate the changes:

$ svn update

Because in our example nobody else made changes to the repository, this will do nothing and output:

At revision 2.

To list all revisions in the repository, type:

$ svn log

This will output a list of all revisions with it's messages:

------------------------------------------------------------------------
r2 | sara | 2006-10-08 16:41:46 +0200 (Sun, 08 Oct 2006) | 1 line
Added some text
------------------------------------------------------------------------
r1 | sara | 2006-10-08 16:10:36 +0200 (Sun, 08 Oct 2006) | 1 line
Initial import
------------------------------------------------------------------------

If you would like to see the exact differing lines to a specific revision, i.e. revision 1, just type:

$ svn diff -r 1

The output states that the line "Hello world" has been added ("+"):

Index: test.txt ===================================================================
--- test.txt (revision 1)
+++ test.txt (working copy)
@@ -0,0 +1 @@
+Hello world

Maybe you would then rather like to switch back to an older revision:

$ svn update -r 1

This will update ('U') your copy back to revision 1 and output:

U test.txt
Updated to revision 1.

Note that all commands are used on the whole current working directory. You could also provide a single filename for each of these commands, i.e. 'svn update test.txt'.

Renaming, Adding And Deleting Files From The Repository

Sometimes you may add new files to your working copy.

$ touch test2.txt

They will not be included in the repository though, unless you manually add them to the repository:

$ svn add test2.txt
$ svn commit -m "added new file"

If you later would like to remove a file from the repository, type likewise:

$ svn delete test2.txt
$ svn commit -m "deleted file"

Note that you should never delete or rename files from your working copy without Subversion knowing. You can modify inside your files as much as you like. But if you just rename files or move them to another folder, Subversion will loose track of them. Always use 'svn' commands for those operations.

This is how you move a file accordingly:

$ svn move oldfilename newfilename
$ svn commit -m "moved file"

All of these commands will not only affect the repository, but your working copy as well. So you should never have to delete or rename a file with your Finder.

If you are working alone on a project, this is it! Well, basicly. The next chapter will explain dealing with multiple users.

Working With Other People

To act as if someone else was working on your project, you could now check out a second working copy named i.e. 'test-copy2' into your home directory and make some more changes to it. Then commit it to the repository following the steps from above.

Now think of a possible conflict: two people have downloaded their working copy and started working on the same file. When Sara commits her files before Michael does, Michael will get an error message when committing because his copy is not up to date any more:

$ svn commit -m "Some change by Michael"
Sending test.txt
svn: Commit failed (details follow):
svn: Out of date: '/test/test.txt' in transaction '3-1'

Michael will then first have to update his working copy by typing 'svn update'. This will merge Sara's earlier changes into Michael's working copy, line by line.

Michael can now commit the merged copy to the repository. In some rare cases however, there my be a conflict that Subversion cannot solve itself. It will then create three files in Michael's working copy:

test.txt.mine
test.txt.r2
test.txt.r3

Michael now has to manually put the pieces together in the file 'test.txt', deciding which changes to keep. Only when this is made and the three extra files are deleted, Subversion will allow Michael to commit his files.

Now go play around with it to get used to it. Of course there is more to Subversion. You could type "svn help" in the terminal to list all commands or read the freely available SVNbook at http://svnbook.red-bean.com

Graphical User Interfaces

Many people don't like working with the terminal. They find it complicated to remember the text commands, as opposed to clicking on buttons in applications. There is a couple of free or commercial apps available on the internet, that provide a graphical user interface for Subversion commands. I think it's best practice to learn Subversion from the terminal first, before you use a graphical client, to understand the way subversion works better.

A nice and free GUI for Mac OS X is svnX. To manage your working copies from the same application that you write your code with, the text editor TextMate is a good choice. TextMate includes a Subversion bundle that allows you to easily invoke most Subversion commands from the menu. Only once for setting up the repository and checking out the first working copy, you will have to use the terminal. After that, just press Shift-Control-A to open the Subversion bundle menu.

http://www.rubyrobot.org/tutorial/subversion-with-mac-os-x