Subversion is a version control system, it allows multiple people to work on the same resources simultaneously and seamlessly merges their edits wherever possible. When changes conflict it provides tools for resolving the conflict. Subversion is provided as a feature in many of the "canned hosting" environments such as SourceForge and Google Code. Alternatively, it is open source software and can be hosted on your local servers.
This page discusses the recommended layout for a subversion repository and is useful to anyone just starting a project in a subversion repository.
Subversion is very flexible in how projects are structured within the repository. However, this does not mean that you should just steam ahead and do whatever you like. People who checkout your code from the repository will expect it to be structured in a sensible, logical and familiar way. Fulfilling these expectations helps ensure that new users can get to grips with the code quickly and easily.
The remainder of this section is intended for total newcomers to subversion. It discusses the three key directories each project should have "trunk", "branches" and "tags". If you already know what these are for skip right on to the next section, "A project with a single code base".
Trunk, Branch and Tag
Trunk, branch and tag are three terms you will often here when referring to subversion repositories. With respect to repository layout they refer to three different directories. With respect to the use of subversion they refer to aspects of version management in the version control system.
Trunk is the main work area of the repository. In the trunk you will find the main copy of resources in the project. If the project were to create a release of its resources today the trunk is the copy of resources that would be used to form the release.
A branch is a copy of trunk that contains some changes not found in trunk. For example, if your repository contains the text of a project plan the trunk would contain the complete project plan whilst a branch may have a copy of the trunk but with all documents relating to budget and staff costs removed. The branch would be used to provide a version of the repository without sensitive data that can be widely distributed, whilst the trunk is used to create distributions with this sensitive data.
The trunk and branch system allows you to ensure that some changes to trunk also appear in the branch, whilst others will only appear in the branch or the trunk.
Branches are also used when a significant set of changes need to be made that may take some time and may disrupt the work of other people. For example, in a software development project a branch may be used to add a key feature that affects a large number of components. This allows the changes to be made in isolation of the trunk, thus bugs that are introduced during the development of this new feature do not affect those working on trunk. During the development of the branch updates in the trunk are periodically copied into the branch in order to ensure that the new feature can easily be merged back into trunk when complete.
A branch shares a common history with the trunk from which it emerges. This is important since it means that you can always travel back in time in order to see how the branch has developed and where that sticky little problem was introduced.
FIXME: Do a nice version of this diagram, inspired by
A tag is a "snapshot" of a project at a given point of time. Note that everything in a version control system is versioned, that is, it is possible to retrieve any single resource, or any collection of resources as they were at any given point in time. These would normally be retrieved using a revision number or a date and time stamp.
A tag simply allows you to make a given snapshot with a more friendly name. For example, "release-0.1-rc1". This prevents the need to keep separate records about when important events occurred in your project.
A project with a single code base
The Subversion team recommend that every project should have a trunk, branch and tag directory. However, this raises the question, what is a project? Is a project a collection of related modules that are developed independently of one another, or is it a single code base that is developed as a whole.
Clearly there are many different types of project. This section looks at how to structure your SVN repository for projects that consist of a single code base. If your project has multiple code bases that are related you may want to skip to the next section "A project with multiple code bases (modules)".
FIXME: describe basic SVN layout
A project with multiple code bases (modules)
FIXME: describe module focussed SVN layout