Subclipse FAQ

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 Websphere Studio 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. Recently, a third option was added and that is to use the JavaSVN 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 JavaSVN does not utilize the Subversion libraries it does not have the guaranteed compatability that you can expect from JavaHL or the command line adapters. That being said, JavaSVN is tested against the same test suite that tests the Subversion command line, and passes those tests.

JavaSVN does not currently support the file:// protocol but there are plans to add support for accessing fsfs repositories in the future.

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, JavaSVN is a great option and offers a number of significant features that JavaHL does not currently offer. JavaHL is currently your only option if you have to use file:// protocol. In that scenario, you should really consider running a local svnserve instance and using the svn:// protocol.

See Support for SVN Protocols for more details on when one adapter might be better than the other.

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 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.

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

Subclipse does not provide anything that allows you to create a Subversion repository. That action has to be performed outside of Eclipse. Within Subclipse, you define a "connection" to an already existing repository. 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 convert an existing CVS repository into a Subversion repository?

Members of the Subversion development community created and maintain a tool called cvs2svn. You can find it at http://cvs2svn.tigris.org/. Be sure to read the cvs2svn documentation.

If cvs2svn.py does not work for you, (e.g. your repository causes it to crash, or it doesn't deal with branches and tags quite how you would like), there are at least two other conversion utilities you can try. These have different features (and possibly different bugs):

• One based on VCP written by Chia-liang Kao can be found on CPAN.
• refinecvs written by Lev Serebryakov is at http://lev.serebryakov.spb.ru/refinecvs/.

See also the Subversion links page.

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.1/ch07.html#svn-ch-7-sect-1 for more information.

If you are using the JavaSVN command-line client adapter then see: http://tmate.org/svn/kb/config-settings.html for more information.

Also see: Support for SVN Protocols for more details.

How do I specify SSL client certificates?

If you are using the JavaHL or JavaSVN adapters, then, at least in theory, 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. As of the writing of this FAQ entry, at least JavaHL has not implemented this prompting. Consequently, you need to store your client certificate in the Subversion configuration area. See: http://svnbook.red-bean.com/en/1.1/ch07.html#svn-ch-7-sect-1 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 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.1/ch07.html#svn-ch-7-sect-1 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.

As of Subclipse 0.9.35 if you are using the JavaSVN 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, JavaSVN 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 JavaSVN. If so, then you should "undo" all of that manual configuration. The older manual configuration is documented at: http://tmate.org/svn/kb/config-settings.html.

Also see: Support for SVN Protocols for more details.

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

Windows: JavaHL is included as part of Subclipse. You do not need to do anything.

OS X: We recommend that you install the Subversion package from openCollabNet. This package includes JavaHL and installs everything in a way that it is recognized by Subclipse. Download the package at http://downloads.open.collab.net/binaries.html.

Linux: The answer varies by distribution and the packaging mechanism. In general most distributions do NOT include the JavaHL library in their Subversion package. In most cases, you can download the source package and alter the build spec to build JavaHL.

There are Debian packages available for Subversion with JavaHL enabled. The packages are provided by http://www.ggtools.net/. Here is the sources.list entry:

deb http://www.ggtools.net/files/debian/unstable/ ./

There are also binary RPM packages for SUSE available. The main Subversion RPM package includes JavaHL by default. These can be obtained at http://ftp.suse.com/pub/projects/apache/subversion/.

Debian packages for Ubuntu Breezy Badger are also available. See the following message for details: http://svn.haxx.se/dev/archive-2006-01/0399.shtml

Others: If your packaging mechanism does not include the JavaHL library, then you probably need to build the library from source.

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/project_packages.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\
     --with-jikes=$JAVA_HOME/bin/javac
make
make javahl
make install
make install-javahl

The main part to check before running the above command is "--your-other-flags". You will typically at least want --enable-ssl.

I think I have a valid JavaHL library installed, but Subclipse says it is not found. What should I do?

Starting with Subclipse 0.9.33 we now show the errors that occurred when loading the JavaHL library. To see these errors open the Eclipse preferences and go to Team -> SVN. Then click on JavaHL in the adapter section, the error messages should appear in a dialog.

On *nix systems the problem is almost always that the JavaHL library was not found in the java.library.path. The Sun JVM only looks in the value of LD_LIBRARY_PATH, and on many *nix systems this value is not defined. The easiest workaround is to create a shell script that launches Eclipse:

export LD_LIBRARY_PATH=/usr/local/lib:.
./eclipse

Alternatively, you can also do something like this in your script:

./eclipse -vmargs -Djava.library.path=/usr/local/lib

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:

 public static boolean validateWorkspacePath() {
    File file = ResourcesPlugin.getWorkspace().getRoot().getLocation().toFile();
    String canonicalPath = null;
    try {
       canonicalPath = file.getCanonicalPath();
    } catch (IOException e) {
        e.printStackTrace();
    }
    if (!file.getAbsolutePath().equals(canonicalPath)) {
        MessageDialog.openError(Display.getCurrent().getActiveShell(), Policy.bind("WorkspacePathValidator.title"),
         Policy.bind("WorkspacePathValidator.eclipsePath") + "\n\n"  + file.getAbsolutePath() + 
         "\n\n" + Policy.bind("WorkspacePathValidator.fileSystemPath") + "\n\n" + canonicalPath +
         "\n\n" + Policy.bind("WorkspacePathValidator.instructions"));
        return false;
    }
    return true;
 }

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 JavaSVN 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 JavaSVN, 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.

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 th 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.

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.