GrantPalin.com

Introduction

This article follows my previous one on starting to use Subversion on DreamHost. After that crash course, this one will show how a repository structure can be organized, so as to simplify use and maintenance.

Subversion allows you to version control many types of projects - websites, databases, software, and so on. You don’t even need to have a particular project to use the system - perhaps you would like to version control your documents? You can with Subversion.

For any non-trivial project, it is a good idea to have structure in place for mainline development, branch development, and tagging specific versions. To that end, the following folders are typically set up at the root level of a given repository:

• branches
• tags
• trunk

These folder names are not required, certainly, but they are the standard convention. They have the following meanings:

branches - temporary branches of the code base where you develop/integrate new features, or to experiment with what is in place already. If necessary, changes made to a branch can be merged with the mainline code. The branch would then be deleted.

tags - permanent branches of the code base, typically used to mark milestones or release versions. If you check out a tag, you get the entire code base as it was at the time the tag was created. Tag names tend to be based on the version number of the code base. There should ideally be no commits made to tags - it is allowed, but bad practice - as they are to be permanent snapshots of the trunk at a particular time.

trunk - usually where mainline development occurs. If extreme, or experimental, changes need to be made, it is best to create a branch and work on that. Then merge any changes back to the trunk if needed.

Note that branches and tags are copies of the code base as it was at the time they were created, but Subversion does this in a way such that no actual copies of files are made. So these operations are quick, and do not require much additional space.

Also note that for certain projects, depending on the nature of the project, there may not be a need for anything other than a trunk. Regardless of whether you use tags or branches or not, you are still able to perform updates and rollbacks as needed. A single website, for example, may not need tags, unless there is a particular need to take snapshots at intervals. Branches may be desired if major changes are being performed. Software development, on the other hand, will almost certainly require branches and tags, so release editions can easily be organized and located.

So that’s the basic theory covered. Time to see a real-world example.

Getting Started

No simple theory project this time: I will demonstrate this process as I do it, with screenshots along the way, to get one of my ongoing ASP.NET projects into properly structured source control using Subversion. I will talk about this as if I am doing it, but the process can easily be applied to any project of your own.

To start with, I create a folder on my local hard drive to receive the checked-out version of my newly-created repository.

Now I right-click the empty folder, and choose SVN Checkout... I enter the URL of the new repository, click OK. Fill in my username and password when prompted. When the process completes, I’m shown a success dialog, which I dismiss. And I’m left in an empty local folder, which in the folder view pane has a green checkmark on it. The folder is empty because the repository was just created, so it is empty as well. But not for long.

I’ll add a trunk folder first. This is done by right-clicking inside the empty folder, and choosing New->Folder. I’ll rename it to trunk. Repeat for branches and tags.

Right-click one of the folders, and choose TortoiseSVN->Add... Click OK at the confirmation dialog, and again at the success message. Observe the blue cross icon overlaying the folder. Repeat for the other two.

With those folders created and marked by TortoiseSVN as to be added to your Subversion repository, it’s time to send them to the Subversion repository. Right-click the top-level folder for the project (in my case, wadmt), and choose SVN Commit...

It is good practice to type a meaningful message describing the nature of the commit - Subversion logs this information. This is useful if you wish to review updates and commits for your repository in the future. Having a descriptive message to go with a revision number is very helpful!

At this point, something like “Adding branches, tags, and trunk folders” will do. That’s what I’ll do here. The process goes through, and the repository is now at revision 1.

As the image shows, I have those three folders added and now part of my repository.

Moving to the Trunk

I’ve mentioned previously that most project work happens inside the trunk. So before I start adding files to the trunk, I want to switch the local working copy to be based on the trunk, rather than the root of the repository, which is how it has been to this point. To make this switch, we need to use the Switch dialog.

Switch is a feature that changes the location of your working copy. When executed, the working copy becomes based out of a different folder in the repository, or even in a different repository altogether. This will allow us to quickly switch the working copy to the trunk folder of the repository.

To make this happen, I right-click my wadmt folder, and choose TortoiseSVN->Switch. The dialog shows the URL entered for the repository when first checking out. In my case, I added trunk (use your “trunk” folder here as appropriate) to the end of the URL, so that I would be checking out directly from the trunk rather than the repository root. If a repository was not using branches or tags, a specific trunk folder would not be needed either. In which case, this step would be redundant, as commits could be done directly to the repository root.

Although I do think the branches/tags/trunk setup is better for keeping things organized, and tend to stick with that pattern.

In any case, click OK on the Switch dialog, and you should get a result similar to the image above. Do not be alarmed by the Deleted listing - TortoiseSVN is smart enough to know you will not need those folders locally when you are working directly from the trunk. The folders have been deleted locally, but are still in the repository.

Working in the Trunk

This is another place to discuss some repository structure theory. Like with the branches/tags/trunk discussion, some extra planning here can make a repository much more usable.

For some projects, there is going to be more involved than just the code itself. There will be documentation, external libraries, and external tools.

Again, these depend on the nature of the project.

Some projects use external, third-party libraries, or binaries (usually .dll files), to achieve some specific purpose within the project. It makes sense to have these external libraries centralized in one location, so they can easily be located and updated or removed as necessary.

Documentation is important for any project. It is important to keep it up to date along with the project itself.

Some projects involve using third-party tools - not in the way of external libraries for the project itself - to build and maintain the project. These tools tend to go into a centralized location as well.

In the case of some projects, especially software development, it may be desirable to store a built, ready-to-use version of the project. This makes sense to have it’s own area as well.

And after all this, I guess we may as well let the actual project have its own area!

So, to that end, I have gotten used to using the following directory structure, inside the trunk:

• build
• docs
• libs
• src
• tools

These should easily be matched up with the items previously discussed. The names are subjective, but they seem to be commonly used.

At this point, I’m only worried about the src folder, so I can get my project source code into the repository, and the libs folder, since my project does use some external libraries.

So I will go ahead and add and commit all the folders listed above (even though I am only using two of them, the others will be in place once I get to using them). I actually don’t need to create the build folder, as the project compilation process will recreate that folder as necessary. The image shows where my trunk folder is at now.

With those folders in place, I can copy my existing code files into the src folder, maintaining structure within the code base. And I copy the external libraries (four of them currently) into the libs folder. I will need to open my projects in Visual Studio and point them at the libs folder for the external libraries that they use. I make sure not to include any bin or obj folders, as they are generated by the compiler, and do not need to be in the repository.

If you are not using Visual Studio, or you are using another technology such as PHP or Java, no big deal: chances you already know how to specify use of external libraries in your own projects.

The following image shows my trunk as it is now, with the solution (.sln) file directly within the src folder, and the sub-projects in their own folders. The solution file ties them all together, regardless of where they are located.

Conclusion

I have illustrated the basic/general layout for any project, and shown how I leverage this structure for one of my ASP.NET projects. I also pointed out the importance of structuring a project/repository so that it is easy to use and maintain.

It is important to re-emphasize that repository structure is very subjective, and should be based on the requirements of the projects and of the technologies involved. This is the way that I do it, and it seems to work for my needs so far.

Additional Reading

The following sites are recommended reading for further information and discussion on this subject.

• My recommended Subversion repository structure
• .Net Development Trees part I
• How to setup a .NET Development Tree