In Part 1 I walked through the installation of the Apache Web server. In Part 2 I covered the installation of Subversion and the integration of Subversion and Apache. This involved configuring an Apache Virtual Host to handle all the requests that come from the Subversion sub-domain (svn.yourcompany.com:81). We also configured dedicated logging for all Subversion HTTP requests through appropriate Virtual Hosts directives. Finally, we looked at browsing the Subversion repositories via a Web browser, but since we hadn't created any repositories, this task was pretty unexciting. In this section I'll discuss the installation of TortoiseSVN, a popular client-side Subversion tool. Through TortoiseSVN we'll be able to create our first repository and perform our first repository import.
What is TortoiseSVN?
TortoiseSVN is an amazingly easy to use and highly popular Subversion client for the Windows platform. Through extending Windows Explorer, TortoiseSVN commands are available anywhere within Windows by simply right-clicking. TortoiseSVN supports all the current Subversion protocols which include http://, https://, svn://, svn+ssh://, file:///, svn+XXX://. Using TortoiseSVN you can create, check out, update, and commit changes to repositories. You can also generate repository reports and view Subversion log files. We'll be installing TortoiseSVN on the server (in order to create the sample repository) as well as the client machine (so we can create working copies of the sample code).
Download the TortoiseSVN installer by pointing your Web browser to http://tortoisesvn.net/downloads. At the time of this writing the current version was 1.4.3. On the downloads page select the TortoiseSVN-184.108.40.20645-win32-svn-1.4.3.msi file.
Getting TortoiseSVN installed is just a matter of stepping through the installation screens. If you already have an older version of TortoiseSVN, you can install 1.4.3 on top of your old installation. The installer will handle uninstalling the appropriate files and adding any new ones. At the end of the installation you will be prompted to restart your server. Remember, at this time you should be installing TortoiseSVN on the same computer that is running your Subversion server. We'll install TortoiseSVN on the client (your machine) later.
Figure 29: TortoiseSVN installation welcome screen
Locate the *.msi file you just downloaded and double-click it to launch the installer. You'll be greeted by the TortoiseSVN welcome screen. Press Next to continue.
Figure 30: TortoiseSVN license agreement
Read the license agreement, accept the terms, and press Next to continue the installation.
Figure 31: Custom setup screen
The installer defaults to placing TortoiseSVN in C:\Program Files\TortoiseSVN\, which is fine. Keep all the default settings and press Next to continue.
Figure 32: TortoiseSVN is ready to be installed
TortoiseSVN is now ready to be installed on the server. Press Install to start the installation.
Figure 33: TortoiseSVN Installation Completion
After TortoiseSVN has been installed you'll see a completion screen. Press Finish to exit the installation.
Figure 34: TortoiseSVN requires server restart
As I mentioned earlier, TortoiseSVN requires you to restart your computer in order for the changes to take affect. When your computer has finished restarting you'll have TortoiseSVN installed and operating.
Creating Your First Repository
Figure 35: Creating your first repository
Remember the svnrepos directory we created in Part 2 (Figure 22)? It's been empty ever since as we finished preparing the Apache Virtual Host that points the svn.yourcompany.com:81 domain to E:\svnrepos. You might also recall I steered you away from ever manually editing the contents of svnrepos as it's meant to be managed by the Subversion server. The one exception to this rule is the actions required to create the initial repository. To accomplish this, first create a new folder called sql. As an example we're going to set up versioning on a few really important SQL files. After creating the directory, right-click it and access the TortoiseSVN options in the right-click menu. Select the Create repository here option.
Figure 36: Selecting the filesystem type
Every Subversion repository is created using one filesystem type or another (how data is stored in the repository). Berkeley database (BDB) files are the original filesystem type having been around for quite a long time. The Native filesystem (FSFS) is a relatively new type but comes with a lot of benefits not found in BDB. It's outside the scope of this text to compare and contrast each type; if you're interested in learning more I recommend reading this Web page (http://svn.collab.net/repos/svn/trunk/notes/fsfs). The important thing to understand is Subversion manages the entire historical makeup of each repository using a flat file system. Personally, I recommend setting up all Subversion repositories using the Native filesystem (FSFS). Select the FSFS option and press Ok.
Figure 37: The new repository has been created
After a second or two TortoiseSVN will display a success message indicating the repository has been created. Behind the scenes, several directories and files were added to the sql folder that are needed to manage the new repository. However, our repository, for all accounts and purposes, is still empty. Before we change this by importing our sample SQL code, we need to stop and think about how to organize our data. There are several organizational structures common in Subversion. The most popular involves creating a few top-level directories: trunk, branches, and tags but what does these mean? The trunk directory is the main line of code for your development team. This is akin to the root folder of one of your Web sites or projects. This directory is also the most fluid receiving frequent bug fixes, updates, and revisions as your code evolves over time. The branches directory allows developers to branch-off or split the main line of development (the trunk). For example, let's say your team has written a really useful application for the marketing department. After 6 months of use marketing decides they need some relatively significant changes, enough to warrant a new release of the application. However, there are still a few outstanding bugs with version 1. Which project does your team, and more importantly each member of your team, focus? With branches, two senior developers can split version 1 from the trunk and start writing version 2. This development occurs without affecting the trunk whatsoever. In fact, the junior developer can focus on the version 1 bugs, at the same time, committing fixed code to the trunk and not negatively impacting version 2. When the senior developers have finished version 2 they can merge their work into the trunk picking up the bug fixes from the junior developer. Branches, whether they are configured as a branches top-level folder or not, are one of the greatest benefits to Subversions copy-modify-merge model. Almost as useful as branches, tags are snapshots of the repository at a particular point in time. The most common use of tags is creating releases or builds of your project. You can view tags as another synonym for milestones; when your team reaches a particular milestone it may be beneficial to take a snapshot of the trunk and give it a meaningful name like release-1.0.3 or version-1.5.
Figure 38: Opening the repository browser
Now that you understand a little more about the trunk, branches, and tags directories we need to add them to the sql repository. The easiest way to do this is to use TortoiseSVN. Using Figure 38 as an example, open the Repository Browser using the TortoiseSVN right-click menu.
Figure 39: The Repository Browser
The Repository Browser (Figure 39) is a nifty tool allowing you to perform many actions on your repository. Some pertain to managing the repository while others enable simple methods of reporting repository activity. The first step to browsing the sql repository is to edit the URL address so it reads http://svn.yourcompany.com:81/sql/. The URL you use may be slightly different depending on how you configured things in Part 2. Once you've entered in the correct URL you should see the full HTTP path to the sql folder listed in the lower pane. Since the repository is empty, you cannot expand it to show it's contents. We're now ready to create the trunk, branches, and tags directory. Using Figure 39 as an example right-click the sql folder and select Create folder.
Figure 40: Creating the top-level trunk folder
Enter the folder name (trunk) in the window provided.
Figure 41: Entering comments for the trunk folder creation
Each time you make a change to the repository you are prompted to enter a log message pertaining to what you are adding, changing, deleting, etc. Enter an appropriate log message (Figure 41) and press Ok.
Figure 42: The trunk folder is now visible in the repository
The sql repository now has the trunk folder listed. To create the branches and tags directories repeat the above steps changing the log message for each folder you add. When are you finished, your repository should look similar to Figure 43 below.
Figure 43: Final top-level folder configuration
With the top-level folders trunk, branches, and tags created we finally have our sample sql repository configured correctly.
Figure 44: Checking the repository with a Web browser
Figure 45: Drilling down into the repository
Before we move on let's check our repository using a Web browser. You should see a screen similar to Figure 44 which lists all the repositories in the E:\svnrepos directory. Using the links provided you can drill-down into the sql repository (Figure 45) viewing any versioned files and directories. Notice how the repository is at Revision 3. This is because any change made, whether it's the addition of a directory or a change to an existing file, increments the overall revision number.
Download the Sample SQL Code
I've created some sample folders and files - a very basic "project" - to make it easy to add content to the sql repository. You can download them from here (http://www.aaronwest.net/downloads/download.cfm?token=46D4A473-CDB5-5CCF-EB5E100FA1187318).
Import Sample SQL Code to the Trunk
Figure 46: Importing code to the repository
Extract the SQL files from either zip to a temporary folder, being sure to retain the directory structure. You should have a main folder called SQL Files with several sub-folders and files. We're going to import the SQL Files folder into the repository trunk. This will cause the contents of the SQL Files folder - not the folder itself - to be imported into the trunk. The directory structure contained with the SQL Files folder should be retained as the contents are imported. Right-click the SQL Files folder, access the TortoiseSVN menu and chose Import.
Figure 47: Selecting the sql trunk and entering a log message
To import the SQL files select the trunk folder of the sql repository. Enter an appropriate log message and press Ok.
Figure 48: Import results
TortoiseSVN displays a log of each and every directory and file that was added to the trunk as well as indicating what the new revision number is. Press Ok to close the window.
Figure 49: The trunk folder is now populated
To view the changes you just made open the Repository Browser and select the sql repository. You may have to refresh the lower pane for the changes to show up.
Figure 50: Viewing the imported files in a Web browser
In addition to viewing the changes in TortoiseSVN's Repository Browser you can also view the changes in a Web browser. Drill-down into each folder and view a couple of the SQL files. If the files are basic text, like those I've provided, browsers like Firefox will display the contents of the file directly in the browser. Now that the trunk has versioned copies of files and directories, the repository can be checked out by any user who has a Subversion client (like TortoiseSVN) and access to http://svn.yourcompany.com:81/sql/.
Creating a Working Copy of the Repository
Figure 51: Checking out the repository
Up to this point all our work has been focused on the development server. We're now ready to move over to a client machine, install TortoiseSVN and create a working copy of the sql repository. Revisit the TortoiseSVN installation instructions if needed and return here once TortoiseSVN is installed on the client machine. The first step to setting up a working copy is to create a folder where the project will live. In Figure 51 above, I've created a folder called SQL Files on my desktop. Incidentally, this probably isn't a great place for the project but will work fine for demo purposes. With the SQL Files folder created, right-click the folder and select SVN Checkout.
Figure 52: Selecting the repository URL and Checkout directory
TortoiseSVN prompts you to select the URL of the repository you want to checkout to the client machine. Be sure and select the trunk folder of the repository. The Checkout directory should already be pre-filled so all that's left is determining which revision we want. The HEAD revision refers to the latest and greatest contents of the repository. If for some reason you wanted an earlier revision you can select the Revision radio button and type the revision number in the box provided. For our purposes leave the HEAD revision selected and press Ok.
Figure 53: The working copy is populated with repository contents
TortoiseSVN will access the repository URL and download the entire contents of the trunk adding all files and folders to the local working copy. With this in place, you can now work on the files on your local computer making any changes you need. Changes you make on your local computer are not reflected in the repository on the Subversion server until you commit them. Let's take a look at this process.
Committing Changes to the Repository
Figure 54: Committing a change to the repository
Navigate to the FolderOne folder of your working copy and open up SQLFile1.sql. Make any change you want to the file and save it. Return to the FolderOne folder and press F5 to refresh Windows Explorer. The icon for the changed file should now look a bit different than the others. The exclamation point icon indicates you have a file changed in your working copy that has not been committed to the repository. This is extremely handy as you make dozens of changes across many files in a project. Using Figure 54 as an example, right-click the changed file and select SVN Commit.
Figure 55: Selecting which file(s) to commit and adding a log message
As always, TortoiseSVN prompts you to enter a log message about what you have changed. The lower section of the window will list any local files that have changed. This gives you the ability to be selective about what you want to commit.
Figure 56: Commit results
Once the files have been committed to the remote repository, TortoiseSVN shows you a status message indicating the new revision number.
Getting Changes from the Repository
Figure 57: Getting changes from the repository
The last piece to the round-trip cycle of revision control is retrieving other developers changes from the repository. This is know as updating your local working copy. To do this with TortoiseSVN you select your local project folder - in this case SQL Files - right-click the folder and select the SVN Update option. TortoiseSVN will poll the remote Subversion server and compare your local copy to that of the repository. If the repository has changes you don't, TortoiseSVN will download those changes and display an appropriate status message.
In this part of the text I covered key aspects to creating and managing a sample Subversion repository. First, we installed the TortoiseSVN Subversion client on the server and used it to create our sample repository. Along the way I discussed a common Subversion repository strategy - creating the trunk, branches, and tags top-level folders. Then, I walked through the steps to importing sample SQL code into the repository trunk. And finally, I covered working copy creation, committing changes to the repository, and requesting updates from the repository.
In Part 2, I covered the integration of Subversion and Apache which included creating custom logs of all Subversion repository access. To learn how to further refine the Subversion - Apache hook, adding more meaningful logging and authenticated repository access, check out Part 4: Subversion and Apache - Better Logging and Authenticated Access. To learn more about accessing Subversion repositories from the client-side perspective, check out Part 5: Accessing Subversion Repositories With Subclipse.
5 related blog entries
- Part 5: Accessing Subversion Repositories With Subclipse (March 15, 2007)
- Part 4: Subversion and Apache - Better Logging and Authenticated Access (March 14, 2007)
- Part 2: Installing Subversion 1.4.2 and Integrating Subversion With Apache (March 13, 2007)
- Part 1: Installing and Configuring Apache 2.0.59 (March 12, 2007)
- Configuring a Development Environment with Apache, Subversion, TortoiseSVN, and Subclipse (March 12, 2007)