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.
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.
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 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 compatability 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. SVNKit does not currently support the file:// protocol but there are plans to add support for accessing fsfs repositories in the future.
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 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.
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 SVNKit 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.
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.
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.
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):
See also the Subversion links page.
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.xml#svn-ch-7-sect-1 for more information.
If you are using the SVNKit command-line client adapter then see: http://svnkit.com/kb/user-guide-config-settings.xml for more information.
If you are using the JavaHL or SVNKit 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.xml#svn-ch-7-sect-1 for more information.
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.xml#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 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/user-guide-config-settings.html.
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/.
Others: If your packaging mechanism does not include the JavaHL library, then you probably need to build the library 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.
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
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 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.