Login | Register
My pages Projects Community openCollabNet

subclipse
Wiki: PluginFAQ

Edit this page | Links to this page | Page information | Attachments | Refresh page

 

Subclipse FAQ

This page will attempt to answer some questions about Subclipse

Return to Wiki FrontPage

Contents

  1. General questions:
    1. Why does this project exist?
    2. Does Subclipse support Eclipse X.Y or Other IDE X.Y?
    3. What is an adapter? What is JavaHL?
    4. Which adapter should I use?
    5. Which adapter am I using?
    6. I have chosen SVNKit, but it looks like JavaHL is still being used.
    7. Usernames and passwords
  2. How-to:
    1. How do I check out the Subclipse code?
    2. How do I create a repository? How do I import data into it?
    3. How do I configure an HTTP proxy connection?
    4. How do I specify SSL client certificates?
    5. How do I configure an svn+ssh:// connection?
  3. Troubleshooting:
    1. While installing Subclipse I can't get past the Review Licenses page
    2. New files added by other users are not showing up in Synchronize view or even coming into my workspace when I update the entire project
    3. How do I get the JavaHL library for my operating system?
    4. How do I build JavaHL from source?
    5. I think I have a valid JavaHL library installed, but Subclipse says it is "Not available". What should I do?
    6. I keep getting an error message about my "Working Copy not locked". Is this a bug? What should I do?
    7. I am trying to commit some changes and I am getting an error message about the transaction being "out of date". What does this mean and what should I do?
    8. On the SVN preferences page the SVN Interface drop down is Blank. What do I do?
  4. Obsolete FAQs:
    1. As soon as I do something with Subclipse on Windows, Eclipse just crashes. Why does this happen?
    2. Why am I getting an error dialog telling me the case of my Eclipse workspace path does not match the filesystem? Windows does not seem to care.


General questions:

Why does this project exist?

Subclipse exists to provide an outstanding user interface to Subversion from within the Eclipse IDE. We aim to provide a client that is every bit as robust and user-friendly as the CVS client that comes with Eclipse. That being said, there are a lot of major technical differences between Subversion and CVS. Therefore, we try to strike a balance between providing a UI that will be familiar to experienced Eclipse CVS users, and one that is appropriate for the Subversion action being exposed. In particular, the way that Subversion handles branches and tags is very, very different from CVS. Consequently the UI for these features in Subclipse is different than the UI for the CVS client.

Does Subclipse support Eclipse X.Y or Other IDE X.Y?

Subclipse should support any IDE or application that is built on the Eclipse framework. The Subclipse feature has the appropriate <requires> tags to define the Eclipse features that we require. The current version of Subclipse supports Eclipse 3.x. There is an older version of Subclipse that supports Eclipse 2.x and applications that are based on it, such as WebSphere Studio 5.x. That version of Subclipse is no longer supported or actively developed.

What is an adapter? What is JavaHL?

Unlike CVS, which does not have an official API, Subversion was designed from the start to be an API. Subversion is written (in C) as a set of libraries. Subversion then provides a default UI, in the form of a command line interface, that uses these libraries. Subversion also provides language bindings for various programing languages so that these same libraries can be used in your language of choice. JavaHL is the name of the Java language binding provided by the Subversion project. JavaHL is an official part of the Subversion project, not the Subclipse project.

svnClientAdapter is a Java project that was developed for Subclipse. It provides an even higher level of abstraction to the Subversion libraries. It also allows for different ways of accessing Subversion functionality. Historically, the two options were to use the JavaHL library or the Subversion command line. Eventually, a third option was added and that is to use the SVNKit library which is a 100% Pure Java implementation of the protocols used by Subversion. This option has the advantage of not requiring any native libraries installed on the client. Of course, since SVNKit does not utilize the Subversion libraries it does not have the guaranteed compatibility that you can expect from JavaHL or the command line adapters. That being said, SVNKit is tested against the same test suite that tests the Subversion command line, and passes those tests.

Which adapter should I use?

If the JavaHL library is available on your system, or easily attainable, then it is probably the best choice. That being said, SVNKit is a great option.

Which adapter am I using?

You can see which adapter you are using in your Eclipse preferences. Go to Team > SVN. In the latest versions of Subclipse the client adapter is a drop-down. The drop-down shows any adapters you have installed. If the adapter loads properly, the version is shown, otherwise it reports "Not available".

If you have chosen the JavaHL adapter and it is not available, Subclipse will fall back to using SVNKit if it is installed and available.

I have chosen SVNKit, but it looks like JavaHL is still being used.

If your preferences show that you are using SVNKit, then that is what is being used. SVNKit provides a pure Java implementation of the JavaHL Java interface and that is how Subclipse uses it. So the JavaHL Java namespace still shows up in things like errors/exceptions because that namespace is part of the interface.

Usernames and passwords

Subclipse does not collect or store username and password credentials when defining a repository. This is because the JavaHL and SVNKit client adapters are intelligent enough to prompt you for this information when they need to -- including when your password has changed.

You can also allow the adapter to cache this information and a common question is how do you delete this cached information so that you can be prompted again? We have an open request to have an API added to JavaHL so that we could provide a UI to do this. Currently, you have to manually delete the cache. The location of the cache varies based on the client adapter used.

JavaHL caches the information in the same location as the command line client -- in the Subversion runtime configuration area. On Windows this is located in %APPDATA%\Subversion\auth. On Linux and OSX it is located in ~/.subversion/auth. Just find and delete the file with the cached information.

SVNKit caches information in the Eclipse keyring. By default this is a file named .keyring that is stored in the root of the Eclipse configuration folder. Both of these values can be overriden with command line options. To clear the cache, you have to delete the file. Eclipse will create a new empty keyring when you restart.

How-to:

How do I check out the Subclipse code?

The URL for the Subclipse repository is http://subclipse.tigris.org/svn/subclipse/. If you have at least the Observer role in the Subclipse project, then provide your tigris.org username and password when prompted. Otherwise use a value of "guest" for username and leave the password field empty. Subclipse development is currently active on trunk.

Also see: SubclipseDevelopment

How do I create a repository? How do I import data into it?

Subclipse provides an option for creating a repository but this is really only suited for personal development where you do not need to share your code. Typically you would setup a Subversion server, create the repository on the server and then point Subclipse at the server. Defining a connection is one of the first things you should do when using Subclipse. This is done from the Subclipse Repository Exploring perspective.

As for importing data, there are numerous ways it can be done, including doing it from outside of Eclipse. Assuming you have an existing project in your Eclipse workspace that you want to add to your repository, you need to right-click on the project and do Team -> Share Project. Then follow the wizard.

How do I configure an HTTP proxy connection?

If you are using the JavaHL or command-line client adapter then all communication with your repository is performed by the Subversion libraries. Consequently, the configuration is the same as what you would do for the Subversion command line. See: http://svnbook.red-bean.com/en/1.5/svn.advanced.confarea.html#svn.advanced.confarea.opts for more information.

If you are using the SVNKit adapter then see: http://svnkit.com/kb/config-settings.html for more information.

Also see: Support for SVN Protocols for more details.

How do I specify SSL client certificates?

You should be prompted when/if you need to supply the server with a client certificate, just as you are when using the command-line. You may want to configure Subversion so that it already knows about the location of your client certificate. See: http://svnbook.red-bean.com/en/1.5/svn.serverconfig.httpd.html#svn.serverconfig.httpd.authn.sslcerts for more information.

Also see: Support for SVN Protocols for more details.

How do I configure an svn+ssh:// connection?

If you are using the JavaHL then all communication with your repository is performed by the Subversion libraries. Consequently, the configuration is the same as what you would do for the Subversion command line. See: http://svnbook.red-bean.com/en/1.5/svn.advanced.confarea.html#svn.advanced.confarea.opts for more information. For Windows users, here is a great explanation of how to set this up from our mailing list archives: Configuring svn+ssh:// on Windows.

Note: By default Eclipse is set to JavaHL. Goto Eclipse->Window->Preferences->Team->SVN and change the SVN Interface to SVNKit.
If you are using the SVNKit client adapter you should be dynamically prompted for your SSH username, password, keyfile, port etc... When defining the repository connection in Subclipse, simply specify the URL like svn+ssh://hostname/repos. Do not include your username in the URL and do not provide a username and password in the connection dialog. At runtime, SVNKit will prompt you for your SSH credentials and optionally cache them in the Eclipse keyring. If you are not prompted for your credentials, it may be because you have previously attempted to manually configure SVNKit. If so, then you should "undo" all of that manual configuration. The older manual configuration is documented at: http://svnkit.com/kb/config-settings.html.

If you do prefer JavaHL on Windows, try these steps to set up svn+ssh access without password:

  1. Install the complete PuTTY: http://the.earth.li/~sgtatham/putty/latest/x86/putty-0.60-installer.exe

  2. Verify: Run PuTTY to connect to your remote host through ssh.
  3. Run PuTTYget to generate a private/public key pair.
  4. Copy the public key into your remote $HOME/.ssh/authorized_keys file.
  5. Verify: Run PuTTY to get a remote commandline without entering password.
  6. Verify on commandline, e.g.  Plink.exe -2 -i D:\home\.ssh\id_dsa.ppk your.remote.host -l yourUser 

  7. Install http://tortoisesvn.tigris.org/ -- this includes a Plink client without console link

  8. Verify: Connect your svn+ssh repository in TortoiseSVN. Will ask for password!
  9. Edit C:\Documents and Settings\user\Application Data\Subversion\config and add this:

    [tunnels]  
    ssh=C:\\PROGRA~1\\TortoiseSVN\\bin\\TortoisePlink.exe -2 -i D:\\home\\.ssh\\id_dsa.ppk 
  10. Verify: TortoiseSVN should work without password now
  11. Verify: Subclipse + JavaHL should also work without password now.

Also see: Support for SVN Protocols for more details.

Troubleshooting:

While installing Subclipse I can't get past the Review Licenses page

This is a bug in the Galileo p2 feature. Try moving back and forth in the wizard, or closing and re-opening the wizard. You might find other suggestions in the comments in the Eclipse Bugzilla page

New files added by other users are not showing up in Synchronize view or even coming into my workspace when I update the entire project

This is caused by a bug in Subversion 1.6 that was fixed in Subversion 1.6.2. However, the fix just prevents the problem from continuing to happen, it does not fix your existing working copies. To fix your working copy follow these steps:

  1. Right-click on your Project and choose Team > Update to Version ...

  2. Change the Depth combo box to a value of "Fully recursive"
  3. Check the box that says "Change working copy to specified depth"
  4. Press OK

The bug was that when new folders were added to Subversion in your working copy, they were added with a depth option of empty. So you could see updates to anything you added, but new files and folders added by others would not show up due to the depth setting. The Subversion add API was fixed to set the depth to fully recursive as had always been the case.

How do I get the JavaHL library for my operating system?

There is a dedicated Wiki page with detailed JavaHL Information.

How do I build JavaHL from source?

JavaHL is part of the Subversion project. So to begin, you probably want to download the latest source tarball. See: http://subversion.tigris.org/getting.html. You should refer to the Subversion instructions for detailed information, but on a *nix system the general procedure is this:

./configure --your-other-flags=here --enable-javahl --with-jdk=$JAVA_HOME
make
make javahl
sudo make install install-javahl

The main part to check before running the above command is "--your-other-flags". Here is a personal example from an OSX system:

./configure \
    --prefix=/opt/svn-1.5 \
    --enable-maintainer-mode \
    --enable-javahl \
    --disable-mod-activation \
    --with-swig=/opt/local/bin/swig \
    --with-apr=/opt/local/bin/apr-1-config \
    --with-apr-util=/opt/local/bin/apu-1-config \
    --with-apxs=/opt/local/apache2/bin/apxs \
    --with-neon=/opt/local \
    --with-serf=/opt/local \
    --with-berkeley-db=/opt/local \
    --with-junit=/opt/local/share/java/junit.jar

I think I have a valid JavaHL library installed, but Subclipse says it is "Not available". What should I do?

A wiki page has been created with detailed JavaHL Information.

I keep getting an error message about my "Working Copy not locked". Is this a bug? What should I do?

You are performing an operation like Update and it fails with an error that look something like this:

 update -r HEAD C:/workspace/project/bin
    Working copy not locked; this is probably a bug, please report
 svn: Working copy 'C:\workspace\project\bin' is missing or not locked 

This message is coming straight out of the Subversion library, so technically it is Subversion asking you to report the problem to them. This error message is kind of their general error message when something really unexpected happens. In the case of Eclipse, the problem is almost always one specific thing. The problem is that your Eclipse build folder was versioned and added to your repository. What happens is that when Eclipse does a full build it will delete everything in this folder, including the ".svn" metadata folder. When Subversion cannot find this folder it issues the above error.

The solution is to delete this folder from your repository, which you can do from the SVN Repositories view. Then try deleting the folder from your working copy and performing an update. You might need to checkout your project again. Once you have a valid project again, be sure to add the build folder to the svn:ignore property of its parent folder so that the problem does not happen again.

If this is not your problem, then as best as you can try to figure out what might have led up to having this problem and report it on the Subversion users@subversion.tigris.org mailing list.

I am trying to commit some changes and I am getting an error message about the transaction being "out of date". What does this mean and what should I do?

Whenever you see "out of date" in an error message it means that the revision of the item in the repository is newer than the copy in your local working copy. The solution is always going to be to run an update, so that your working copy is up to date with the repository, and then do the commit again (assuming that the update did not generate any conflicts). For files, this is usually pretty easy to understand how and why this happens. However, Subversion also versions folders, and it is usually with folders that this problem most often happens. Subversion does not allow you to delete/rename a folder OR change its versioned properties, UNLESS the local copy of the folder is at the HEAD revision of the folder in the repository.

Your next question might be: "OK, I can maybe understand that, but why is my folder out of date? I am the only person working in this repository." That is a valid question, the answer lies in the way that Subversion works. When you commit a change to a file, the revision of the file in your working copy is updated to that new revision when the commit completes, however the version of the parent folder(s) of that file is not updated. This is because there may have been adds/deletes to other files in that folder and until you have run an update, the folder is not really at that new revision. This is called "mixed revision working copies" and is probably explained better in the Subversion book.

In summary, the answer is always to do an update so that the folder or file is updated to its HEAD revision.

On the SVN preferences page the SVN Interface drop down is Blank. What do I do?

This issue normally means you did not install an adapter. Because if you did, then they should show up in the drop-down and in worst case with a "Not available" next to them. For the drop-down to be empty means the features are either not installed or not loading.

So here is what you need from an Eclipse "feature" perspective:

Must have

  • Subclipse
  • SVN Client Adapter

Must have at least one of

  • JavaHL Adapter
  • SVNKit Adapter

If SVNKit Adapter is to be used, must have

  • SVNKit Library

The most common reason for to see this issue is that one of the Must have at lease one of is not loaded or it is failing to load for some reason.

Obsolete FAQs:

The following FAQs are no longer valid if using a recent version of Subclipse, Subversion or Eclipse. They are preserved here for users of these older versions.

As soon as I do something with Subclipse on Windows, Eclipse just crashes. Why does this happen?

This is a fairly recent problem that is caused by a DLL incompatibility. Subversion uses a library called APR or the Apache Portable Runtime. This library has a component called APR-ICONV which is used for translating characters in path and file names to/from UTF8 and the local character set. The release of Apache 2.2 brought with it new releases of APR and APR-ICONV and these are not binary compatible with previous releases. Subclipse ships with the Apache 2.0 version of these libraries. This crash occurs if you install an application that installs the Apache 2.2 version of these libraries AND ALSO sets the APR_ICONV_PATH environment variable to a path that contains the Apache 2.2 version of the APR-ICONV .so objects.

The fix is actually simple. Change the name of the environment variable to APR_ICONV1_PATH. The Apache 2.2 library will look for this environment variable name first, and only fallback to the older name if it is not found. You can safely have an APR_ICONV_PATH environment variable pointing to the Apache 2.0 version of these libraries and the APR_ICONV1_PATH environment variable pointing to the Apache 2.2 version.

Subversion 1.5 has resolved this problem by discontinuing the use of APR-ICONV. Instead, Subversion will use translation routines that are provided by the Windows operating system.

Why am I getting an error dialog telling me the case of my Eclipse workspace path does not match the filesystem? Windows does not seem to care.

The underlying problem here is in Eclipse, see Bug#: 95832. Eclipse does not canonicalize the workspace path to match the case of the underlying OS. That alone would not be a problem, but Eclipse also has code which relies on an exact string match when converting a path represented as a String to an Eclipse resource. When Subclipse calls Subversion API's, Subversion naturally passes back paths in their exact case from the file system. Subclipse then has to take those Strings and convert them to an Eclipse IResource. The Eclipse code to do this fails if the case of the string does not match exactly with the value that Eclipse has stored for the workspace.

This problem was causing a lot of problems for Subclipse users and it took a long time before the underlying cause was discovered. See Subclipse issue# 285 and all of the duplicates. Since we cannot fix the Eclipse problem and this problem is so hard for a user to self-diagnose, we added in our own check which displays a warning dialog when we detect this situation exists. The validation code looks like this:

   1  public static boolean validateWorkspacePath() {
   2     File file = ResourcesPlugin.getWorkspace().getRoot().getLocation().toFile();
   3     String canonicalPath = null;
   4     try {
   5        canonicalPath = file.getCanonicalPath();
   6     } catch (IOException e) {
   7         e.printStackTrace();
   8     }
   9     if (!file.getAbsolutePath().equals(canonicalPath)) {
  10         MessageDialog.openError(Display.getCurrent().getActiveShell(), Policy.bind("WorkspacePathValidator.title"),
  11          Policy.bind("WorkspacePathValidator.eclipsePath") + "\n\n"  + file.getAbsolutePath() + 
  12          "\n\n" + Policy.bind("WorkspacePathValidator.fileSystemPath") + "\n\n" + canonicalPath +
  13          "\n\n" + Policy.bind("WorkspacePathValidator.instructions"));
  14         return false;
  15     }
  16     return true;
  17  }

NOTE: We recently discovered that this basic issue was causing another problem users were seeing. In this case it happens when you use File -> Import to import a project and you do not specify the correct case when importing. This leads to the same null resource problem. In this scenario, we are now logging a very detailed error in the SVN Console and Eclipse error log. It also points to this FAQ. In recreating the problem it appeared that the SVNKit adapter did not have the problem. Possibly because it is using the same Java API's as Eclipse the case does not get canonicalized as it does when using the JavaHL native C libraries. Other than switching to SVNKit, the way to solve the problem in this scenario would be to delete the project from the workspace and re-import it. Use the Eclipse file chooser to select the project so that the case matches the OS.

Update: The underlying problem has been fixed in Eclipse 3.2, and if you install the version of Subclipse for Eclipse 3.2 or higher, we no longer issue these warnings.

PluginFAQ (last edited 2009-11-17 21:24:23 -0700 by ?markphip)