Subversion: Sorting Out Your Module Structure

written by Geoff Bowers on Friday, 7 September, 2007 @ 04:04 PM

It’s important to understand that Subversion is a system that records and manages file changes. It’s not a prescribed methodology for managing those files. So while Subversion provides the nuts and bolts for your version control system, you need to agree within your own team how you want to manage your code base. This can be a little overwhelming given the sophistication of Subversion and the multitude of strategies for code management it allows.

The repository or “repo” is the root level of your versioning installation. You can have many repositories, and in turn each repository can hold many different code bases. Where you might apply some sort of global setting to your implementation, this is the level it starts at. You may find yourself running several different repositories or one — it just depends.

For example, we typically run a separate repository for each significant client. This allows us to store all the code bases for a specific client together, apply security settings that are relevant to just that client and so on. If the client ever wanted the entire version history backed up, or moved, having a separate repo makes the whole process cleaner.

For example, we maintain and co-ordinate development on the open source, FarCry Core Framework for ColdFusion. Having a separate repository allows us to more easily manage the open and accessible nature of the code base without endangering the security of our private client information.

The truth is we could run all of these code bases in a single repository, it all boils down to what works for you. Generally speaking, if all the code logically fits together, is part of the same overall infrastructure you are managing, and belongs to a single stake-holder, such as your company, you probably want to stick to a single repository.

The module is typically a discrete code base that represents either a shared library of code, or a specific project that you are working on.

For example, a shared code library might represent a framework or tag library you have developed for building websites and a specific project might be a website that leverages these libraries.

It’s most practical to think of a module as a project in your IDE of choice. Although you might include external libraries within your project, the module should really contain all the bits and bobs you are working with that pertain specifically to that project. At Daemon we think of this as “everything below the application root”. Another developer should be able to deploy this module into their own working environment from this single module. Any shared libraries would be deployed separately from different modules. But we’ll talk more about this later.

Day to day you will not be working with the module root itself. The module will encompasses several different versions of your project and so your actual working code base will sit somewhere underneath the module folder. The specific code base will depend on the stage of development you are at and the strategy for code management you are employing for this project.

The module itself can assume any structure at all within Subversion. Here we’re recommending a slight variation on the most common approach to managing your code.

Subversion: Module Structure

Under every module you should create the following folders:

  • trunk
  • tags
  • branches
  • skunkworks

Common practice in the community at large is to use trunk, tags and branches. We’re advocating the addition of another folder, “skunkworks”. We find this comes in handy for managing more complex scenarios. But first lets discuss what on earth the different folders are for.


trunk is the “main line” of development. If you think of a tree, this is the woody bit that all the branches spring from. Everything else that happens in the module is really all about managing the code in the trunk.

All development leading to the next version of your code base will eventually end up here at some point. It’s really the key folder of any module.


tags will contain “read only” snap shots of your code base. You’ll want to create these from time to time as milestones of your development work in the trunk. If you are exporting your code base to give to someone, or deploying to production servers, you should nearly always be doing this from a “tag”.

So the tags folder is over time going to accumulate a bunch of folders representing the entire trunk at different points in time. When you first create a module, this folder will always be empty.


branches is a folder that will contain variations of the trunk. You’ll want to create these from time to time depending on the strategy for code management you are using.

So the branches folder over time is going to accumulate a bunch of folders representing variations of the entire trunk. When you first create a module, this folder will always be empty.


skunkworks is a Daemon’ism. We use it in a very similar way to the branches folder. It contains variations of the entire trunk.

You could certainly stick these trunk variations into the branches folder. However, in an effort to keep everything neat and tidy, we like to reserve the branches folder for specific code management tasks like maintenance and quality assurance. Skunkworks is set aside for the more experimental and crazy development efforts you might have from time to time.


Related Blog Posts