Subversion Best Practices: Repository Structure

Maintaining a Subversion repository can become a complex task, and implementing the right project layout from the very beginning is crucial. As Subversion doesn’t impose a strict file structure, users are free to tailor Subversion repositories to their project’s needs. Users can organize Subversion on a ‘one project per repository’ basis or create multiple projects within the same repository; and have considerable freedom when it comes to how they use Subversion’s trunk and branches. In this post, we’ll look at some guidelines and best practices on how to keep Subversion files, for users who are embarking on a new project in Subversion.

Multiple Projects: Single Repository vs. Multiple Repositories

In modern software development, it’s normal for teams to be working on multiple projects simultaneously. If this sounds like your organization, the first question you’ll need to answer is: should I set up a single repository for multiple projects, or create one repository per project? Although the experience will be slightly different for each project, there are some general benefits and drawbacks to each approach.

Single Repository

Single repositories are typically suited to organizations managing multiple, small projects that require cross references, cross tracking, etc.

Positives:

  • there is a single location where all the code is stored, even for projects you aren’t directly involved in.
  • ability to reuse common libraries.
  • lack of duplicated maintenance (e.g only one repository needs to be backed up.)
  • the ability to move data between projects more easily, and without losing any versioning information.
  • all projects share the same repository history.
  • typically less administration – new projects can be created without creating a new repository, and without the help of sysadmin.
  • you can delete entire projects without losing the record from Subversion.

Negatives:

  • Subversion uses repository-global revision numbers which apply to entire trees, not to individual files. The revision number for projects will increase in accordance with the rest of the repository, even if no changes have been made to that particular project.
  • unable to use unified logging (svn log command).
  • branching can be complex when many folders and files are involved.
  • dumping/loading one huge repository can be time-consuming.

Multiple repositories

These are typically suited to multiple large unrelated projects.

Positives

  • the ability to define different access permissions, for different users.
  • each project repository will have its own revision sequence.
  • the version number is meaningful for all projects.
  • projects have a tendency to increase in size, and numerous large projects on a single repository can become difficult to maintain. It is typically easier to manage large projects with a ‘one repository per project’ approach.
  • can tailor each repository’s structure to suit a project’s unique needs. This can include branching, tagging, naming conventions, etc.

Negatives:

  • Subversion does not support merging code between projects in different repositories, and the transplanted code will appear in the new repository with no history. This also means you cannot perform merges if you need to temporarily maintain two versions of related code.
  • different projects have different mailing lists, which can be a problem if there’s cross-over between two related, but separate, projects.

There is also the potential to have more than one repository, and to group related projects within the same repository. This allows related projects to share data, and when new revisions are added to a repository, they are more likely to be relevant to everyone who uses the repository.

Project Layout

Once you’ve decided whether to organize your projects in a single or multiple repository structure, it’s time to plan your project layout. Putting some thought into your layout in the beginning, can help you avoid having to move files around later.


An illustration of how a Subversion Repository evolves using branching, tagging and a code trunk.

Here are some best practices for getting the most out of your project layout:

  • Project root – This is the anchoring point for a project. A repository may contain one project root, or multiple roots, but each project root contains three subdirectories: /trunk, /branches, and /tags. The use of a project root is officially recommended by the Apache Subversion project.
  • Trunk - This is where you should store current release code – only! Don’t muddy the trunk directory with revisions or release names.
  • Branches – Use these to work on significant changes, variations of code etc, without disrupting the current release code.
  • Bug fixing on a branch – Branches should be created to fix major bugs; this allows bug changes to be immediately worked on without disrupting whatever work is currently underway in the trunk/development branches.
  • “Toe in the water” branches – Branches can be used as a code “sandbox” where new technology can be tested without risking the working code. If things go right, the new code can always be merged back into the trunk.
  • Tags – Should be used as “code milestones” providing a snapshot of the code at specific points in its history.
  • Tagging bug fix / development branches – when creating a code or bug fix branch, it’s useful to create a “pre” tag, and a “post” tag after the bug fix or code change has been completed:

http://10.2.5.2:9880/encom/tags/PRE_authchange_bug9343

http://10.2.5.2:9880/encom/tags/POST_authchange_bug9343


Ready to start a new project with Apache Subversion? Certified open source Apache Subversion binaries can be downloaded from the WANdisco website.

5 Responses to “Subversion Best Practices: Repository Structure”


  • In my company we use three big repositories and the big size and maintenance points are spot on.

    Yet, I differ in two smaller points:
    - Revision numbers have become completely irrelevant for us. Using the proper tools (in our case, mainly, TortoiseSVN, Netbeans and sventon) we use dates, comments and diffs to find previous versions and nobody even flinches about numbers not being consecutive in a particular project.
    - SVN through apache allows to set permissions to users in particular paths in one repository.

  • “the ability to define different access permissions, for different users.”

    You can still do this with one repo though… you can define per folder access permissions.

    Here is an example:

    http://www.thinkplexx.com/learn/howto/svn/advanced/enabling-per-directory-permissions-in-subversion-with-apache-svn-access-file-ldap-tutorial#highlighter_828646

  • Hi

    in the case of cloud based subversion it may be more attractive to have fewer repositories in order to keep the costs down. Each repository may have more than one .NET solution dir structure. Is there anyway to apply separate versioning to each dir structure; with each held under the branch structure?

  • Hi Daniel,

    Thanks for your comment! With Apache Subversion, it’s not possible to have branches with different revision numbers in the same repository. Whenever you perform a commit, the revision number will increase across all of your repository’s files and folders, regardless of whether they’ve actually changed. If revision numbers changing based on other branches is a problem, you should create separate repositories.

  • Hi all,

    There a small note that point about ‘dumping/loading one huge repository can be time-consuming’ on single repository holding can be easily dealt with by using multiple project roots within the repo and checking out only required project.

Leave a Reply