Throughout the parts of this text I've used TortoiseSVN to perform all repository actions. This was mainly due to the simplicity and ease of use TortoiseSVN affords. TortoiseSVN is also handy when versioning assets that aren't code-related like spreadsheets and general documents. When working with code - ColdFusion for instance - there are other Subversion clients that work just as good as TortoiseSVN and don't require you to leave your development environment to request repository updates or commit changes. One such tool is Subclipse which is built on the open-source Eclipse platform. Eclipse is an extremely popular Java-based programming tool that works with just about every modern programming language. I use Eclipse and Eclipse plugins like CFEclipse on a daily basis to manage my code. In the this section, I discuss installing, configuring, and using Subclipse, the Subversion plugin for Eclipse.

What is Subclipse?

Just like TortoiseSVN, Subclipse is a Subversion client tool allowing you to create and manage working copies of versioned resources. The difference between the two is Subclipse is designed around the open-source Eclipse Platform. In order to manage and work with repositories using Subclipse, you must first download and install Eclipse. The rest of this section assumes you have Eclipse 3.2 installed and operating properly and walks you through installing Subclipse and using it to manage Subversion repositories.

Installing Subclipse

Figure 65: Find and Install Eclipse Plugins

The first step to installing most Eclipse plugins is to first access the Find and Install option under Help  Software Updates. This menu option allows you to create a new update site where Eclipse will look for installation files for plugins you already have installed or are interested in installing.

Figure 66: Selecting the new features radio button

You can elect to search for updates to currently installed features or search for new features to install. Since we're installing Subclipse for the first time, select the Search for new features to install radio button and press Next.

Figure 67: Current remote update sites

Eclipse shows you a list of all the remote update sites you have configured. Press the New Remote Site button to add a new site for Subclipse.

Figure 68: Adding the Subclipse update site

In the modal window that appears, enter a name for the update site (Subclipse 1.2.x) and the update URL ( Press Ok.

Figure 69: Selecting the version of Subclipse to install

A new Subclipse site should be listed in the Updates window and it should be checked. Expand the entry until you see the versions of Subclipse listed. Only the latest version of Subclipse will be listed if the check box at the bottom of the window for "show the latest version only" is selected. Select the latest version and press Next.

Figure 70: Subclipse License Agreement

Accept the terms of the Subclipse license agreement and press Next.

Figure 71: Subclipse installation location

Subclipse needs to be installed in the folder where Eclipse is installed. By default this is C:\Program Files\eclipse. Press Finish and the Subclipse installation files will be downloaded.

Figure 72: Subclipse installation verification screen

Press Install to begin the installation of Subclipse.

Figure 73: Restarting the workbench

In order to finish the installation of Subclipse you should restart the Eclipse workbench. Press Yes to do so.

Figure 74: Verify the installation of Subclipse

To verify Subclipse was installed successfully open the perspectives window using Figure 74 as a guide.

Figure 75: SVN Repository Exploring

Subclipse is installed and available if the SVN Repository Exploring perspective is listed.

Creating an Eclipse Project Connected to a Subversion Repository

With Subclipse installed we can now create a repository location inside of Eclipse that points to the Subversion server we've set up in previous parts. Select the SVN Repository Exploring perspective and press Ok to open it.

Figure 76: Creating a repository location

If the SVN Repository tab (which is a "view") does not display, select Window - Show View - SVN Repository. Right-click the empty space in the SVN Repository tab and select New - Repository Location.

Figure 77: Specifying the repository URL

To work with repositories, we need to tell Subclipse where they are located. Type the URL to the sample repository we've been working with throughout this text ( and press Finish.

Figure 78: SQL repository contents

Subclipse introspects the repository URL you entered and shows the repository contents. Expand the repository to the trunk folder to ensure the contents of the repository are listed correctly.

Figure 79: Checking out the repository to a local working copy

In order to begin working with the repository we must create a local working copy. In the next few steps we'll direct Subclipse to create a new Eclipse project that points to the trunk folder of our sample SQL repository. Start this process by right-clicking the trunk folder and pressing Checkout.

Figure 80: Checking out the repository as a new Eclipse project

Next, select the first option for checking out the trunk folder as a new project using the project wizard. Press Finish to continue.

Figure 81: Selecting the project type

This screen allows you to select the type of project you are creating. Since our project relates to SQL files, just select the General Project type. Press Next.

Figure 82: Naming the new project

We're now prompted to enter a name for our project. Keeping with the same names we've been using thus far, give the project the name SQL Files and select the location. The default location is fine unless you have a need to store your files elsewhere. Press Next to advance to the Project References screen. Our project doesn't need to reference any existing Eclipse projects so leave all boxes unchecked and press Finish.

Figure 83: Console tab displays checkout log

After pressing finish Eclipse will create the new project in the Navigator tab and Subclipse will access the remote repository and check out the trunk to the root of the new project folder. If you have the Console tab open, you should see log messages from the checkout action performed by Subclipse.

Figure 84: New project listed in the Navigator tab

Switch to the Navigator tab and you should see the new SQL Files project listed. Expand the folders and you'll see all the files Subclipse checked out as well the version number for files. Also shown are special Subclipse icons next to folders and files indicating their status in relation to the repository.

Committing Changes to the Repository

Figure 85: Subclipse Team window

In order to work with the Subversion repository you need to access the Subclipse commands. Much like TortoiseSVN these commands are located in a right-click window - well, most of them at least. Right-click the project folder and select the Team option. A new menu will appear showing all the things you can do. You can commit changes, update your local working copy with changes from the repository, show the history of the repository, create branches and tags, and revert to previous versions just to name a few options. To see how commits work, open the SQLFile1.sql file and make a change.

Figure 86: SQLFile1.sql has been changed locally

Once you've saved your change, an asterisk icon will display to the left of SQLFile1.sql indicating it has been changed locally and differs from the same file in the repository. To commit your change you have two options. You can right-click the file you changed and select Team - Commit. This will allow you to commit only that one file. To see ALL files that have changed locally, right-click the project folder and select Team - Commit (Figure 85).

Figure 87: Selecting files to commit

The bottom pane will show you any file that can be committed. You can ignore the .project file. Make sure only SQLFile1.sql is checked, enter a comment, and press Ok.

Figure 88: Authenticating with the repository

Subclipse will prompt you for your username and password (if you followed the steps in Part 4). Enter your username and password and press Ok. You can elect to have Subclipse save your password if you don't want to type it over and over again. You will definitely want to do this at some point, as it gets very annoying typing your password for each and every "authentication-required" action taken on the repository.

Figure 89: Commit results

Once the commit action has finished the version number listed to the right of SQLFile1.sql should increment to 7 (based on the actions we've taken thus far in the various parts of this text). The Console tab, if you still have it open, will list the Subversion command used to perform the commit and the results (a new version number).

Getting Changes from the Repository

Repository updates work pretty much the same as commits, you just select the Update option of the Team menu after right-clicking the project directory. To view the latest actions taken on the repository you can display the repository history. Right-click the project directory in the Navigator pane and select Team - Show History.

Figure 90: Viewing the repository history

The History tab will list the history of actions taken on the repository. This includes actions you've taken using TortoiseSVN and Subclipse as well as any actions taken by others.

Synchronizing a Working Copy with the Repository

Figure 91: Team Synchronizing

One final feature of Subclipse I want to discuss is the Synchronize with Repository option. Select this option by right-clicking the project folder and selecting Team - Synchronize with Repository. Subclipse will let you know the feature is part of the Team Synchronizing perspective in Eclipse. Press Yes to continue. The Synchronize with Repository option allows you to view changes you need to download (through an Update request) and changes you need to upload (through a Commit). An example is shown in Figure 91. As you can see, I have made a change to SQLFile1.sql while someone else has changed SQLFile2.sql. To update my local copy - receiving the new SQLFile2.sql file - and commit my own changes I have a few options. First, I could right-click individual files I need to download and select Update in order to retrieve them. Or, to download all updates, I could right-click in the whitespace and select Update. Commits work very much the same. I could right-click individual files I need to commit and select Commit, or I could right-click the project folder and select Commit to commit all my local changes at once. In either case, Subclipse will prompt me to enter comments before sending my changes to the repository.


In this part, I walked you through installing Subclipse and creating a working local copy of the sample repository files. I also discussed the most commonly used features of Subclipse: updating your working copy, committing your own changes, showing the repository history, and synchronizing between your working copy and the remote repository. I'm a pretty big fan of Subclipse and the Eclipse environment in general. I use the Eclipse platform on a daily basis to manage workplace code and personal code. However, TortoiseSVN is also a nice Subversion client - especially when used on the server that hosts the Subversion server and repositories. Add these tools to an "Apache-based" Subversion environment and you have, in my opinion, a very nice development set up on the server-side and client-side.

I hope this text has provided you with a good overview of how to set up and configure your development environment with Apache, Subversion, TortoiseSVN, and Subclipse. As I said in the introduction and disclaimer, the implementation I describe is not the only way to configure a source control environment. I encourage you to consult other resources on how to set up and further refine your own environment. To that end, I have included various resources that I feel are useful on this topic. Some of these I used as a reference in deciding how to configure the development environment where I work. Others are useful, in general, for anyone wanting to configure a localhost Web development set up. Finally, there are several resources listed that expand on many of the ideas I presented in this text. If you're interested in learning more about source control management I highly recommend checking them out. Good luck, and have fun!

Additional Resources


Collins-Sussman, B., Fitzpatrick, B., & Pilato, M. (2004) Version Control With Subversion
O'Reilly Media

Collins, S. (2006) The ACME Guide (3rd ed.)
Stephen Collins

Mason, M. (2006) Pragmatic Version Control Using Subversion (2nd ed.)
Pragmatic Bookshelf


Subversion FAQ

Subversion Cheat Sheet

Charlie Arehart's Subversion Resource List

Dave Shuck on setting up Subversion for his development team.

Rob Gonda explains differences between SVNServe and Apache.

Brian Kotek on using Subversion (svnserve) locally.

Net Batchelder discusses Subversion branching strategies.

Brandon Harper discusses best practices for Subversion branching.

Rick Osborne's CFDIFF


Apache HTTP Server

Subversion Server Packages




CFEclipse (ColdFusion plug-in built on the Eclipse Platform)

Aaron West's Gravatar
About this post:

This entry was posted by Aaron West on March 15, 2007 at 10:14 PM. It was filed in the following categories: ColdFusion, Apache, Subversion, Eclipse, CFEclipse, TortoiseSVN, Subclipse. It has been viewed 63909 times and has 23 comments.

5 related blog entries

23 Responses to Part 5: Accessing Subversion Repositories With Subclipse

  1. Sue W

    Hi Aaron,

    Thanks for this. I just had to re-install Eclipse & plugins because something went horribly wrong on my system, and although I had done this a while ago (& made a doc for others to follow) it is still reassuring to go along with someone else's steps.

    Keep up the good work!

  2. I'm glad you found it helpful Sue. Thanks for your comments.

  3. Hey Aaron,

    I noticed that you set up your repository via Tortoise. We plan on using Subclipse as our client of choice. If I don't set up Tortoise on our Subversion server, do know if it is possible to create our repository via Subclipse? If not, would you recommend installing Tortoise simply for the purpose of creating the repository? And can I assume that the repository will work the same regardless of which method is used to build it?


  4. Jim, you can use whichever tool you want - TortoiseSVN or Subclipse - to set up your repository on the server. TortoiseSVN has advantages from the server perspective in that a) you don't have to have remote access set up and working yet and b) you definitely want some sort of local (on the server) way to manage your repositories should remote access fail.

    I guess I would recommend installing TortoiseSVN on the server and using that to get the ball rolling. Then, when you have things straight, developers can begin utilizing Subversion with the Subclipse plugin. Make sense?

  5. Yes, makes sense ... thanks. But I was under the impression that even if you wanted to, you can't set up a repository through Subclipse. Does this sound accurate?

  6. I was thinking you could create repositories using Subclipse but upon further review it doesn't look like that's possible. And it makes sense too, since Subclipse hooks to existing repositories only and does not allow one to introspect a Subversion server. So, your best option is to use other Subversion client tools like TortoiseSVN. Thanks for bringing this up Jim.

  7. Thanks Aaron. I've used TortoiseCVS, but haven't used Tortoise for SVN. I will definitely give it a whirl ;)

  8. Shaji

    I found you on Shlomy's blog.

    Thank you for sharing this. I use Eclipse and CFEclipse and VSS plugins. I will try subversion..

  9. Shaji, let me know what you think once you've have a chance to work with Subversion. I think you'll be very happy with it, especially coming from VSS.

  10. As mentioned on this weeks ColdFusion Weekly, there is also SmartSVN ( as an alternative to TortoiseSVN. A free and paid version are both available, and it is a cross platform Java utility. Might be worth a look.

  11. Great article!

    I've given well deserved credit on my own blog :)

  12. Mark

    i do have one question, and i apologise in advance if it's a not so bright one :-) .. If you set up Tortoise SVN then go ahead and setup subclipse is it creating a seperate repository ? Using this would i have to update the subclipse repository then go back and update Tortoise as well ? Or is subclipse merely referencing the same Tortoise set.

    if that doesn't make any sense just let me know

  13. Mark, in most cases yes, you would be creating two separate repositories. One managed with Subclipse and one managed with TortoiseSVN. I'm not sure why you would want to do this, unless it's to try and use features of TortoiseSVN and features of Subclipse on one repository. Personally, I would just pick the right Subversion client for the job and stick with it. For code-specific repositories, I recommend using Subclipse exclusively. For non-coding projects you might want to use a Subversion client outside of the Eclipse environment. For this I recommend TortoiseSVN or SmartSVN (I'm recommending SmartSVN blindly as I have no direct experience with it).

  14. David Lincoln

    Just a thanks for publishing this. I have been using Subversion on our local network for about a year. I wanted internet access to my source repositories but not being familiar with Apache, I wary of stumbling into a "black hole" that some software configuration projects seem to impose on all available work hours. You saved my from a black hole! -dwl

  15. David, thanks for the comment. I've not saved someone from a black hole before; that's pretty friggin sweet.

    Don't feel bad about the barriers to getting into Apache - you are by no means alone. It took me a few years to take the leap and become comfortable admin-ing an Apache Web server. I'm still learning. ;-)

  16. DK

    thanks... this series really helped me get svn up fast! The official docs were a bit heady lol.

  17. Jason

    Thanks Aaron..this helped me out a lot!
    I was hoping you could answer a question for me though...After I edit files on my local project, then commit them - is there a way through subclipse to have the remote repository update the actual file without remoting into the server and doing right click, svn update?

    Thanks so much!

  18. Jason, I'm not sure what you mean by "to have the remote repository update the actual file..." When you commit files, the remote repository IS updated and holds the new revision. If you are wanting other working copies - like members of your team - to get your committed updates they will have to run an svn update. Let me know if this helps or if I'm missing the point of your question.

  19. Jason

    What I mean was the actual file in the directory..for example...

    If I have my root at d:\inetpub\wwwroot\
    and my svn repository in c:\svnrepository

    when I commit a file, its not actually updating the file in d:\inetpub\ I can't actually test it without having a local copy of coldfusion (which I don't really want)

    does that make sense? basically, it seems to be updating the repository, but not the actual file from the website

  20. Jason, I think I get what you're saying. You don't want to run a local copy of your Web site (though with the developer version of ColdFusion I would recommend it) but you want your *real* site updated when you commit changes to your Subversion repository. Is this correct?

    In terms of having your Web site code automatically updated when you commit, I don't think this is possible. And honestly, it kind of goes against the idea of source control management. However, I know folks who install a Subversion client (like TortoiseSVN) on their production server, hook it to their repository, and run an "update" statement when they want to bring new code into the production environment. This is a common way teams handle code deployment.

    Personally, I prefer other mechanisms like using Subversion's export feature in conjunction with ANT. This allows you to export your repository to a temporary directory and "sync" the temporary directory with your actual Web site. New files would be added to your Web site, updated files would be, well, updated, and files removed from the repository would be removed from your site. This type of workflow provides the highest level of control and while not fully automated - which you seem to desire - it's the best solution in my opinion (whatever that is worth).

  21. Greg

    I may be misunderstanding Jason, but I think the functionality he is looking for would be a post-commit hook in Subversion.

    We commit via Subclispe, then post-commit auto-updates a remote version of the project's "public" website, which is just a working copy on the remote server which only gets updated (no direct coding).
    Theoretically, each developer can have a "personal" working web site updated from branch commits while under developement with the "main" project site only being updated upon a commit to trunk so that it is always stable.

    Used in combination with Trac, it's a nice setup.

  22. Greg, thanks for your comments. What you suggest sounds exactly like what Jason is looking to do.

  23. Shaji

    If upgrading to apache 2.2 and Eclipse crashes, read at

    It happened to my co-worker today and read his blog at