Add SVN support to your Eclipse installation

UPDATE March 2009:

this installation method has been superseded in later versions of the IDE, and the connector and all other SVN components are now very easy to install, which kind of invalidates this article. However, the rest of advice regarding the use of SVN in Eclipse is still valid.

Surprisingly, Eclipse comes by default with CVS support only, which is not very use(ful|d) at this point. You can do all your SVN duties from outside Eclipse, using something like kdesvn, TortoiseSVN, etc, but it is really powerful to be able to do everything from Eclipse. Specially for comparing between versions, checking the changes on one file, etc, it's really handy.

Unfortunately, the installation procedure is horrible and confusing. So no wonder everybody just opt for using external tools. I have installed it several times in several computers and using different operating systems, and I always forget how to do that. But this time I decided to write it down so that not only I can remember how to do that, but also people who are using Eclipse with FDT, Flex, etc... can benefit from SVN without having to resort to external tools.

I will use Eclipse Ganymede which uses a slightly different naming for installing new features, but you will probably find your way if using an older version of Eclipse. If not, just post a comment and I'll try to help :-)

A bit of background

(aka Why can't I just select a new feature to be installed and have it Just-Working?) It seems that because of bizarre licensing problems they can't distribute the whole feature in just one file, but they had to split the SVN support in two parts: the plug-in itself, which talks to Eclipse and that is distributed from the Ganymede update site, and the SVN Connector, which deals with the SVN server and all that, and is NOT distributed from the eclipse servers, but from Polarion. So that's why the installation process is somehow divided in two parts.

Installing the plug-in

Go to Help -- Software Updates -- Available Software

Enter "svn" in the field which says "type filter text".

When it shows the matches, check the feature called "Subversive SVN Team Provider"

Click Install..., and then Finish.

It might ask you to restart the workbench; you can do that if you feel better that way.

Note: if you can't get any result when entering "svn" in the field, you might need to add to the list of software sites so that you can install the plug in.

Installing a connector

Wooohoo! You have the Team Provider installed, but it is absolutely useless without a connector. Let's install one. Where do you get connectors from? Good question. Somewhere in Eclipse literature you can find a link to this page, which provides links to update sites which will enable you to download one of these mysterious connectors.

What really matters here is that the update site url is

Copy and paste that link and in Eclipse go to Help -- Software Updates -- Available Software

Click on Add site..., and paste the url you just copied. Accept and it should load the available installable features at that location.

Check the following two:

  • Subversive SVN connectors
  • SVNKit 1.2.0 Implementation (or the highest available version)

and click Install..., and Finish.

Now it would be a good idea to say yes when it asks you to restart the workbench.

Selecting the connector

Not only do you have to install the connector, you might need to tell Eclipse that you want to use the connector. Just for being safe, once you have restarted the workbench, go to Preferences -- Team -- SVN -- SVN Connector.

And make sure that SVNKit 1.2.0 (or the one you selected before) is selected.

Alternative methods

The official method and support page from Polarion is here, just in case they changed YET again the install method in Eclipse. It seems there can't be a new Eclipse release without changing the way of installing new features, as if it wasn't hard enough to install Subversive...

Using SVN in Eclipse

You might probably be wondering how to use this fantastic thing now. Well, you obviously need a SVN repository to begin with, but if you've followed until here, you know what we are talking about. So let's create a project to show how to start using SVN here.

Right click over the Project Explorer and select New... -- Project... from the pop-up menu. You should have a new option for SVN in the project types list. Open the SVN folder, highlight Projects from SVN and click Next.

Now enter the SVN repository details, which you should already know: the url, user, password, etc. If you don't use the classic trunk/branches/tags structure, you can deactivate that from the Advanced tab, if you uncheck the "Enable structure detection".

Once you're content with the folder and everything, it will ask you for which resources to check out as a project. And it will show you the repository tree for you to browse and select the specific folder you want to check out. Select it, click Finish.

In the next window it asks you what to do, regarding the creation of the project. Check out as a project configured using the New Project Wizard is like creating a normal project from scratch with the typical assistant, only that it is prepopulated with the contents from the SVN repository location you just selected. This is very useful for creating PHP projects, or FDT projects, for example, so that the project acquires the appropriate nature and you get instant gratification from the beginning (i.e. source highlighting, auto-completion, useful contextual options, etc ...).

You could also select Check out as a project with the name specified, which will then create a folder with the name you enter, in your current workspace. Very useful for checking different versions of the same repository (for example into your web_root) into the same parent folder, and modifying them in parallel.

Then click Next, change the workspace if you feel like that, and Finish.

Eclipse will check out things from the repo and set up the new project. If you look at it in the project explorer, it has the svn location right next to its name, to denote it is a svn project.

Comparing and reverting

There is more new stuff. Unfold the project to see all the files and open one of them. Edit it and change something, save it. Now go out, leave the computer alone and have a walk. You could also go to an ice rink, there are lots of temporary rinks open right now in London. If that's not your thing, you could also head for the pub, which is an all-time winner option. Unless you head hurts... Anyway, what was that thing you changed? You don't remember at this point, do you? Wouldn't it be great to compare it with the repository version? But we said we didn't want to use external tools, and we won't do that. Right click over the modified file (which has a ">" in front of its name, to denote it has been modified and has not been checked in yet) and select Compare with... Latest from repository. A new tab will open showing the differences between versions. You can even modify the version you changed, using the repository one as reference.

But what if you don't like those changes? Well, you could just wipe out everything by right clicking over the file and selecting Replace with ... Latest from repository. Bam! it's gone, you can start from scratch again.

Checking things in (commiting)

Let's imagine you have been doing some work and now are happy with it and want to check that into the repository. It's a matter of right clicking over the changed files and selecting Team... -- Commit....

If you have right clicked over a folder, it will show you which files from that folder will be included in the commit. This is your last chance for unselecting files you don't want to include.

On the other hand, if you have clicked over a file which is not yet in the repository, it will complain and say it's not under version control. In this case you need to manually add them first. Right click over the file you want to put under version control (which has a question mark over its icon to show it's not in SVN yet) and select Team -- Add to version control.... It will then be included in the next check-ins.

Deleting stuff

This is a very common mistake we do when we do not understand how svn works. If something is under version control, NEVER EVER DELETE IT FROM THE FILE SYSTEM MANUALLY. You need to delete it via subversion. Fortunately, that is very easy with this plug-in: just right click over it and select Delete. Then you'll probably have to check in the parent folder, so that subversion registers the new state of the folder (i.e. this folder has now one file less). Otherwise you risk creating a little (or big, depends on your case) wave of chaos and confusion in subsequent commits and updates.


By the way, updating is as easy as right clicking over something and then selecting Team -- Update.

This is only a very little demonstration of what you can do with subversive; the best way of finding out is to experiment with the different options there. Let me know if there is some area I could expand in this mini tutorial or if something wasn't clear enough, and I'll try to clarify. Happy SVN'ing!