# FAQ

## Table of Contents

#### General questions:

- Why does this project exist?
- Does Subclipse support Eclipse X.Y or Websphere Studio X.Y?
- What is an adapter? What is JavaHL?
- Which adapter should I use?
- Usernames and passwords.

#### How-to:

- How do I check out the Subclipse code?
- How do I create a repository? How do I import data into it?
- How do I convert an existing CVS repository into a Subversion repository?
- How do I configure an HTTP proxy connection?
- How do I specify SSL client certificates?
- How do I configure an svn+ssh:// connection?

#### Troubleshooting:

- How do I get the JavaHL library for my operating system?
- How do I build JavaHL from source?
- I think I have a valid JavaHL library installed, but Subclipse says it is not found. What should I do?
- 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.
- I keep getting an error message about my "Working Copy not locked". Is this a bug? What should I do?

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

When you define a repository connection to Subclipse there is an area to specify your username and password. Since version 0.9.30 of Subclipse the best thing to do is always leave these fields empty. The exception is if you are using the command line adapter. As of version 0.9.100 the dialogs no longer show the username and password fields. Why should you leave them blank? Because the JavaHL and JavaSVN adapters are intelligent enough to prompt you for this information when they need to. You can also then allow the adapter to cache this information. The adapters are also intelligent enough to prompt you when the password has changed. Conversely, if you specify a username and password within Subclipse then we supply that username and password to the adapter. If the password has changed on the server, then the adapter will prompt you for a new one. Now we get to the problem. Subclipse does not know that this exchange took place so it has no way to update its password. Consequently you keep getting prompted by the adapter for your password.

If you just leave these fields blank within Subclipse, then you never have to worry about it. If you do provide a username and password to Subclipse, and your password changes, you can update the stored values by right-clicking on the connection in the SVN Repository view and choosing the Properties option.

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

## Troubleshooting:

### 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 Metissian Subversion package. This package includes JavaHL and installs everything in a way that it is recognized by Subclipse. Download the package at http://metissian.com/projects/macosx/subversion/.

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.

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