Experience has shown me that the best method is to use the command line tools, specifically svnadmin.

> svnadmin dump oldrepo > oldrepo.txt

The command ’svnadmin dump’ creates a plain text file of all your revision. Included in this is a hash of each revision to check against once you start your import process.

Be careful not to forget to pipe the output into a file, if you don’t you will get a lot of  text flooding your terminal very quickly.

Now create your new version 1.5 repositoy, again using svnadmin.

> svnadmin create newrepo

We can now import our old revisions into the new 1.5 repository using ’svnadmin load’

> svnadmin load newrepo < oldrepo.txt

Svnadmin will report on screen any problems and show its progress. The process is very quick and normally takes a matter of minuites for anything other than the largest repositories.

Hopefully the audience will be gentle.

The command line syntax is very easy, this will commit all the changed files from your working copy.

D:\Test\site>svn commit -m "my great comment"
Sending index.html
Transmitting file data .
Committed revision 66.

Using the Tortoise client you can select individual files to commit, much easier than using the command line client.
Try to make sure your commit comments are as clear and descriptive as possible.

Explain why the change was made, include any bug or change reference that you have. Remember that these notes are not just for your benefit but for the many people who will be looking over the code in the future.

Commit your changes in logical groups.

Each time you commit changes to the repository make them as complete changes. Don’t check in half finished bug fixes or enhancements, unless you really need to. Remember someone could checkout or update to this ‘broken’ version and be disappointed when expected functionality doesn’t work.

Communicate to your team when changing important files.

Each project or website has a certain set of key files, whether it is the default layout for the front page, or a function to pull information from a database. These changes effect everyone else working on the project. They need to be aware of possible issues which may arise from your changes.

Update your working copy before you commit.

It may be a day or a week since you checked out from the repository, in which time others may have committed changes to the files you are editing. Make sure to do an update on your working copy before you commit your changes. Then you wont get any nasty conflict messages.

Using the Tigris Subversion Binaries

To create your own Subversion repository, you will first need to install the Subversion server software.

At the time of writing the current version was svn-1.4.5-setup.exe.

More versions are available at the Project Download Page.

Installing this will give you a Subversion folder at something like C:\Program Files\Subversion. Must regular subversion users will put the /bin folder in their path. This means they can execute the Subversion binaries from any location on the command line.

To create our repository will use the svnadmin.exe binary, with argument create and then the location on the file system where we want to create the repository. For example:

svnadmin create D:/temp/repo

This creates me all the required files for me to get started. I can access this repository directory using the url:

file:///D:/temp/repo

Using TortoiseSVN

Create a folder in the location you wish to create your repository. This is best to be an empty folder, on a path which contains no spaces. For example:

D:/repositories/companyname

Would be easier and better to use as apposed to.

D:/Program Files/Company Name

Right clicking on this folder will give you the “Create repository here…” function. TortoiseSVN gives you the option of two flat file system databases, Native Filesystem (FSFS) and Berkeley Database (BDB). Your best option is to pick the default FSF, BDB will not work over a local network, not even a remote share.

You can now access this repository via the url:

file:///D:/repositories/companyname

Obviously there will be nothing available yet, my previous post details how to import established projects into subversion

Even though Branches aren’t a dark art, they are a little more complicated than most things in version control. This shouldn’t put you off using them, as they will save you time in the long run. But you should take time to organise them and create a structured naming convention.

Below is a diagram of a single Branch being created from the trunk. Have a quick look at it, then I’ll describe the process in detail.

Firstly we need to create an anchor point to remind us when in the repositories history the branch was created. This will help us in the future if we are unsure what patches need to be applied.

To do this we create a Tag from the Trunk. I’m going to pretend we’re at the start of this projects life. So I have created the Tag as 1.0.0, remember to create a Tag just use the copy command in subversion and place the copy in the Tags directory in the repository.

Now we have a fixed position to play with we can create our Branch. This is a copy from the Tag we have just created (1.0.0), but this time placed in the Branches folder of the repository. We name our Branch with a reference to where it was created, this is where the Tag comes in. Here I will name the Branch 1.0.0_B1. Where as Tags are normally read only, Branches are not. We use branches to allow multiple development streams to work on the same pieces of code.

Heres an example of when to use a Branch.

Lets say you wanted to redevelop your database access layer of code. This may take a significant length of time. By which I mean that you might need to bug fix your existing code before the new code is available to use. This is when you would use a Branch. This allows you to seperate your new code, while allowing you to maintain your Trunk.

Once you are happy that your branch code is ready to be used in anger you need to get it back into the trunk. This can be done in two ways, you can checkout both the Branch and the Trunk and use a diff tool to merge the changes. The other way is to create a patch (I’ll be explaining patches in a future article).

Once the code is in the Trunk and tested, commit the changes and create another Tag. This will be a reference in the future of when you committed these changes. In my example I’ve named the Tag 1.1.0 to indicate a minor change to the code base.

Now for a more complicated example, in less detail now since I’m sure you understand the basic ideas.

1 ) Create Tags/1.0.0

2 ) Create Branch/1.0.0_B1

Meanwhile a bug fix is made to the Trunk.

3 ) Create Tags/1.0.1

4 ) Create Branches/1.0.1_B1

5 ) Merge bug fix from Trunk to Branches/1.0.0_B1

Work is done on both Branches. Branch 1.0.0_B1 is ready to commit merge to the Trunk first.

6 ) Merge 1.0.0_B1 to Trunk

7 ) Create Tags/1.1.0

The 2nd Branch is now out of line with the Trunk.

8 ) Merge Trunk to Branch 1.0.1_B1

Development on the 2nd Branch has now finished and is ready to be committed to the Trunk.

9 ) Merge Branch 1.0.1_B1 to Trunk

10 ) Create Tags/1.2.0

Fin

Using a clear naming convention allows you to understand how and when you need to make merges to where. Once you are finished with the Branches you can delete them, or keep them if you are interested in the individual revision history.

To demonstrate the process I’ve created a little Java project called DBTest, here is its layout.

DBTest
│   build.xml
│
├───lib
│       mysql-connector-java-5.0.7-bin.jar
│
├───resources
│       database.properties
│
└───src
  └───net
   └───sailes
    └───DBTest
      DBTest.java

Its nothing special, just one Java class, one property file, one 3rd party library and a build script to pull it all together.

The first thing you need to think about it the layout of your Repository. Obviously if your adding to an existing repository you can follow the existing guidelines. However if your starting from brand new, its worth considering a few questions.

How many separate projects am I liking to create?

No one likes a list of 100 separate folder they have to scroll through, it might be worth considering sub folders.

Who needs access to what projects?

Group together similar projects this will help you create easy to maintain access lists in the future.

Where should I place my trunk, tags and branches folders?

I’ve seen lots of different style, and each have their benefits.

/trunk/projectname/src
/src/trunk/projectname
/projectname/trunk/src

Personally I like to be able to version up specific components, so I like to have a different trunk, tags and branches folder for each project. If all your projects are interconnected you may not like this approach.

So now I have an idea of the layout I want, I’m going to use the Tortoise SVN repo browser to create my initial folders.

Type in your repository url and right click the parent folder, giving you the option to “Create folder…”

Give your project folder a name “DBTest”

Now create the default Subversion folders in the same way.

Tortoise SVN gives us a function to be able to import folders into our repository. These are the “Add folder…” or “Add file…” options. This allows you to very quickly import files directly into the repository. But be careful that you don’t add sub folders you don’t need. For example:

Importing the DBTest folder directly into Trunk would give you the paths

/Projects/DBTest/Trunk/DBTest/lib
/Projects/DBTest/Trunk/DBTest/resources
/Projects/DBTest/Trunk/DBTest/src

Duplicating the project name. You may need to do several folder and file imports to get the structure just how you want it.

Another way is to checkout the Trunk folder as a working copy to your machine.

Then copy your files into the folder structure you want, then to do an svn add.

You can then commit your files once your happy that you’ve not broken anything.

This is the process I’m currently pushing for where I work. For all documentation I receive on projects I have to work on. I think it works well for all non source code documentation, but I have a feeling there will be mixed opinions. So lets see how we go…

We use Subversion to track changes that we make mainly in source code. These are plain text files, 90% of the time human readable. Using diff tools it makes it really easy to spot what has changed between versions. However a lot of documentation is written in proprietary formats which are unreadable to humans (Microsoft Word for example). You could just check these into Subversion, but you are losing a lot of the benefits you would normally gain from version control. Unless you were going to write very detailed comments for each revision, you would only be using Subversion as a glorified backup system.

My suggestion is this:

Write your documentation in a simple way, in plain text. This doesn’t mean you have to start writing everything as .txt files using notepad, but you could. A more serious suggestion is to write your documents in html. This is a plain text format, which allows very creative layout and presentation. I’m not suggest large complex websites, but just very simple <p> and <h1>’s, with the option of adding tables and images where needed.

Using a html format you will easily be able to see which sections of writing have changed between versions, and you will lose very little value in presentation. After all we all know that good documentation is about accuracy and clarity, not fancy word art.

You also get the added bonus of having a file format that is 99.9% viewable on any platform with any operating system. No more “My version of open office wont open your version of MS Word”. This is a very important consideration as you move to larger multi location teams.

I’ve seen some corporate repositories separate their source code and their documentation. I think this is a bit silly, personally I always advise it to be added right next to the source code and other resources. For example:

MyProject/
   docs/
   lib/
   resources/
   src/

To answer the second part of Dom’s question. If I want to sync with the server, I just do a svn update. This will give me the latest version which has been committed to the repository.

The majority of development work is done on the developers actually machine or a development team server. Normally with a working copy of the code in one directory, and sometimes a separate copy in another folder being served by Apache or IIS.

As the developer works on the code, they will often make some updates to their server directory to see their changes in effect. Often making lots of small changes, updating the server folder often is a pain. Here I will show you how to use svn hooks to automatically update a folders contents when you commit your latest version into the repository. This way your server will always be serving your latest work.

The svn repository folder structure contains five separate folders.

conf
dav
db
hooks
locks

Today we are just interested in the hooks folder. This contains templates for all the events fired as you commit and work with the svn repository. They include: