Subversion with Eclipse: Subclipse

Humour me if you're an Eclipse expert already, but I've been taking my time about getting familiar with it. I tried the compound XML document editor a little while back and was less than impressed with it's SVG editing ability. As far as I could tell it didn't even respect the encoding I specified (I couldn't change from the default to UTF-8). Maybe I missed the point of that plugin, though.

So tinkering a bit with a new project in Eclipse recently, I noticed that there's CVS support built in. I like Subversion and have a couple projects stored in Jeff's subversion repository. I love the almost seemless integration of the Tortoise SVN client into Windows Explorer. So seeing the CVS support in Eclipse got me wondering about SVN support. Sure enough, the good people at have an Eclipse plugin called Subclipse.

The installation instructions are very clear, but demonstrate what I don't like about Eclipse. This is standard practice for installing a plugin for that framework, I'm sure, but it's vastly different than plugins for more familiar software projects. I'm sure the steep learning curve keeps a lot of otherwise enthusiastic developers out. Subclipse developers shouldn't have to include that many screenshots to do something as run-of-the-mill as adding a plugin. Without those screenshots I would have probably given up though. Eclipse could learn something from the XPI installation method that Firefox uses.

After installing Subclipse I wasn't sure what to do next. I've only made a couple of Eclipse projects and don't have a good grasp of their terminology yet. So here's what I did figure out. The instructions say
Finally, after restarting Eclipse, the first thing you will typically want to do is open the Subclipse Repository perspective where you can define your repositories. Be sure to also check the online help as well as the Subclipse preferences located under Team -> SVN.
And have a picture of a box that I didn't know how to get to. Apparently all that's missing for the Eclipse beginner is to chose Window ⇒ Open Perspective ⇒ Other... The item "SVN Repository Exploring"in that list is obviously the perspective the instructions refer to. I'm not sure what exactly a perspective is yet, but it's apparently different from a view. The pane opens on the left side of the main window and you can right-click in the empty space then choose New ⇒ Repository Location. The ensuing dialog clearly explains what you need. One thing you might miss if you weren't paying close attention is that Subclipse connects to the Internet separately from Eclipse. That might make a difference or it might not.
Using a proxy If you use a proxy, you'll have to configure the SVN client that Subclipse relies on in order for it to get through. If you don't, skip down a bit to "Accessing your Project".
The Subclipse FAQ points to Version Control with Subversion for instructions on that. (Note there are different instructions on the JavaSVN client which I'm not using and I'd bet if you are then you don't need my help). The instructions look daunting at first, but then I realize they cover Unix and a couple methods for Windows. For a Windows XP/2000 user (as I am at the moment), it boils down to finding a configuration file in a directory like C:\Documents and Settings\<em>username</em>\Application Data\Subversion. The username part is going to be your login name or some variation on it. And as the book notes, this is usually a hidden folder. In that folder, the configuration file is a text file with the name "servers" and no extension.
If you just have a single, simple SVN repository you want to get to (the usual case, I think), then look for the section that starts with "[global]". Once you find it, the rest should be straightforward. There's a commented-out section that looks like this:

# http-proxy-host =
# http-proxy-port = 80
# http-proxy-username = blah
# http-proxy-password = doubleblah

Uncomment it by removing the # marks and fill in your proxy info.
Phew. Didn't mean to go into all that detail, someone should make a script for this sort of stuff.
Accessing your Project
Anyhow, after that's done, then you can access your SVN project with Subclipse from inside Eclipse. Remember that subversion works on whole folders at a time though. This carries through to Subclipse, so you can use it to explore your whole repository, but you can't just double-click a file and start editting. The way to edit the files in your repository is simple, right-click a folder inside the repository (but not the top-level repository itself) and choose "Check out as Project." This will create an Eclipse project containing the contents of that folder. Since you can't get the top-level container as a project, make sure that you give the highest-level path that you can when you add the repository to the perspective. Why didn't I mention that earlier? Because that was all confusing enough already.

Once the project is created, you'll want to see it, so go to the "Resource" perspective. You can find the Resource perspective on the Window menu, the same way we found the SVN Repository Explorer perspective earlier. There's also a toolbar near the top with buttons to switch perspectives once you get used to it. I see a lot more potential use for Eclipse (for me) with the Subclipse plugin. The revision history for the file being editted is available inside the tool and there seem to be more advanced features that I still haven't even looked at.
Maybe if I keep at it I can even figure out how to commit my changes back to the project ...

Your rating: None Average: 4 (2 votes)

It is a good thing you did not try this a week or two ago. I just barely added all of that documentation!

Before you become an Eclipse/Subclipse "expert" please keep some notes about these things you find confusing. Most Subclipse users are experienced with Eclipse so we take certain things for granted in our docs.

The Subclipse dialogs are very similar to TortoiseSVN, so hopefully you will find it easy to use.

In the next release of Subclipse, you can do a Checkout at the root of the connection. Should be available next week.

As for the proxy stuff, I am a bit surprised. I thought that you had to set all of that up for TortoiseSVN too. So I would have expected that you had already done it. One of the advantages of Subversion is that there is a common library that the Command Line, TortoiseSVN, Subclipe and any other GUI all share. So you should be able to use any of the tools of your choice on the same working copy, and you should only have to do the setup stuff once.

Hi Mark, good work on the docs, without that it would've taken me hours longer. I probably would have just given up. I had to set up the proxy stuff because I haven't got TortoiseSVN on this machine (yet) - so this is my first time with it through a proxy.

I have been learning my way around, through some more reading and experimenting. I think that the Compound Document Editor was the reason that I couldn't just double-click and start editing a file. The CDE plugin sets itself up as the editor for SVG files (the type I was working with) and won't let you edit them as text. The error I got said something about Eclipse not being able to create an editor for the document. I can't get it again since I removed the Compound Document Editor.

Commiting changes with Subclipse seems a little odd - I really find that convenient in TortoiseSVN. With Subclipse the only way I've found so far is through a synchronization process. I'll dig in a little further some time and see if there's something simpler that I'm missing. I think I need to read up more on how to synchronize, but I have a feeling that it's partly a function of Eclipse but implemented with SVN. I get that impression since I see a CVS option when synchronizing as well.

I will keep notes and I'll post any more 'revelations' I have. It might be useful to people coming at it from outside the usual Eclipse crowd.

First of all, good job with the docs, they were really helpful. I have got one question though.
I am trying to create a local repository using subclipse and I am having all sorts of problem. If I am not wroing the process is

OPen perspective
SVN repository
And then u type the URL, right?

But it's not working. It does'nt ask for any URL when I click SVN repository. Can u help?


Hi Muntasir,

I think that the first time you open the SVN Repository Explorer perspective you are prompted for a repository location. If you missed that prompt, then you get the same thing when you right-click in the SVN Repository pane and pick "New &#8658; Repository Location..." (there's also a button labelled "Add SVN Repository" that brings up the same dialog).

This option lets you connect to an existing SVN repository though. It sounds like you're trying to create a new one. In the Subclipse FAQ it says you have to do this outside of Subclipse.

To create a new repository, I think you'll need to get Subversion itself. I haven't installed my own repository yet, though I'm considering it. If I do, I'll write about it here.



Thank you so much for u'r help. I have setup the repository. If you need any help on that, please let me know.

In eclipse, there is an option called "team". Are you familier with that option? If you select that option, it asks for a patch. Do u know how to apply a patch in eclipse?


I think the 'patch' they're referring to has to do with your subversion project. I've never used it though, so I'm afraid I don't know any more about it.

Just out of curiosity, did you ever find a good way to commit or synchronize your changes? I've tried the synchronize function but that doesn't seem to automatically perform a commit. I know I can right click and select the commit function but I'm lazy and I'd much rather have a commit button on the toolbar or setup a shortcut key so I don't have to right click everytime. Just wondering if you found a simpler way?

No, that's the easiest way that I know so far. Once I have Tortoise SVN and Subclipse on the same computer I'm going to see if I can just commit through Explorer, but I don't know if that lines up with the way Eclipse does things.

I have switched from Vs.PHP to Eclipse to edit my PHP project and I am very confused with Eclipse's approach to a project (compared to Visual Studio I mean). Eclipse seems to own the files: the project *is* the directory, it's a not a loosely coupled file like in Visual Studio.

I already have an SVN checkout of my project, so I want to import it into Eclipse ... Does not work. Even after deselecting (manually) each of the .svn folders so they don't get imported, I can't create a project in-place. I have to keep a separate copy, which is then not "subversionable".
Worse, you cannot remove a file from the project - you can only remove it from the file system. That's why you can't just ignore the .svn folders. What a pain

So I have a question: is there a way to simply use eclipse as project manager, not a file manager, and not a subversion tool ? I like to commit from the Explorer and am not interested in built-in features to update/commit from Eclipse. In fact, how do you guys [prefer to] work ?
Maybe if I had started the project with Eclipse it would be easier ...

Eclipse does seem to be more "in control" of the files than VS, in my limited experience. I was going to mention that the folders in the Eclipse navigator view don't necessarily correspond to file system folders (or maybe this is just in the package explorer), but then that's true of Visual Studio as well. So I guess it's not just more or less coupling, but a different way of looking at things than I'm used to.

When you create a file in an Eclipse (from the navigator view), you can link it to a file in the file system. Right-click, pick new &#8658; file, then you get the New File dialog that asks for the parent folder and file name. Under the file name edit box, click the "Advanced" button and you can choose to link to an existing file.

Now it looks like the folders in this dialog correspond directly to the tree of folders in the Eclipse workspace folder on the filesystem. I'm using Windows, but I would expect this works similarly on Mac and Linux. So if I click the "Browse..." button then I can find the folder that an existing project is in and link the new Eclipse file to the file in my project. That should work with a project that's synchronized via Tortoise SVN or a project that you share with Visual Studio. It might get tedious to link every file in the shared project, but I think it would work.

That means that if you already have a project that needs one development setup (like TortoiseSVN or Visual Studio) then you could create a parallel project in Eclipse that just accesses all the files in that other folder. It looks like you could even create a variable to keep the path of the base project using the "Variables..." button.

Thanks for your reply, Rob.
I had not noticed this "Advanced" button before; and it seems to be the "Add existing" feature I was looking for.
Indeed, this means I have to separately create the files and link them into Eclipse but that's anyway what I already do with my C++ projects (I keep the projects files separated from the sources so I can compile them easily with both VC++'s solutions and GCC's makefiles).

I see only advantages in this method:
- we can keep Tortoise SVN as the subversion client; given the quality of this product, one would be crazy to use another one
- it allows an easier collaborative work as each developer can pick his prefered method to edit his files (while still relying on SVN's power)
- manually importing files let us choose exactly what is part of the project's release and what should not be deployed. The only overhead comes when we first create the Eclipse project - it does not happen everyday !

Nice document! Thanks