I discovered Subversion and Revision control software in general a little over a year ago. I’d heard of it all before but that was when I began to learn about and use it. The appeal, once I took the time to think about, was significant. As a freelance website developer (and reluctant designer), being able to version my code meant time saved from searching through backups (when I’d deleted stuff) and cleaner space (from when I wouldn’t have deleted stuff; see previous point). It particularly allowed me to get rid of goofy versioning mechanisms I had employed (file names with 1,2, etc at the end, e.g.).

Having used Subversion extensively this past year (although certainly not all of its features), I have a few suggestions for newcomers regarding the repository setup. It turns out, looking back at it, that the online manual could have told me this just as well (more or less), particularly the section about Repository Deployment and Externals Definitions. If you’re seriously looking for repository layout advice, I recommend reading those more than the rest of this article. On the other hand, personal experience can at times be more immediate and useful that a manual. (By the way, I haven’t looked closely to see how well my suggestions really match up with the manual; rather, I’ve noted in re-reading sections that they make a lot more sense to me now.)

When I setup my repository, I set up one, single repository for all my projects. And life was good. The root directory contained a directory for each project. This was manageable up to about ten projects. Then, I begun dividing them into groups. My logic for a single repo was:

1. Aesthetic reasons: for better or worse, I just liked the idea of a single repository better.
2. Ability to svn copy files/directories between projects: A number of the websites I’ve made have very similar code that is not quite similar enough to just create a library, and the chance to save space appealed to me.
3. I could setup a frame project (for Rails apps) and when I started a new site, just svn copy).

I still aesthetically like the idea of a single repository, but that’s no justification for a business decision (at least when there are weightier factors). What made me change my mind otherwise? Simply, it became a headache. One of the problems was that the project group directories I created early on are no longer as useful groupings as they were, and I don’t really want the change to be versioned. When going back to earlier revisions, the path to the project would be uselessly different. But the straw that did in that design was one project. This project contains a lot of media. I didn’t want to put all that media in my main repository. I like the fact that it doesn’t take up a lot of space. But I’ve found a need to start versioning many of those large media files. So, I decided to use svndumpfilter to break out the project. And with all the path moves, I realized I was facing a serious chore. I also had a bunch of project folders that were basically empty, unused, I’d created in a fit of “planning”. There was no reason to have them at all, so I wanted to completely remove them from the repository.

Over the past couple of weeks, I’ve spent many hours writing a lengthy script to break up the repository. Because I realized it’s best to get it done now. Some major difficulties have been the result of my earlier reasons for a single repository. The copies between projects and setting up projects by copying from a frame create extra dumps that must be done. And for very little gain, it’s turned out.

Here’s how my repositories will now be:

From the view of svn-serve–at least, for now–the repository won’t look much different. But the project group folders will generally be regular folders with the filesystem, holding project folders, which will each be (generally) a single repository. There are a few exceptions, where the group is the root of the repository, holding multiple projects. But I plan for minimal, if any, path moving once they’re created (if needed, I plan to do it using dumps, but I will try to plan to avoid it).

Anyway, my five key points of advice:

1. Except for small, easily grouped projects (rails plugins, for example), each project has it’s own repository.
2. In any case, project heirarchy (divsion into groups) should not be within the repository. There’s no use in having that versioned and it gives much more freedom.
3. Use svn:externals rather than svn copy for sharing code between projects, even within your own repository realm. And when you do, use -r option to explictly set the revision (or set the external to a tag). Setting to the trunk without a -r is asking to break your code.
4. If you need a frame for creating new projects, make the frame itself a repository. Copy the repository (within the filesystem), rather than a project within a repository. Much more manageable. Or use a script.
5. It’s worth the extra space to copy large chunks from one project to another in different repositories, when a library shared via svn:externals won’t work. It’s better than the headache.

Yes, the proceeding blog entry was ~80% introduction. test