Subversion (abbreviated svn), is a collection of programs which enable multuiple programmers to conveniently work on the same project. It makes aquiring the complete sources, checking changes in to the official version, summarizing changes, and version control easy and convenient.
Subversion uses a client-server model. A Subversion server has one or more respositories, which typically can be thought of as projects in Microsoft Visual C++ terminology, though this is not an exact analogy. The Subversion respository for each program is the master copy of that program. Individual programmers can retrieve as many copies of the respository as they like and work on them locally (in Subversion terminology, you check out the respository). Once a programmer has finished making his changes, he sends his copy to the subversion server to become the current version of the repository. This is called commiting the changes.
The Subversion server will handle:
SolarTech's cvs respositories are hosted on Hepaestus (network name: solartech.chrislansdown.com).
This is probably described most easily with an example, so let's assume a very simple Subversion setup. Let's say that we have two programmers, call them Nick and Chris, and one Subversion respository, for The Program™.
Suppose that there is a bug in The Program™, and Nick and Chris are working together to fix the bug. To make sure that they're working from the production code, they each check out a fresh copy of The Program™. Through testing and reading the code, they discover that they're facing not one but two related bugs. Nick fixes the first, more complicated bug and Chris fixes the easier, less complicated bug.
At the moment, neither Nick nor Chris has a copy of the source for The Program™ which can be built and shipped to customers. This is where Subversion saves the day. When Chris is finished with the fix for the smaller bug, he checks the fix into the Subversion respository. Chris is prompted for an explanation of the change that he made, and the master copy is updated with the changes.
When Nick is finished with the update for the larger bug, he checks in his copy. Since Nick and Chris changed different portions of the code, there are no problems with the check in and Nick is prompted for an explanation of his change. (If there were conflicts that Subversion could not automatically resolve, Nick would be prompted to resolve them manually.)
Now that the cvs repository has both bug fixes, Nick checks out a fresh copy of the Subversion repository, builds The Program™ from scratch, and ships the compiled version off to the delighted customers.
If you have the pleasure of being on a Debian system, this is easy. Just apt-get install subversion subversion-tools. For those stuck on windows, read on.
You will need to download subversion. Version 1.1.4, which is the latest as of the writing of this document, is available here. To check for later versions, go to subversion.tigris.org.
Run the installer — the default options are fine, but you can customize the location etc. if you prefer. Subversion is a command line tool, so to use it you will need to launch a command shell. To do so, choose the Start menu, Run..., and enter the program "cmd". This will bring up a windows command shell.
When you check out a repository, subversion will create a directory with the name of the repository you checked out. In most cases, this will be "trunk". Generally, you'll want to rename this to something more meaningful before working with your freshly checked out copy. You can work on a given checkout indefinitely — updating and committing in a never ending cycle of up-to-dateness, or you can discard it once it's served your purposes.
You can also have as many copies of the same repository checked out as you like, so if you want to experiment with changes or just make changes you're not interested in keeping (such as littering your program with printf() statements in order to do debugging), feel free.
(The following instructions are all to be entered in a command shell. Since most people who need to read this document are stuck on windows, the examples given are for a windows command shell. Of course everything is better on unix, but it will be assumed that the reader knows where he's keeping things and can change '\' to '/'.)
To go to a directory on your C drive, type:
(If the directory that you want to go to does not have spaces in its name, you may omit the quotes.)
To check out a repository, cd to a directory where you wish to put your copy, then use the command:
This will create a directory trunk. You can rename this to anything that you like (since all svn commands are run from within this directory, it doesn't matter what you call it — for simplicity, however, this document will just refer to the repository directory as trunk). You may now go into trunk and edit, build, etc. the program. When you wish to commit your changes to the Subversion repository run the following command from within the repository directory:
If you know that someone else has committed a change that you want like in your local copy, or just because it's good programming practice to update before doing a commit, run the following command from within the repository directory:
If you wish to see what the changes you've made to your local repository are, run this command from within the repository directory:
There are a few other tidbits about using Subversion which are good to know for practical use. Also, the above presumes that you're working with the trunk. If you want to work with a branch or merge instead, you'll subsitute branch/branchname or tag/tagname for trunk; this is covered in more detail later.
In order to facilitate files used locally for development but not meant to be included in a Subversion repository (for example, compiled object files, test data files, etc), Subversion must be explicitly told when a given file is to become part of a repository or to stop being part of it. The two relevant commands are add and remove (all of the following commands are done within the repository directory).
Remember that nothing that you do takes effect in the repository until you commit it, i.e. when you're done adding or removing files, run the command:
Please note that the above also holds true for directories, so if you want to add or remove a sub-directory to a repository, you do it in the same way:
Branches and tags are both implemented in subversion by directory copying. For the time being, see the book.
The repositories on hephaestus are organized in a shallow heirarchy. The following is an explanation of the heirarchy of respositories on Hephaestus, with the bold entries being the name to use with svn commands:
This category is for all projects related to the Message Board
This category is for all of the software which runs on an arrowboard or is otherwise used to drive/use an arrowboard.
This category is for all software which is run on, or used to test, a display module.