This post is about folder structures and project management in Subversion.. If you don’t already know what Subversion is check out the previous post: http://blog.akademy.co.uk-tips/2009/09/source-control-beginning-with-subversion/
Folder Structure
The folder structure you implement in your repository can have significant impacts on how well your project gets managed, now and in the future. With the right forethought you can implement things like:
- release version tagging,
- multiple simultaneous version releases
- and have code, installers and build systems all in the same place.
Tags – release version tagging
Tagging is the term used to “mark” a certain version of your files as important in some way. Most often this will be to mark public releases of your code, this enables you to go back to that specific version even after other changes and version releases have taken place. In Subversion there is no specific tagging mechanism, instead you simply take a copy of the code as it is at the moment. Now this sounds like it would use a whole lot of memory space but you need to remember that Subversion only ever records the changes between files – a tag will not not have any changes in so is virtually copied for free.
To keep track of all your tags you’ll need somewhere to put them and in subversion this means a folder. So in the top level repository folder have a folder called “Tags”. Lets assume you have another folder called “Main” for now which contains your source, to create a tag you’d just copy it, so type something like:
svn copy file://your-path/TestProj/Main file://your-path/TestProj/tags/release-1.0 --message "1.0"
Branches – multiple simultaneous version releases
To work on multiple versions you’ll need to once again copy the main source code. You might need to work on two different releases if you have two major changes to the code which you want to test separately, or you need to make bug fixes in an old release but don’t want to mix up the new code, or you just want to try an idea but don’t want to mess with the main source.
You’ll need to keep this code separate also so create another folder at the top level of your repository. We’ll call this one “Branches” as you are copying the main code to subsequently change it – it branches away from the main part. Now You’ll just need to copy the main code, so type:
svn copy file://your-path/TestProj/Main file://your-path/TestProj/branches/newtest --message "fixing"
This command is near identical to the tag one. This is because all you are “really” doing is making a folder and copying some files to it.
Main (or Trunk) – code, installers and building
When you read up on subversion you’ll come across the folder “Trunk”. Once again, this is subversion so it’s just a folder, and it’s where you main source is edited from. (It’s called “Trunk”, because it’s where the “Branches” come from!). The above paragraphs have called in “Main”.
I tend to split my main folder into several others to make the full building of a program easier. Typically this will be something like “Source”, “Installers” and “Builder” – “Source” holds things like c++ files, “Installer” will hold the files needed to create an installer, and “Builder” is the files needed to automatically build all the bits into some kind of release, such as a CD; (you might like to add “Content” or “Manuals” or something else to your own). This is very useful when you need to tag something as everything needed to rebuild a specific release will be copied into that tag.
Trunk, Branches, Tags or anything.
Obviously the folders you’ll need will depend on your own project. Don’t be afraid to experiment with your own names and structures – the folders are yours to play with!
A few caveats on changing from “Trunk”, “Branches” and “Tags”
- Some client programs can automatically create tags and branches if you stick to these folder names.
- Much of the documentation will make reference to these folder names.
Multiple projects
Up until now I have assumed a single Project in your repository but that’s not the only way to do it. There’s two main ways to store multiple projects in Subversion, each with positives and negatives.
- Create multiple repositories, one for each project.
- Create a single repository with a top level folder for each project.
Multiple repositories, single projects
This is the simplest to manage. Every new project his it’s own repository and is entirely separate from any others.
Positives:
- You can reduce the impact from a single hardware failure as repositories can be kept on separate hard drives.
- You can backup each project separately, depending on it’s value.
- You can easily give user access to a single project
- User subversion errors limited to a single project.
Negatives
- Users will need to be created separately for each repository.
- The merging of projects is very difficult.
Single repository, multiple projects
A single repository, with top level folders for each project. Each sub folder has the usual “Trunk”, “Tags” and “Branches” in.
Positives
- A single list of users is all that is needed.
- A single, simple, backup procedure.
- Merging of several projects into one is very easy.
Negatives
- Can mistakenly give access to a user for any project.
- Single hardware failure can wipe out all projects at once. Single backups also at risk.
- A subversion user error in one project can impact all other projects.
Conclusion
There is no right and wrong way to store your folders. It really depends on your use, for instance I use subversion to back up my fiction writing, and it contains no folders just a list of files.
There are some best practices you should consider though, decide how you’ll make taqgs or branches if you’ll need them, and if you are going to use multiple or single project repositories.
However, if you are looking for a quick set up, I’d recommend having a single repository for a project, then a sub folder structure of “Trunk”, “Branches” and “Tags”. In side that Trunk create a folder for each of the different parts you’ll need, although different parts can be added later.
That concludes this blog. A future blog will include subversion clients amongst other things.