A way to understand what Subversion (SVN) is and how it works, you should picture SVN as a storage management system. You have a storage, a repository, and clerks/clients to operate it. One of the prime features of SVN is the ability to synchronize your repository with other users.

You can either upload or change new files yourself or you can see files/changes made by other users. This is very useful when working on medium/large projects with many contributors.

These steps explains the theoretical usage of SVN

1. A repository is created
2. Users are added
3. Users add and commit files/alterations of existing files
4. Users update to see changes.

This is more or less the operational procedure of SVN. Step 3-4 are repeated as long as the project is alive. Note that adding and committing are two different operations. A typical way to use SVN is in conjunction with LaTeX.

SVN makes sure that everybody has the same versions of what is written and also lets the users work on each separate chapter/section and commit changes, without interfering others users. SVN also holds a history of repositories, or revisions as its called, which enables the user to "go back in time" to an earlier version of material if some faulty changes were made. This is indeed also a very powerful feature.

Please note that SVN is NOT a substitute for a file sharing service like DropBox. It is a version control system and is therefore NOT suited for binary data! In other words: Do not use SVN with huge graphics, movies, sound or stuff like that.

Using SVN in practice

A tricky part of SVN is the management of a repository and there are a number of ways and programs to do this, depending on the technical skill/ambition of the user. But in general it makes sense to distinguish between two ways:

• A Graphic interface.
• A Command line interface

For the average user, the graphic interface is probably the easiest way, but the experienced user may find it faster to use a command line interface. An introduction to a windows based graphical interface, using TortoiseSVN, and a more generic command line interface is presented here.

Please note that these guides are intended as a quick start and not a substitute for the full documentation, like the SVN manual.

The graphical way

An efficient and user-friendly way to access a repository is to use the program called TortoiseSVN. It is an Open Source software that on Windows integrates into Windows Explorer. This allows a user to view, alter and commit changes as, almost, any other folder on a machine.

• First download TortoiseSVN.
• Follow the on screen installation instructions.

When TortoiseSVN has been installed, it is time to check out a repository. What SVN does when checking out an repository is retrieve the current version, or revision, of the repository and save it on to the local machine. TortoiseSVN is simply a client to manage this process.

• Browse to an appropriate folder e.g.

   C:\user\<username>\documents\repositories
  

• Right click on an empty spot in Windows Explorer's "Contents" view. If the installation of Tortoise SVN was successful, a element on the pop up menu is added called "SVN Checkout". If this is not the case, try installing TortoiseSVN again.
• Click on SVN Checkout

• A box called Checkout appears. The only thing the user needs to add is the SVN address. For repositories hosted on repos.gbar.dtu.dk, the URL will look something like:

     svn://USERNAME@repos.gbar.dtu.dk/<student-id>/<repository-name>
  

  If your repository is hosted elsewhere, you have to adjust to accordingly.

• Click OK.
• Enter user credentials for the repository.

The user now has access to an exact copy of the repository and is able to view and alter existing files and add new files. The folder behaves exactly as any other folder on Windows. Simple drag and drop manoeuvres are supported. If a user for an example wants to add a file to the repository he/she needs to complete the following simple steps.

• Copy / Drag and drop a file to the checkout folder.
• Right click and choose SVN commit...
• A box is shown, be sure to check the check box of new or altered files.

• A status box is now shown, containing information about the operation. Note that the revision number is now raised one integer.
• Click OK

The new file is now added to the repository. When the other users want to see the changes made to the repository, they have to complete following steps.

• Right click on blank space in the Checkout folder.
• Chose SVN update

And that is it. The folder will be synchronized with the repository and changes are visible.

This covers the fundamentals of using SVN via the TortoiseSVN client. This enables the user to view a repository, add or alter files and commit the changes.

The command line way

Using the command line can be more efficient, especially to experienced users. This guide is based on the SVN functionality of Linux, but software like Slik SVN can add the same interface to Windows based computers.

The fundamental steps are the same as in the graphical way, the only difference is how to execute the commands. It is here assumed that a working repository has been created. To check out, or open, a repository, the user has to complete these steps.

• Open a Terminal
• Browse to an appropriate folder e.g. repositories, this is the checkout folder.

• Issue the command:

    svn checkout svn://USERNAME@repos.gbar.dtu.dk/<student-id>/<repository-name>
  

  Note the example above is using a URL for repos.gbar.dtu.dk. If your repository is hosted elsewhere, you have to adjust to accordingly.

The working directory now contains a copy of the latest revision of the repository. The terminal will display what number the revision is at currently. The folder where the repository has been saved, behaves as any folder on a Linux system, as in the graphical way. To add a file to the repository, the user basically follows the same procedure:

• Copy the desired file intro the checkout folder

• Issue the command:

    svn add <file-name>
  

  The terminal will now display a list with an 'A' followed by the name and suffix of the file. This means that this file will be added to version control in the next 'commit' command.

• Commit changes by issuing the command:

    svn commit -m <"message possibly containing spaces">
  

  or:

    svn commit
  

  The -m argument tells SVN that the string in the brackets are a log message. Subversion demands a log entry when committing, it can however, be empty. If the "-m" option is omitted, SVN will try to open an editor so you can write the commit message.

The new file has now been added to the repository and is available for other users when they update. If the other users want to see the changes, they would issue the command:

  svn update

This command updates the repository to the latest revision.