Subversion for Coders

Intro

Subversion, or SVN is a tool for tracking and coordinating many people working on a single project. Using subversion, we can all develop on our code, make changes that could break or fix the program, install the latest version, or roll back to a previous version with ease. Throughout this document, please understand that "PROJECT_NAME" should be replaced with the actual name of the project being worked on.

If you're interested in a more thorough coverage of this topic, please look to http://svnbook.red-bean.com/

Account setup

On our subversion server, as root, run:

 $ ./add_a_user.rb

SVN Basics

Checking out

Assuming you already have a user account on our subversion server, you need to check out a project to work on. This is the command you probably want to use:

 svn co svn+ssh://dev.freegeek.org/svn/PROJECT_NAME/trunk PROJECT_NAME/trunk

(You may need to set up ssh public key-based passwordless logins for this checkout - and future checkins - to succeed.)

Without a user account, you can check something out anonymously, but will not have the ability to later commit your changes to the central repository:

 svn co http://dev.freegeek.org/svn/PROJECT_NAME/trunk PROJECT_NAME/trunk

The only difference there was "http" instead of "svn+ssh".

Making changes

To make a change in a file... edit the file! That will change your local copy only, of course, so you will want to commit your changes into the central repository for thost changes to mean anything to the rest of the world. Best practice for this is to be very careful about what changes you're putting into the central repository. Here is an example:

 $ svn update
 edit a file
 $ svn update
 $ svn status
 $ svn diff | less
 $ svn commit

Lots of things went on there, so let's break it down.

 $ svn update

Perform this operation frequently! It synchronizes your local copy with any changes that have been committed to the central repository. Especially if you know other people might be working closely with the things you're working on, you need to do this before any significant operations. Updating is also where the dreaded conflicts will occur.

 $ svn status

This gives you a quick look at which files you have edited, in case you accidentally edited the wrong file.

 $ svn diff

This gives you a much more verbose list of the changes you've made - down to each line of each file.

 $ svn commit

This is the command that will load your changes onto the central repository. It will open up an editor, into which you should describe the changes you've made. "Added a new foo feature to lib/application" or "Removed spelling mistakes from readme.txt" or "Vandalizing and destroying everyone's hard work" - whatever you want, but try to be descriptive, referencing the filenames you've changed and how they interrelate.

If you'd like to commit changes without going into an editor, you can just type:

 $ svn commit -m "COMMENT"

Include the quotes.

File operations

Adding, removing, renaming and copying files, symlinks and directories is pretty straight-forward:

 $ svn add newfile
 $ svn mkdir newdir
 $ svn rm badfile
 $ svn copy onefile twofile
 $ svn mv oldname newname

Don't worry too much - no changes are irreversable in subversion. And don't forget to commit your changes afterwards.

New Projects

To create a new project in subversion, login to the subversion server (dev.freegeek.org) as root and do:

 $ ./setup_new_svn_project.rb

Unless you use this to migrate from an existing CVS project, this creates a project without any branch, tag or trunk directories. Those directories are, however, the recommended way to deal with branching and tagging in subversion. It is therefore recommended that you then check out the project a different way and do:

 $ svn co svn+ssh://dev.freegeek.org/var/lib/svn/PROJECT_NAME
 $ cd PROJECT_NAME
 $ svn mkdir trunk branches tags
 $ svn commit -m 'set up control directories'

From then on, you can use the normal method for checking out a project.

Trac

We have a web interface for viewing the projects and their histories:

 http://svn.freegeek.org/projects/

TODO

• conflict resolution
• branches
• tags
• finish trac

Back to Coders