Playing around with Subversion with a test repository

• July 12, 2008
• James Skemp
• general programming, software, tutorials / guides

I've flirted with source/version/revision control since September 2006 (with Subversion), but have never really dug in to actually do anthing with it. But now, that changes.

The basics of Subversion

The basics are that you have a repository to store files within. Files in the repository are not directly modified. Instead, you can check out a working copy of the files to work on. You can then check in (aka commit) your working files, at any time, so that they become a part of the repository. When you do this, a new revision is created. If multiple people are working on the same repository, you'll also need to update your working files and handle any conflicts.

Getting started with Subversion

I've already covered this in previous posts, for Windows installations.

• Subversion
• TortoiseSVN

These both cover Windows Vista installations, but an older guide exists for Windows XP.

TortoiseSVN isn't required, but I highly recommend it, and it's how I'll be working through this.

Creating a test repository 

The first thing to try is a 100% test repository. Again, this will be what keeps track of file versions.

Determine where you'll store your repositories. I have a second hard drive that I'll be using, so my repositories will be stored in B:\repos\ . Substitute your directory structure whenever you see this.

Next, create a new directory under B:\repos\, called repoTest.

Right click on the directory and select TortoiseSVN > Create repository here... (See this.)

When prompted, select Native filesystem (FSFS) for the repository type. (See this.)

With that, the repository is created.

Now that you've got a repository, it's time to check out a version you can work with.

Creating a working directory

Right-click on the repoTest directory and select SVN Checkout... (See this.)

You'll be prompted for the URL of the repository (which should be correct - in this case, file:///B:/repos/repotest) and a Checkout directory. This directory is where you'll store your working copy. I created a new directory B:\projects\repoTest\.

Leave all other options as they are and press OK to continue.

With that done, you should be shown a window stating that the checkout has finished.

If you now browse to your checkout directory (in my case, B:\projects\) you'll notice that the repoTest directory has a new icon - a green circle with a check.

Adding files to the working directory

Let's now create a text file called 'file number 1.txt' in the working directory. For now, leave the file blank.

Now go back up to the B:\projects\ directory and right-click on the repoTest folder. Select SVN Commit... (See this.)

Our new file is displayed in the lower half of the window that appears. Check the box next to the file name. Next, enter a meaningful message in the first text box. For example, "First check-in."  (See this.)

Press OK to continue.

A new window will appear showing that our file has been added and sent. We're also given a revision number, in this case, 1. (See this.)

Checking out another copy 

Now let's go back to our repository and checkout another copy.

This simulates another user working on our repository.

Once again, we can browse to B:\repos\ , right-click on our repoTest directory, and select SVN Checkout... Or, we can also select TortoiseSVN > Repo-browser . This browser enables you to see all the files in the repository, as well as additional details, like revision. (See this.)

If you right-click on the repository, you can select Checkout...

Either way you checkout the repository, do so to a new folder, such as B:\projects\repoTest2\ . (See this.) Press OK.

This checks out all files currently committed to the repository. So, when we browse to our new working directory, we'll see 'file number 1.txt' .

Where we're at 

Right now we've got a single repository and two working directories. This is similar to what one might see if two individuals are working on a project.

So, Lisa is B:\projects\repoTest\ and Trish is B:\projects\repoTest2\

Let's treat these imaginary users as human beings, and call them by there names from here on out.

Lisa adds new files

Switch to Lisa's repository at B:\projects\repoTest\ . Let's say she creates two new files, called "file number 2.txt" and "file number 3.txt" in this directory.

She also adds some text to file number 1, such as "Lisa has made a modification to this file."

When she modifies file number 1, note that it now has a different icon, as the file has changed.

Now we assume that she wants these to be a part of the repository, so in order to get them in there, she'd have to commit these changes.

Select both of the new files and select TortoiseSVN > Add...

In the prompt that appears, verify both checkboxes next to the file names are selected, and press OK. You'll then be told that both files are added.

You may have to refresh Explorer, but when you do so, you'll notice that the two new files have new icons - little blue plus signs.

Right-click in the repoTest directory, or on the repoTest folder, and select SVN Commit...

This time you'll see that you've modified one file and added two others. Make sure you put in a message, such as "Lisa updated file 1 and created files 2 and 3." You may note that when you type file, you've got the option to auto-complete with the file names. Pretty nice, eh? (See this.)

Go ahead and press OK, verify it completes, and press OK again. (See this.)

What about Trish?

Now Lisa is up to date with the repository, since she's the only one making changes. But what about Trish?

Let's switch to Trish's directory, B:\projects\repoTest2\ . She still just has file number 1.txt and it's still empty.

Let's go ahead and open her version of file number 1.txt and make a change. For example, add "Trish modified this file."

Right-click on the repoTest2 directory, or within it, and select SVN Commit... Make sure you enter a message!

If you try to commit, the commit will fail. Unfortunately, Trish's version is out of date (it says so). (See this.)

Getting Trish up-to-date

We have a couple of options for getting Trish up-to-date. The first is to right-click on 'file number 1.txt' and select TortoiseSVN > Check for modifications. We'll see that Trish's version has been modified, and by double-clicking, can see what modifications took place.

However, that's what was modified from the version she checked out.

Press the Check repository button and you'll see an even newer version, the version Lisa checked out.

If we now double-click on the file we'll see Lisa's changes compared with our changes.

So now that we've got a conflict, what do we do?

Let's get an updated version of this file by right-clicking on the file and selecting SVN Update.

When we do so, we'll be told that a conflict exists, and will have a couple of files created in our working directory - 'file number 1.txt.mine,' 'file number 1.txt.r1,' and 'file number 1.txt.r2.' In addition, 'file number 1.txt' wll have a small warning icon.

Right-click on this file and select TortoiseSVN > Edit conflicts.

From within TortoiseMerge, we can right click on either of the differences and select a couple of options.

1. Use a specific text block from one file or another.
2. Use the whole file from one or another.
3. Put our text before/after their text.

The merged/final version will display in the bottom half of the window.

For now, let's go ahead and put Lisa's text before Trish's text.

Right click on the changed block from 'mine' and select 'Use text block from "theirs" before "mine."

In the merged version, you'll see Lisa's text before Trish's. Close out of TortoiseMerge and save your changes when prompted, or press the save icon, or select File > Save.

Trish's working copy has now been modified with the updated text, however the file still is in conflict.

Right-click on the file again and select TortoiseSVN > Resolved... Verify that 'file number 1.txt' is checked, and press OK.

Once you've done so, the extra files are removed from the directory. You'll now need to commit the file back into the repository. Now that the base copy is the same revision, the commit will complete.

What Trish should have done

However, there's still an issue with Trish's copy of the repository. She has no file 2 or 3.

What Trish really needs to do is update her copy. She can do so by selecting SVN Update, after right-clicking on/in the repoTest2 folder.

This will allow her to get all the updates that have happened since she first grabbed a copy.

She can also, from this window, see a log (by pressing "Show log...") of revisions, with messages.

Workflow with more than one developer

Therefore, based upon this, it's a very good idea to make sure you're pulling updates from the repository on a regular basis.

While there may indeed be times when you don't want to do this, this will allow you to see what other developers have been working on.

She can also use a number of menu items to check on the repository without making commits. The log (Show log), repository browser (Repo-browser), and modifications (Check for modifications) can all be accessed at the directory or file level.

In the case shown below, Lisa has made two additional revisions since Trish last checked files out, including adding two new files and modifying two that Trish already has.

If Trish hasn't made any changes, it's easy enough to SVN Update and get everything she needs. If she didn't modify any files that have changed, then she won't have to handle any merging of changes. If she has, then she'll just have to handle the conflict, which can involve just ignoring it by using her version (Mine), if she's actually got the version that should be used.

Deleting our working directories

At this point we've covered what we need to cover for working with Subversion, using a test repository, and two working directories.

We can clean-up by deleting the B:\projects\repoTest\ and B:\projects\repoTest2\ directories.

Since our repository still exists, we can still get a working copy of the repository. However, if we delete the repository directory, B:\repos\repoTest\, our repository is gone.

Since we don't need it anymore, go ahead and delete this directory.

To conclude ...

Probably the best way to start with Subversion is to actually work on a dummy repository, as I've done above.

Next time

Next time I'll move an existing Web project into Subversion, since it's definitely time.

Questions, comments, concerns, definitely appreciated.

• subversion
• svn