Repository Guide: Part 2: How To Use A Repository

This guide is part 2 of my repository guide series. For this post I'm going to go through a basic usage of the repository that you would use for 95% of your needs. I think most students that I teach (3rd and 4th years) will already be familiar with most of these things but I'll see if I can introduce some new stuff as well.

The general workflow for repository use is:

  1. Checkout a working copy of the repository
  2. Make changes to your files
  3. Update your copy of the repository
  4. Resolve any conflicts in your changed files
  5. Commit your changes
  6. Update again
  7. Repeat from step 2.

I think everyone knows that these are the basics that you need. (If you don't, where did you learn about version control software?) Can we improve upon this process? Sure!

Before committing changes you can compile your code (if applicable) and run the test suite for the code written. You can also run static analysis tools, like lint for C code or FindBugs for Java. Doing all this will increase the delay to getting our work into the repository so why would we want to do it? We do it because it means our repository stays as bug-free as possible. The goal is the have a repository of source files that we can check out at any time and be confident that it will compile and run without problems – so the repository must always stay clean.

Some version control systems allow you to use scripts to automate the process of running static analysis programs over your code before it can be checked in. In Subversion they are called hook scripts (specifically "pre hooks" for scripts run before repository actions) and are simple executables that live the hooks subdirectory of your main repository directory. For more information about how to write hook scripts I suggest you look at the template scripts in the afore mentioned directory and consult the "Implementing Repository Hooks" section of the Subversion book. You can use these same scripts to do other nifty things like automatically compiling PDF copies of your LaTeX documents and place them in a web-accessible directory for easy access.

You could also define a process to require that someone else inspect your files before they are checked in. The reviewers' names can then be placed in the log message. For 3rd year software engineering at my university teams consist of 4 or 5 students, so you have very few team members and thus having a process like this may be too much overhead so have a think about it before implementing it. I think code inspections should only be performed at milestones anyway, rather than every time code is checked in.

There you have it: our basic repository use upgraded to help us fight bugs, software rot, entropy and other bad-sounding things! Keep in mind that I've deliberately left this post pretty simple as more advanced actions are more … well, advanced and will may require adjusting how you think about version control – especially if you just think of it as a giant ‘undo' function.