Subversion With Mac OS X Tutorial
Tags: mac os x,
subversion,
textmate,
tutorial
Posted 21. September 2006.
Subversion 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 Tuturial
This tutorial explains the basics from installing subversion and getting started to working 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:
Add the following line to the text file:
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):
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:
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:
$ touch test/test.txt
Let's import this project into the repository. Type in you terminal, by replacing 'sara' with your own user name:
This will output:
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":
The output will show all files added ('A') to our working copy:
Checked out revision 1.
Change into the working copy directory by typing:
Next check the content of our working copy in the terminal:
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:
This will state that our file has been modified ('M'):
Now we want to update the repository with the changes we made. This process is called "committing":
This will output:
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:
Because in our example nobody else made changes to the repository, this will do nothing and output:
To list all revisions in the repository, type:
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:
The output states that the line "Hello world" has been added ("+"):
--- 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:
This will update ('U') your copy back to revision 1 and output:
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.
They will not be included in the repository though, unless you manually add them to the repository:
$ svn commit -m "added new file"
If you later would like to remove a file from the repository, type likewise:
$ 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 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:
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.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.
Subscribe to this Feed
Social bookmark
