Retrieving Files From Subversion

To get your working files of the paper draft from the repository, you need to "check out" the files:

Note that 'co' is a synonym for 'checkout.' This command generates a local directory 'your_folder' in your current default directory and fills it with the stuff from the repository. The terminal output will show all files added ('A') to our working copy:

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
blah.tex
blah.pdf

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 http://cmbpol.uchicago.edu/svn/inflation your_export_folder

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 'blah.tex' from the working copy with your favourite text editor and type "%comment" or whatever you want, 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. It is very useful to put in a comment telling people what changes you made. This process is called "committing":

This will output:

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:

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 ("+"):

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:

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:

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

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:

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 John commits his files before Tom does, Tom will get an error message when committing because his copy is not up to date any more:

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

Tom 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 Tom's working copy:

Tom 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 Tom 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 apps available on the internet, that provide a graphical user interface for Subversion commands.

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.