Subversion Guide

Getting started with Subversion

Subversion (SVN) is a Version Control System. It's a way to keep track of changes in a file tree structure, which are maintained in a central 'repository' and downloaded locally by each developer to work on.

The two main features are:

• It remembers the history of all changes done to the project, so it's very easy to simply roll back to a previous version if incorrect code is later found or if the current development line is found to be a deadend.
• It lets several developers work on the same project without them stepping on each other's toes. For instance, if two developers change the same file and try to upload it, Subversion will try to merge them into a single file, containing both developers' changes. If this can't be done cleanly, it will diligently raise a conflict and wait for the developers to give it a solution.

With SVN, it's actually very difficult for a developer to harm the project in a permanent way.

So how do I use SVN to work on the project?

You need a couple things before getting started.

First, you need to have the SVN Client installed in your computer. Just type 'svn --version' in your terminal, and you should get info about your currently installed SVN client. If you don't have it (unlikely in most Linux distros), you can get it through your *nix package manager, or find a suitable package here: http://subversion.apache.org/packages.html

Second, you'll need to know the project repository's URL. For StarChronicles, which is hosted on SourceForge, the repository's URL is:

https://starchronicles.svn.sourceforge.net/svnroot/starchronicles

The root of the repository is, as the name suggests, at svnroot/, but by convention we'll put all our files in svnroot/starchronicles, so the above URL is the one you should use.

Also, if you want to upload changes to the project, you'll need developer access (your sourceforge login, if you're enabled as a developer). The project admins can add users to the developer list. One cool thing is that you don't need special permission to download the project svn tree. This is free for all to see and download.

Ok, I got all these things, how do I get started already?

Checkout the project

This is the most basic SVN operation. Checking out means you download a local copy of the project. Since it's done through SVN (rather than making a regular copy), all changes done to these files on your computer will be recorded. The command to checkout the project (or just part of it) is:

svn checkout <URL to project directory> <local destination directory>

The first field is the URL to the project directory you want to checkout. All files and subdirectories (i.e., the whole file tree structure rooted at this directory) will be checked out.

The second field is the local name you want for the copy of the project directory you're checking out. If omitted, it will simply use the same name.

Once you run the command, you'll get a "Checked out revision X" message. In SVN, every time the project is changed, even if only correcting a typo in a single file, the project's revision number is increased by one. When you check out the project, by default you'll get the latest revision. One cool feature of SVN is that you can always checkout any past revision of the project. It accomplishes this by keeping track of all the changes that have been done (but it doesn't keep a copy of all revisions of the project! - only the changes). In SVN lingo, we refer to the Nth revision as 'rN' (for example, revision #187 is called 'r187').

For the StarChronicles project, an example of the checkout command could be:

svn checkout https://starchronicles.svn.sourceforge.net/svnroot/starchronicles StarChronicles

This checks out the whole project to the local directory StarChronicles. Your local copy of the project is called, in SVN lingo, your "working copy".

So what does this do? It copies all the files to your local directory, but it also adds a hidden .svn dir to the main local directory and every subdirectory. This is where SVN keeps track of all the project changes. Without this .svn dir, your local copy is just a set of regular files, with no version control system, and SVN will not work on these (you will get a "not under version control" error if you try to upload them to the project).

Working on your local copy

At this point you work on your local copy, introducing changes to one or more source files. Subversion always knows which files have been modified. At any point, you can have SVN give you the status of modifications by issuing the command

svn status

This will list all local source files that have changed relative to the last time you checked out the files. Not that this command will not contact the repository, so you won't know if any files have changed in the repository since the last time you checked them out. If you do want SVN to check against possible updates on the repository, simply issue the command

svn status -u

Also, if you want to update your working copy to the most up-to-date version in the repository, issue the command

svn update

This will download all files that have a newer version available on the repository. Note that if you have locally modified any file that has been updated, SVN will try to merge the two files. If it doesn't know how to do this non-destructively, SVN will say so.

Adding to or removing files from the project

Because SVN must keep track of every file in the project, it's not enough to simply shell copy or remove a file into your working copy. If you want to add a new file or directory, copy it to your project working copy, and then use the SVN add command to tell SVN to keep track of this new file/dir too. The command is:

svn add <target file or directory>

Note that SVN will automatically recurse to all files and subdirectories if the target is a directory. You will get a list of confirmations for each file that was added to the project. They will be uploaded on your next commit.

Similarly, deleting files/dirs must be done through a SVN command:

svn remove <target file or directory>

Commit your changes

After working on the files, once you're ready to call it a day, or simply think you've done an important change, you'll want to commit your changes. That's the other basic SVN operation. Navigate to your working copy's root directory, and use the following command:

svn commit

In its simplest form, it does not need any arguments. SVN will read the .svn dir, which contains details of the whole file structure and all the changes that have been made. It will then upload those that have changed (and only those) to the project's repository, and increase the project's revision by one.

Before uploading, however, SVN commit will ask you to type a "commit message". It will launch your default text editor (vim in my case) and ask you to type a message, indicating what changes you've made in this commit or anything you think the other developers should know about this revision. Once you're done typing the message, save and close the text editor, and SVN will commit your changes. It's important to save the file before exiting the editor: if it's not saved, SVN will abort the commit operation.

A useful aspect of SVN is that it does atomic commits: the project's repository will only be updated if ALL the changes in your commit are received; in any other instance, the commit will fail. This prevents potentially corrupting the project if something happens to your internet connection during the commit phase.

That's pretty much all there is to know to start working on the project using SVN. All SVN commands have a decent help file, so be sure to check it if you forget something. Simply type 'svn --help'.