Subversion Repository Layout

I see a lot of questions asked about “What is the recommended repository layout?”, “What does trunk mean?”, or: “What is the significance of trunk?”. This post will try to answer those questions and more.

A Subversion repository implements the metaphor of a versioned filesystem. The repository is just a filesystem with folders and files. It so happens that modifications to this filesystem are versioned and there are implementation enhancements like “cheap” copies that make certain operations less expensive than they are in a traditional filesystem, but the repository itself still behaves like a filesystem: there are no special folders or names and Subversion itself has no knowledge of trunk or branches, they are just folders within the filesystem. It is up to you as the user to give those folders names and structure that are meaningful to you.

That said, there are several common layouts that have been adopted by the community as best practices and therefore one could think of these as recommendations. If your repository is accessible to the public, following these conventions might make it easier for users that have accessed other Subversion repositories to find what they are looking for.

There are two commonly used layouts:

trunk
branches
tags

This first layout is the best option for a repository that contains a single project or a set of projects that are tightly related to each other. This layout is useful because it is simple to branch or tag the entire project or a set of projects with a single command:

svn copy url://repos/trunk url://repos/tags/tagname -m "Create tagname"

This is probably the most commonly used repository layout and is used by many open source projects, like Subversion itself and Subclipse. This is the layout that most hosting sites like Tigris.org, SourceForge.net and Google Code follow as each project at these sites is given its own repository.

The next layout is the best option for a repository that contains unrelated or loosely related projects.

ProjectA
   trunk
   branches
   tags
ProjectB
   trunk
   branches
   tags

In this layout, each project receives a top-level folder and then the trunk/branches/tags folders are created beneath it. This is really the same layout as the first layout, it is just that instead of putting each project in its own repository, they are all in a single repository. The Apache Software Foundation uses this layout for their repository which contains all of their projects in one single repository.

With this layout, each project has its own branches and tags and it is easy to create them for the files in that project using one command, similar to the one previously shown:

svn copy url://repos/ProjectA/trunk url://repos/ProjectA/tags/tagname -m "Create tagname"

What you cannot easily do in this layout is create a branch or tag that contains files from both ProjectA and ProjectB.  You can still do it, but it requires multiple commands and you also have to decide if you are going to make a special folder for the branches and tags that involve multiple projects. If you are going to need to do this a lot, you might want to consider the first layout.

As for the names of the folders within the repository, again: they are just a convention. They have no special meaning to Subversion.

“trunk” is supposed to signify the main development line for the project. You could call this “main” or “mainline” or “production” or whatever you like.

“branches” is obviously supposed to be a place to create branches. People use branches for a lot of purposes. You might want to separate your release or maintenance branches from your feature branches or your customer modification branches etc. In this case, you could create a layer of folders beneath branches, or just create multiple branch folders at the top-level.

“tags” are not treated as special by Subversion either. They are a convention, perhaps enforced by hook script or authz rules, that indicate you are creating a point in time snapshot. Typically the difference between tags and branches is that the former are not modified once they are created. You might call your tag folders “releases” or “snapshots” or “baselines” or whatever term you prefer.

Remember, the significance of the name is for your benefit, not for Subversion. Finally, the architecture of Subversion, with its global revision number can often make the need for tags unnecessary. I do not think there is any reason to create tags just for the sake of creating them. If you find a need to recreate the software at a specific point in time, you can always do so by using svn log to determine the relevant revision number. Tags are best when there are “external” consumers of the repository. Maybe it is a QA/Release team that needs to perform builds, maybe it is an internal development team that wants to use releases of your code in another product, or maybe it is literally external users or customers who need to grab release snapshots from your repository. In these scenarios, creating tags is both a convenient way to be sure they get the right code, as well as a good communication mechanism to indicate the presence of release snapshots.

Hopefully this post clarifies some of these issues for you and makes it easier for you to understand how Subversion works.

I would like to finish by pointing out that a Subversion repository layout can be changed. You can always reorganize and restructure your layout after the fact. At worst, it just might create some short term pain as users adjust their working copies. It is not like you need to start over though. Just change names, move folders or do whatever to get the filesystem looking the way you want it.

Mark Phippard

Engineering manager for several teams at CollabNet, including CloudForge, Subversion, Subversion Edge, Git and our Desktops and Integrations. Project owner for the Subclipse project, which provides Subversion support in Eclipse. Also a full committer for the Subversion project. Product owner for GitEye, Subversion Edge and the CollabNet Desktops and Integrations.

Tagged with: , , , , , , , , , , , , , , , , , ,
Posted in Subversion
12 comments on “Subversion Repository Layout
  1. Hi,
    is there any trunk strategies as we were used in other version control system(clearcase).
    Regards
    Ravi

  2. We have a discussion forum that is well suited to ask questions of this nature:
    http://subversion-migration.open.collab.net/servlets/ForumMessageList?forumID=37
    The forum is frequented by other users that have migrated from ClearCase to Subversion or are considering it.
    Mark

  3. Deepali Parikh says:

    Can we use 2 different layouts in one subversion repository. And at later stage can we change the repository layout and still can be able to maintain the history?

  4. Yes and yes. It is basically a file system. You can organize stuff in any way that meets your needs. If you want to change it, you can use svn move to move things in the repository and all history stays attached.

  5. Tim says:

    We have a growing project in subversion that we want to split into many projects each with its own repository, retaining existing history. Is there a how-to for this? TIA.

  6. Subversion has the svndumpfilter tool. If you Google for it you can find some how-to’s that people have written. There are limitations in this tool if you have done any copies between these projects. If you run into that, then Google for svndumpfilter2 and svndumpfilter3 which are scripts that enhance the process. There is also a Perl module in CPAN if you want to script your own solution.

  7. David says:

    Can you please elaborate more what a deep directory tree structure would look like? Would you just have a /trunk/a/b/c/d/e/f.doc and then if you make a branch copy just that file to /branch/a/b/c/d/e/f.doc?
    Thanks!

  8. Mark Phippard says:

    David,
    I’d encourage you to always branch the root of the project, whether it is /trunk or /trunk/ProjectA or /ProjectA/trunk.

  9. Parminder Kaur says:

    Hello,
    Myself is working as a research fellow in the area of software engineering. I make use of Subversion to keep track of changes in my work. while dealing with .doc files, i am facing problems. Please suggest the ways to associate .doc files with subversion.

  10. Blair Davies says:

    One thing I’m having a hard time getting my head around is the notion of working copies vs current copies vs the repository itself.
    What I want to setup is a central code tree that has my ‘gold code’ (current copies) that we compile and build from (ex: c:production). Then each of the developers has their own working copies of some files (ex: c:mydev). When they commit their changes they are merged into the ‘gold code’ and deleted from their working directory if they are finished.
    I thought the repository would then be c:production. But that doesn’t seem to be the case.
    Can you explain this to me?

  11. Bill Richards says:

    @Blair
    The repository itself is the thing that retains all versions of each file checked in, and the attached history for each item.
    The current version is the latest version within the repository.
    The working version is the code checked out locally on a developer’s machine.
    Code check outs are on a per-user basis, and you can check your code out to anywhere you like, so long as you have write permissions and access to the repository.
    For example:
    svn://myserver/Solution1
    branches
    tags
    trunk
    Project1
    // all files for project1
    Project2
    // all files for project2
    Any developer with access to this repository (Solution1) can check these projects out to whatever local storage they like …
    C:working version
    C:Projects
    C:AnyDirectoryILike
    Checking code in from the local working copy results in a new version number in subversion.
    Your build server (if linked to SVN) will pick up the current version and build the solution.
    You can check your code out to multiple locations if you like, but this is all under the user’s control, not SVN.
    Subversion will not dictate where your doe is checked out to.

  12. What is the recommended strategy for storing configuration files and other files that change reguarly and nonlinearly on subversion?

1 Pings/Trackbacks for "Subversion Repository Layout"
  1. [...] Repository or Many? Posted by Mark Phippard on April 26, 2007 My previous blog entry discussed the issue of repository layout. This entry will try to answer the question of whether you [...]

Leave a Reply

Your email address will not be published. Required fields are marked *

*

CAPTCHA Image

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

connect with CollabNet
   Contact Us
sign up for emails
looking for something
conversations

CollabNet: Learn which Apache #Subversion server products that @CollabNet: provides is right for your enterprise. http://t.co/coKOlEzzLp
Date: 11 September 2014 | 8:05 pm

CollabNet: .@rsabbagh: #CST will be teaching a Certified #ScrumMaster course in Toronto, ON Sept 25-26! Register soon! http://t.co/xCuQ0wP4dr
Date: 11 September 2014 | 5:15 pm

CollabNet: Ask the #Agile Guru questions related to Agile cultural shift, management best practices, engineering best practices http://t.co/optUVe9Rmj
Date: 10 September 2014 | 8:30 pm