SVN mini tutorial

Intro

This is a quick intro on how to use subversion, it’s not intended to be a complete tutorial of subversion or even a proper introduction to subversion. It’s intended for those who want to learn the most important commands in order to be able to do some work. Note that I sometime ‘lie’ or ‘simplify’ things, if you want all the details you should look at some other document. You could for example look at one of the tutorials you can find using Google or why not read the subversion book. Subversion is a version control or revision control system, my explaination can be found here, intended to be used by one or more people at one or more locations. This means that it’s possible

• for one user to work on a project at different computers and be sure that the files are up to date.
• for several users to work together on a project being sure changes that made by others are not overwritten accidently.
• for several users to work together and be sure that all files are up to date.
• to “go back in time” and check how an earlier version of one ormore files looked like

There are of course other reasons to use a system like subversion but these are my main reasons. Anyway, subversion works on many different types of computers, for example Mac, Linux, Unix, and Windows. The subversion system itself doesn’t include a graphical user interface, you can download various programs that gives you a graphical user interface, for example “iSVN” for Mac and “Tortoise” for Windows. I will however not discuss those, instead I will use the standard command line interface. I will also assume that you’re not interested in various details of subversion (see the subversion book) and have no desire to setup a server, you just want to use it.

The first step

Let us assume that you want to work on the project “BigProject” and the administrator of that project has set up the subversion repository (the place where the subversion server stores all the data) and sent you three pieces of information: your username for the repository, the password and the URL to the repository, for this example we assume they are

What you need to do now is to checkout a working copy of the project. You do this by issuing the command:

Your computer will now fetch a copy of the project from the server and store it on you computer (this copy is called the working copy and the operation of fetching it checkout). If you look at the files on your computer you should have a folder named “trunk” (you can rename it if you want to something more meaningful). In this folder you will find all files that belongs to the project and you can now start working with them. Note that this “checkout” is often only done once for each project/person/computer.

Basic workflow

When you have checked out a working copy you normally go through a cycle of steps while working with the files:

1. Update – get the changes that others have made (or the ones you have made on another machine).
2. Edit – you make changes to the files
3. Commit – you send your changes to the server.

Let’s take a closer look at these three steps.

Update

Changes that others have made are not sent automatically to your computer, instead you need to fetch the changes from the server and update the files in your working copy. This means that files can be added, deleted or changed during the update process depending on what others have done. My advice would be to update your working copy before starting to edit the files so that you have the latest changes. To update your working copy you issue the command svn update assuming your “working directory” is the folder where your working copy is. In other words if you have the following directory structure:

where ‘BigProject’ is your working copy of the project (assuming you have renamed “trunk” to “BigProject”), then you need to move to the “BigProject” folder (for example by using cd SomeFolderA/BigProject). By moving into the “Documentation” folder before issuing the update command you will only update the files in that folder. While subversion is doing the update it will display some info on what files it updates/deletes/adds and normally there is nothing else you have to do. However, on occasion there is a conflict which you need to handle, see below for details.

Edit the files

You can edit the files with whatever program you want, subversion doesn’t care.

Commiting the changes

When you have edited the files it’s time to send the changes to the server so others can see what you have done. You do like this:

The text can be anything you want but it’s best to add some useful comment so that you and your co-workers know what was changed. Normally subversion prints out some info about what it has been doing at that’s it (OK, you can get conflicts here also … see below). That’s it … well, there are some additional things you would like to do, like adding files, deleting files, finding what files you haven’t added to the project, etc, so let’s take a look some other useful commands.

Some other commands

Adding files

You can of course add a file to the project. Just create a file and place it in the desired location within your working copy, then you type

So if you’re currently in the “BigProject” folder and add the file “Acknowledgements.tex” to the documentation folder you give the following command to add it to the project:

Note that this does not send the file to the server, in order to do that you have to commit your changes (see above). Note that you can add several files at the same time.

Deleting files

If you want to delete a file from a project you should let subversion do it, you should also be aware that the file will be deleted from the current version of the project but it will still be around in the repository on the server. So if you decide that you have deleted the file in error you can get it back by checking out an earlier version of the project. Well, to delete a file you give the command

so if you want to delete the file you added above you type

Note that this does not tell the server to delete the file from the current version, in order to do that you have to commit your changes (see above). Note that you can delete several files at the same time.

What files have been modified by you?

Sometimes it can be difficult to remember what files you have created but not added to the project, or if you have made some any changes to some files since the last commit. You can easily check this using the “status” command:

Here is an example of how it can look:

In the first line I use the ls command to see what files that are available in this folder, as you can see there are five files. I then issue the status command and subversion replies with three lines. The ‘?’ mean that this file is not a part of the project and the ‘M’ that my copy of ph_intro.tex have been changed. I could now add the files ph_intro.log and ph_intro.aux by using the ‘add’ command but since these are “temporary” files created by LaTeX I don’t bother to add them (not every file used in a project need to be known by subversion) but I should commit the changes that I have done in the ph_intro.tex file so others can see them.

What have people done?

If you want to see what changes that have been done to a file you can use the log command:

or

here is an example:

Here you can see that ph_intro.tex is currently at revision 5, the last change was by “jem” with the comment “Added Lyndas text”. You can also see when the change was done. Revision 4 was committed by Mark about four days earlier when he added some sentences about categorization.

What if subversion says something is wrong?

Sometimes subversion complains that something is wrong with your local copy, if you run into some kind of problem you should probably talk to someone that is working with you and know subversion well (or you could look in the subversion book). However, there is one command you could try before asking someone for help

This removes some temporary files, etc, and can sometimes make subversion happy again.

Conflicts

So what happens if two persons make changes to the same file at the same time? Well, usually nothing. Subversion see that you both have made some changes and take those changes and merge them into a new version of the document. An example, below is a short text file:

This file has been committed to the server by user A. User B updates his/her working copy so that the file exists there. B looks at the file and see that A haven’t spelled subversion correctly. B fixes the spelling error and commits the file. User A have at the same time added some more text at the end of the file and A have also committed the changes. In other words, A is sending the following text to the server:

while B sends the following text:

Both of these texts comes from the same version of the file so which one should subversion save? The answer is “none of them”, instead subversion see that the changes does not overlap each other. This mean that subversion can merge these changes into one new version:

This is what usually happens, you don’t need to do anything to make sure that document contains the latest changes. So what subversion do if the changes overlap each other? The answer is once again really simple: subversion does nothing, it hands over the responsibility to resolve the conflict to the person who made the last commit operation (if B committed the changes 1 second after A, B is responsible to fix the conflict). But since this never have happened to me (except for when I forced this to happen) I’m not going to explain how to handle it (you can find instructions here)