RoughDraft:Subversion

From Tech Elephant

Subversion, or SVN for short, is an open-source revision control system, which aims to be a compelling replacement for CVS^[1]. The project was initiated in 2000 by CollabNet Inc^[2], but was conceived from the start to be a community-driven open-source project.

[edit] Best Practices

[edit] The directory structure

[edit] Overview

The beauty of Subversion is that you are not tied to a specific usage pattern. This lack of structure tends to confuse the newcomer. If you have used other version control systems, such as Microsoft's Visual Source Safe (VSS), CVS, or the like, the power of Subversion is not intuitive.

Particularly confusing is the notion of working with tags and branches. In subversion, your code can be tagged and branched by simply copying a file or directory into another directory. This other directory is usually called 'tags', but you are not forced to use that paradigm.

[edit] Why is there no required usage pattern for tags or branches?

The creators wanted to leave this decision completely in the control of the user/developer/software-engineer. This is because Subversion's underlying repository structure versions all content within the repository, including directories. Since a directory is version in the same manner as a file, everything points back to a revision number. So, when you wish to 'tag' a file or directory as a certain version number, then you simply copy that file or folder into a directory designated as your 'tags' directory. This copy simply points back to whatever revision number the original represented when you made the copy. Hence, your 'tagged' can pull out or export the exact state of the file or directory you wanted to preserve to reference a specific version number.

[edit] Stratagies

The first thing you may do is start adding your files to the repository root. Of course, this isn't "bad", but it certainly won't help you as your code matures.

[edit] Single project

Are you only working on a single project or application code-base? If so, you simply need to create the following structure:

• [repository_root]
  • /trunk/
  • /tags/
  • /branches/

This basic structure will allow you to utilize all traditional features of a mature revision control system, such as tagging and branching your code.

[edit] Multiple projects in a single repository

If you are working on multiple projects and wish to use a single repository, you may want to apply a different strategy.

At first, you may simply place your projects under the existing/single-project directory structure.

This would look like the following:

• [repository_root]
  • /trunk/
    • [project_one]
    • [project_two]
    • [project_three]
    • [project_four]
  • /tags/
    • [project_one]
    • [project_two]
    • [project_three]
    • [project_four]
  • /branches/
    • [project_one]
    • [project_two]
    • [project_three]
    • [project_four]

Although this looks like it may be a good paradigm, but you'll quickly find that maintaining it is definitely a pain. Exporting a single project to relocate it to another server or repository is not as simple as pulling out a single directory. Yes, you could create an export filter, but it's not as user friendly.

Here is a slightly different strategy that gives you separation of projects, each with their own directories to handle their trunk, tags, and branches.

• [repository_root]
  • [project_name]
    • /trunk/
    • /tags/
    • /branches/
  • [project_name]
    • /trunk/
    • /tags/
    • /branches/
  • [project_name]
    • /trunk/
    • /tags/
    • /branches/
  • [project_name]
    • /trunk/
    • /tags/
    • /branches/

This will allow you to export a project and import it into another repository when your code requires it.

[edit] Converting an existing structure

Did you read the above section thinking that you did it wrong and there's no way back? Don't worry, the beauty of Subversion is that you can always change your mind later and move things around at will -- without losing your revision history!

The only action you need to take is executing a "svn mv" command.

The syntax resembles the following:

svn mv [old repository path] [new repository path]

Here is an example:

svn mv http://localhost/repository/old/ http://localhost/repository/new/

[edit] Notes

1. ↑ http://subversion.tigris.org/
2. ↑ CollabNet is a software and services company. It produces development collaboration software for enterprise businesses. They also own and operate [wikipedia:SourceForge SourceForge], which they acquired in 2004.