Subversion

Tips

• • Don't checkout more than you need.

  • Commit as often as you can. Just make sure that what you commit won't break the build.

  • Test and verify before you commit.

  • Always comment your commits.

  • Branch before you release.

  • Tag after successful builds.

  • Use mod_dav with apache if you expect lots of activity.

  • Organize your repository tree with:

    • trunk

    • branches

    • tags

  • Document your tree.

  • Structure your project in a way that you can just checkout and make.

  • Build your makefiles to support:

    • clean

    • build-all

    • build-dist

    • build-package

    • test

  • Do NOT check-in build artifacts. I know, some groups do that. It's wasteful of repository disk space. And here's the real gottcha, once you check-in a file to subversion, it's extremely difficult to delete. Version control should be used to hold the secret recipe, not the meal! Just use some common sense here. You use a structured build process to faithfully reproduce a build. If you tag those builds, it's just a matter of checking out the tag and running the build. If you need to save your build artifacts, then use a backup or archive tool. Copy your build artifacts to a distribution directory then back that up.

Quick start

• • svnadmin --fs-type fsfs create /pathname

This creates a subversion repository at /pathname. The option --fs-type fsfs will create the repository using a database type of fsfs. It's better to use the fsfs database, rather than bdb (Berkeley DB), for performance and reliability issues.

• • svn import LocalDir file:///pathname/ProjectName

This will import the contents of LocalDir into the Subversion repository file:///pathname/ProjectName.

• • svn checkout file:///pathname/ProjectName

This will checkout the repository file:///pathname/ProjectName.

• • svn co http://svnhome.tsand.org/svn/ProjectName

This will checkout the repository ProjectName from the web server svnhome.tsand.org, path /svn/.

• • svn help [command]

Tutorial

This tutorial covers the creation of a local repository, an initial import and a checkout.

• 1. Ensure that your subversion software is installed. On windows, I install the cygwin package along with the subversion package, then I'm able to start a cygwin session (a shell) and issue my commands just like I was on a Unix or Linux system.

  2. To create a repository you need to select the directory that you have write permissions to. For this example I will create my repository under directory /opt/svn. I will name my repo "project_a". You then issue the command:

     • mkdir /opt/svn

     • svnadmin --fs-type fsfs /opt/svn/project_a

  3. I suggest using the option "--fs-type fsfs" to specify the database type for the repository. There are two types of databases, bdb (berkeley database) or fsfs (filesystem). I suggest using fsfs filesystem as there have been some reported problems with bdb. And if you ever experience a system crash in the middle of a subversion operation, your bdb database could become corrupted, which entails other commands to run in an attempt to repair the repository. With fsfs, a plain old fsck (which Unix typically runs on filesystems after a crash), will clean things up nicely.

  4. You will need to set your permissions to the repository so that others will be able to checkout (read) and checkin (write). I usually create a special user and group entry to store all my subversions files under. User ID svn, Group ID svn. Then I configure authorized users to the group "svn", and then set write permissions for all group access. For example:

     • chown -R svn:svn /opt/svn

     • chmod -R g+w /opt/svn

  5. Now we can import some data. Create a directory with some files in it. The following script will work well for that:

     • cd $HOME

     • mkdir project_a

     • cd project_a

     • mkdir trunk branches tags

     • cd trunk

     • date > file1

     • date > file2

  6. The structure of trunk, branches and tags is the recommended repository layout. The directory "trunk" is where all your main-line development will occur. When your project is ready to release, you then branch the trunk to the directory "branches". In subversion this merely creates a link. This "branch" is a point-in-time checkpoint of all the current state of the files that were in "trunk". You then apply any fixes to the newly created "branch", and may merge those fixes from the new "branch" back to the trunk, if needed. We use the "tags" branch for sucessful nightly builds. A typical shop will run nightly builds. If the build suceeds, then we create a new "tag" in the "tags" directory. This also is merely a link. There really isn't a whole lot of difference between a branch or a tag, it's just how you decide to use them.

  7. So now for the import:

     • cd $HOME

     • svn import -m "initial import" project_a file:///opt/svn/project_a

  8. We pass in the '-m "initial import"' option to specify the commit message. If you leave this out you will be prompted for the commit message.

  9. Now we can checkout the project:

     • cd $HOME

     • mkdir checkout

     • cd checkout

     • svn co file:///opt/svn/project_a

  10. You will now have a directory under "checkout" called "project_a" with all of your files.

Subversion URLs