What is SVN?

SVN (Subversion) is the commonly-adopted, efficient tool that allows a group of people to work on a common project. Most relevant examples are

  • software developing
  • paper / books writing and editing
  • research

SVN allows the group to have a common repository for their work and to keep their working copy (on their computer) up to date with what the other co-workers are doing. This sort of synchronization works in both ways: you are assured that your copy is the most recent one any time you update your copy and at the same time you decide to provide your modifications to the group as soon as you complete them.

More advanced features include

  • conflict management
  • branching and versioning
  • publication of your work in internet (to a wider audience)
  • backup and restoring

The main parts of this system are

  • an SVN server
  • a repository
  • an SVN client for each member of the group

Repository setup

The first step consist in setting up an SVN server, which is not covered in this minimal guide. The second step is to create a repository for your shared project, that is a basic layout of the tree that will contain your shared files. Again, this is not covered here, at least for now.

Basic commands

What is described in this page is how to use your SVN client, that is how to cooperate correctly in your working group. Even if every SVN client has its own commands (command line or via a GUI), their names will almost always be the same. Therefore I'm presenting here some basic command line commands (that you can directly use for example in Linux, Mac, and other UNIX based systems), while you won't have any problem in looking for the same commands in you graphical SVN client.

svn checkout http://mysvnserver/myrepository

This command just creates on your local hard disk the exact same copy of the whole project in the repository. After this command you will have a complete and up-to-date copy, and you can start working on it.

You only have to do this step once, when you set up the whole thing. Then there are other commands to keep your copy updated and to commit your changes.

Just a couple of options that can be useful if authentication is required on the server

  --username USER

to specify your username USER on the server

  --password PASS

to specify your password PASS on the server (otherwise they are required in an interactive mode).

  --no-auth-cache

if you don't want your computer to store your authentication details.

svn update

Bring changes from the repository into the working copy.

svn commit

Send changes from your working copy to the repository. A log message is required and strongly recommended to be as detailed as possible. You can include it with the option

  --message 'MY LOG MESSAGE'

otherwise it will be required to you in an interactive way.

Usage examples

Here I describe the easiest, typical use of SVN. Just consider a couple of users working on the same project. They just checked out the repository, so they have their own working copy. It's a tree, with folders, text files and binary files.

Modifying your working copy

They start working on these files. Each of them modify some files, add some others, deletes an image and so on. To modify a file, they just have to edit their local copy with the editors they prefer. To change something in the file tree they instead have to use the commands

svn {add, delete, copy, move, mkdir} [options]

Now the idea is that they get to a point in which they thing it's time to share with the rest of the group what they've done. First of all, it's a good idea to take a look to your own modifications, running

svn status

to see which file have been added (A), deleted (D), modified (M), etc. And running

svn diff

to look at the modifications in details.

Sending your changes

Once you're sure of what you've done, you decide to share your working copy, sending it to the server with the command 

svn commit

Resolving conflicts 

When commiting, you can get an error message about your copy being out-of-date. This means that another user was working on the same files, and he or she already committed his / her changes! You then have to FIRST download the new version, then SEND yours. 

To update your working copy to the last revision on the server, just run

svn update

You will see that some files are updated (U), some merged (M), and some files conflict. Updated means that another user modify the file, but you didn't, so your working copy is just updated. Merged means that, for text files, another user modify some lines, but you modified others, so svn can merge the two versions automatically. Conflict means that you modified the same lines, so you have to solve this conflict.

When a conflict occurs, three files are created. Suppose filename is the conflicting file. A file names

filename.mine 

will be simply a copy of your working copy right before you run update.

filename.rOLDVER

will be a copy of the file as it was before you started editing it, when you updated it the last time. That is, the file on which you worked.

filename.rNEWVER

is the last version of the file on the server, and is of course conflicting with your working copy filename.mine.

Your file filename, instead, will be modified with some marker lines to help you solve the conflict. You can then scroll the file, solve the conflicts, and then run

svn resolved filename

followed by

svn commit

Of course you can also decide to ignore your changes, just copying filename.rNEWVER over filename, or ignore the other user's changes, copying filename.mine over filename. You still will have to run svn resolved filename.

These are the main commands. Your working cycle will then consist in a series of updates and commits, hopefully with few conflicts. :-) 

SVN Clients

Here is a short list of available SVN clients for different operating systems. In order I would prefer open source ones over freeware ones over commercial ones, but this is up to you. In the following ads box you can also probably found some good links.

Linux

Type

svn --version

on your Linux machine and you will find out that you (almost surely) have an SVN command line client on your PC. Otherwise any distribution has at least an SVN command line client in its repositories, just look for it.

In instead you're looking for an SVN client with a graphical user interface, try these ones:

(I'll add more soon)

Mac

As with Linux, you already have svn as a command line client.

Some graphical clients are

Windows

The best SVN client for Windows is TortoiseSVN, free and efficient. It completely integrates with your Windows file explorer and you can do everything with a right-click.

Other choices are