Sandbox Web Solutions

Before I started using subversion I used to make backup of my projects on regular basis and I can’t emphasis enough how this process was so boring and tedious, and every know and then I forget to make a backup or maybe replace files by accident. Actually I don’t know how I survived without using some kind of version control.

I’m assuming that because you’re reading this article then you probably have some general info about Subversion and maybe some other version control system like CVS. If not, then no problem, this article will still help you to get started using Subversion.

This article assumes that you’re running windows xp/vista, but the concept is the same and should work just fine on linux and mac os x systems as well, the only difference will be in the installation which you’ll find a lot of guides on the internet.

So lets get started, here is an overview of the guide:

1. Downloading and Installing Subversion for Windows
2. Creating a Repository
3. Initializing Repository Structure
4. Creating A New Project
5. Checking Out a Project
6. Adding Files to the Working Copy
7. Committing Changes

Downloading Subversion for Windows

Subversion for windows can be downloaded from here. After downloading is finished, install the package. If it asks to restart, please do so. In order to verify that the installation was successful open the command line prompt and type svn then hit enter on the keyboard. If you get an output similar to the following then the installation was successful.

Type 'svn help' for usage.

Creating a Repository

Now that we have subversion installed we want to create out first repository. Normally you’ll want to store the repository on the root of a drive, for example c:\repo, so lets use this path to store our repository.

To create a new repository we use the following command:

cd c:\
svnadmin create repo

Initializing Repository Structure

Defining the structure of your repository is completely up to you, there’s no restrictions in subversion that forces you to structure your repository in a certain way but most developers around the world uses the same structure as a global convention. This structure states that the repository will be divided into three main folders: Tags, Branches, and Trunk. I’ll not dive into why this structure was agreed upon between developers around the world. I’ll leave that for another article. Maybe that reason will make you visit my blog again .

So lets create the repository initial structure.

svn mkdir file:///c:/repo/tags file:///c:/repo/trunk file:///c:/repo/branches -m "initialized repo structure"

The above command should result in the following output

Committed out revision 1.

Lets explain what happened now, first we used the svn command mkdir to create three folders and we also added a message using the parameter -m.

After running the mkdir command svn reports that the repository revision number is now (1). Each time you modify the repository whether by adding, modifying, or deleting, the revision number increase by one. So the repo revision number is an indication of the number of changes made to the repository since it was created.

Creating A New Project

Now that our repo structure is ready lets create our first version controlled project. For sake of testing we will name the project sandbox-ws. The sandbox-ws project will be added to the trunk folder. We will use the same mkdir command

svn mkdir file:///c:/repo/trunk/sandbox-ws -m "created sandbox-ws project"

Checking Out a Project

The figure below outlines the basic operations done on a subversion repository. First we create the repository, then initialize the project structure, then create one or more projects in the repository, and last but not least, the developers checks out a project, modifies it, and then commits the changes back to the repository so other developers can update their working copies to reflect those changes.

If sandbox-ws was a PHP project for example, then the working copy will be in your web server’s documents root, htdocs for example if you’re using Apache. But for sake of testing we will create our working copy on the Desktop.

To check out the sandbox-ws project run the following command(NOTE: I assume that you’ve changes the cmd path to your desktop):

svn co file:///c:/repo/trunk/sandbox-ws

The above command should result in the following output

Checked out revision 1.

Now we move to the sandbox-ws project:

cd sandbox-ws

Adding Files to the Working Copy

Now that we have checked out the sandbox-ws project, it’s time to add some files to it. We will start with a simple php file, see below

// index.php
<?php echo 'Hello World!' ?>

What we have done by adding a new file to the working copy is that we simply modified it. Lets see what subversion have to say now, run the following command from the sandbox-ws project folder

svn status

The above command output should be similar to the following:

?     index.php

The (?) next to the index.php file indicates that svn detected that the index.php status is unknown i.e. it’s new and has not been added to the working copy yet.

Since svn doesn’t know the status of the index.php file, we should add it to the working copy, to do this run the following command:

svn add index.php

The output of the following command should be similar to the following:

A      index.php

As you may have guessed, (A) means that the file has been added to the working copy, the next step would be committing the changes to the repository which would result in incrementing the repository revision number by one.

Committing Changes

After adding new the index.php file to the repository, we’ll want to commit it to the repository for other developers to be able to update their working copies and take advantage of our newly added file. To do so run the following command:

svn ci -m "added index.php"

The output of the following command should be similar to the following:

Adding         index.php
Transmitting file data .
Committed revision 2.

I think that the above doesn’t need any explanation, but the following does, run the following command:

svn info

The output of the following command should be similar to the following:

Path: .
URL: file:///c:/repo/trunk/sandbox-ws
Repository Root: file:///c:/repo
Repository UUID: 50729929-acbb-d647-b00b-4f3555a6f6a3
Revision: 1
Node Kind: directory
Schedule: normal
Last Changed Author: Sandbox
Last Changed Rev: 1
Last Changed Date: 2009-01-23 16:52:06 +0200 (Fri, 23 Jan 2009)

Of course some of the data displayed by the following command will differ between you and me but what is interesting about the command is that it indicates that the revision number of the working copy is less than the current revision number of the repository which is currently is 2. The reason of this is that after our commit the repository revision number as we have said increments by one but the our working copy is now out dated, we need to update it so the revision number of the working copy is similar to the repository. To do so run the following command:

svn update

The output of the following command should be similar to the following:

At revision 2.

I hope that this article successfully cleared what subversion is and how to start using it, in upcoming articles we will dive into more advanced topics.