svn for mac

Subversion WithMac OS X Tutorial

Tags: mac os x, subversion, textmate, tutorial
Posted 21. September 2006.

Updated: April 2011

Subversion is a version control system that allows you to work withother people on a project and switch back easily to every versionever made. It can be used for all kinds of projects likeapplication source code, web sites, even images or just simple textdocuments. Once you have it all set up and followed all the stepsdescribed below, it is easy to handle and a very useful thing – notjust for computer geeks.

About This Tutorial

Thistutorial explains the basics from installingsubversion and gettingstarted toworking with otherpeople on the same project. It is writtenprimarly for Mac OS X users, but since Subversion itself works thesame on all platforms, most of this tutorial should apply to Linuxor Windows users, too.

The Concept of Subversion

Subversion works by setting up a central repository on a server orlocal computer that every user connects to and downloads a personalworking copy from. When changes are made to the working copy, theycan be uploaded to the repository. If these changes conflict withchanges other people may have uploaded since the last time youupdated your working copy, subversion tries to merge these filesand solve the conflicts.

Downloading and Installing Subversion

I recommend downloading the Subversion Mac OS X packagefrom Collabnet

Download and run the installer. Note that Subversion itself doesn'tfeature a graphical user interface, so you won't find any new filesin your application directory after installation. Instead itinstalls some command line commands into thedirectory/opt/subversion/bin* onyour hard drive. *Note: For otherSubversion 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 linestarting with a dollar sign, you should type the text after thedollar sign in your terminal and hit return.

Start by creating a new text file called '.bash_profile', i.e. withthe 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', followedby return.

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

$ . .bash_profile

Creating a Sample Subversion Project

First we will need to set up a Subversion repository on our localcomputer. 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 homedirectory, although svnadmin won't give you any feedback. If youdon't trust me on this, you can check the existence of this folderby typing 'ls' in the terminal or looking for it in the Finder.

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

$ mkdir test
$ touch test/test.txt

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

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

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" andis identified by a unique number. Always provide a short message('-m') of the changes you made to the repository like we justdid!

Retrieving Files From Subversion

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

$ svn checkout file:///Users/your_user_name/SVNrep/testtest-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:

....svntest.txt

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

$ 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 workingcopy though, so you can't commit changes back to the repositoryfrom this folder.

Time For Changes

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

You can then query Subversion to find out the differences betweenthe 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. Thisprocess 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 madechanges to the repository. You will want to update your localworking 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) | 1line
Added some text
------------------------------------------------------------------------
r1 | sara | 2006-10-08 16:10:36 +0200 (Sun, 08 Oct 2006) | 1line
Initial import
------------------------------------------------------------------------

If you would like to see the exact differing lines to a specificrevision, 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 olderrevision:

$ 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 workingdirectory. You could also provide a single filename for each ofthese 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 youmanually 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, typelikewise:

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

Note that you should never delete or rename files from your workingcopy without Subversion knowing. You can modify inside your filesas much as you like. But if you just rename files or move them toanother 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 yourworking copy as well. So you should never have to delete or renamea 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 couldnow check out a second working copy named i.e. 'test-copy2' intoyour home directory and make some more changes to it. Then commitit to the repository following the steps from above.

Now think of a possible conflict: two people have downloaded theirworking copy and started working on the same file. When Saracommits her files before Michael does, Michael will get an errormessage when committing because his copy is not up to date anymore:

$ 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'sworking copy, line by line.

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

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 madeand the three extra files are deleted, Subversion will allowMichael to commit his files.

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

Graphical User Interfaces

Many people don't like working with the terminal. They find itcomplicated to remember the text commands, as opposed to clickingon buttons in applications. There is a couple of free or commercialapps available on the internet, that provide a graphical userinterface for Subversion commands. I think it's best practice tolearn Subversion from the terminal first, before you use agraphical client, to understand the way subversion worksbetter.

A nice and free GUI for Mac OS X is svnX. To manage your workingcopies from the same application that you write your code with, thetext editor TextMate is agood choice. TextMate includes a Subversion bundle that allows youto easily invoke most Subversion commands from the menu. Only oncefor setting up the repository and checking out the first workingcopy, you will have to use the terminal. After that, just pressShift-Control-A to open the Subversion bundle menu.