Generally, developers don’t use source control from within their IDEs or put off integrating their own code with the project source control because they believe that doing otherwise is easier and faster. This misconception — like most misconceptions — is quickly dispelled with a little better understanding.

In this tutorial, I aim to provide that understanding for reluctant developers by walking through integrated source control with Eclipse and Subversion (SVN). While the focus will be on this specific IDE and Source Control combination, both tools are standard and the concepts will be common to most environments you may work in. If you work with Java and/or J2EE, most of the popular tools are extensions of the Eclipse and Subversion combination.

Installing the Eclipse SVN Plugin

If you’ve never installed an Eclipse plugin, the standard process is very straight forward, despite the circular and confusing FAQ entries at Eclipsepedia. I found a very detailed set of instructions at an NCSU URL, and the update site for Subversion (my preferred SVN plugin, there are others) is helpful. While Subversive is an official Eclipse project, you will need to go to the project sponsor’s site for additional download locations and installation options.

Assuming you have gone the recommended installation route of using Eclipse Update Manager, most users will need to select only one of the offered installations from the Subversive install site, which is currently the last option, Subversive SVN Team Provider Plugin:

If you have a 64-bit version of Windows, you also should select the Subversive Client Libraries. If you aren’t certain if you need it, you can always install it later. Some people are tempted to simply select all of the installations, but some of the options could conflict with other plugin libraries, so unless you actually need the other options, don’t select them. Once you have made your selections, follow the usual acceptance of license and ignore any warnings about unsigned content.

Select the Restart Now option when it is all over with, and afterwards you will have some new perspectives to use. I strongly suggest leaving the SVN Repository Exploring perspective always open. For new users it acts as a reminder to keep in synch with the project, and for advanced users it saves a few clicks when you want to managed your repository.

Connecting to an Existing Source Repository

Most developers will be connecting to an existing project the first time they use SVN. Many new users create their connection at the root of the repository and then become overwhelmed with the full directory structure. For new users I recommend connecting to a single project or group of projects. With SVN, locations are URLs, so if someone gives you only the root URL, you can go to a browser and drill down to the URL you want.

You can now use the more direct URL to connect to your repository. The following screens will walk you through the process.

Recall that some 64-bit Windows installations require the client libraries. If you receive the following error at this point, you will know that for certain:

Even if you selected the Subversive Client Libraries during installation, you still need to configure the client per workspace in the Eclipse Options:

Once connected, you will be able to browse the repository from the point of the URL you entered when creating the connection.

While the Subversive plugin facilitates creating properly formatted Eclipse projects, it does not enforce it. We will look at how to add the project correctly so that it integrates easily with Eclipse, and proceed with the Pollyanna assumption that all projects will be properly formatted. To add the project to your Eclipse workspace, right-click and select Find/Check Out As.

In some cases, projects are grouped in SVN. If your repository projects are grouped, you can start the process one step higher on the tree (MyImportantProjects, as illustrated in Figure 9: Use Find/Check Out As… Option for Eclipse Projects). The plugin then will find the projects for you, if asked.

Projects and files under source control will indicate their current state with icons. These icons are very intuitive, such as a database image to indicate under source control, a question mark to indicate an object in a managed project is not managed, the “>” symbol to an object with changes locally. A list of the icons, their meaning, and how to manage them (for advanced use) can be found at here.

A Couple of Notes about File Commit Before We Continue

We will look at these two sub-topics before we go further so they will not become a distraction later.

1. Some Eclipse packages have missing or conflicting UI libraries that cause the following error message when checking files in:

   

2. When you commit files you will be promoted to make a comment. You should. It may never matter if you don’t, but the one time it does matter, you can’t go back.

Managing Files Inside Eclipse with SVN

Once your files are managed by SVN, managing them is fairly simple. Files and folders have intuitive options accessible by right-clicking and then navigating down to the Team menu.

Here are brief descriptions of the common tasks you will perform on a daily basis.

• Update. Referred to as Get Latest or Checkout, the icon illustrates that this option will bring in updates from the repository to your IDE. Generally, only files that you have not changed locally will be updated, though I have seen exceptions to this, so it is best not to rely on your un-committed changes being preserved. If you want to update and preserve your un-committed changes, update at the file level or use the Synchronize with Repository option.
• Commit…. This will commit your changes or new objects to the repository. Unless you locked the file before making changes, other users could have committed changes while you were working. If this is a possibility, use the Synchronize with Repository option instead first.
• Add to Version Control. This will add an object to version control but not commit it. I personally never use this option.
• Lock. This tells the world that you and you alone are working on this file at this time. Only lock a file if you really need to prevent others from touching it, and be sure to release the lock when you are done. While the lock can be over-ridden by power users, it is an annoying task to do so.
• Show Resource History. This is useful to if you need to revert to an older version or go hunting for the person that didn’t read this article and wiped out your last set of updates.

Except for Synchronize with Repository the other options are used less frequently and mostly by advanced users.

Don’t Just Update, Synchronize!

Synchronize with Repository is what new users should choose in lieu of Commit and Update until they become more proficient with the tools and know the code base very well. Selecting Synchronize with Repository with prompt you to switch to the perspective, which I strongly encourage you to do, and to check the Remember my decision for convenience’s sake. Synchronize with Repository will allow you to see all changes you have made and the changes that others have made.

While the number of features in this perspective may seem overwhelming at first, they quickly become familiar and easy to use. In this perspective, double-clicking a file opens it in compare view. If an icon indicates conflicting changes, this is where you can decide to over-ride with your changes, the changes in the repository, or merge the changes. If you try to commit from another perspective and the object still shows the “>” icon with no error message, it is often because there is a conflict that can be found and resolved quickly from the Team Synchronize Perspective.

There is detailed documentation available at the workspace synch documentation page, though most users should be able to get by just from the interpreting the icons.

One tip about using the Synchronize with Repository option: If you later create an Eclipse project that contains different SVN projects as folders, only run Synchronize with Repository on the folders and not the full project. Selecting the full project will result in the Subversive trying to synchronize the entire repository from the root down since the actual project itself is not an SVN project.

Creating New Subversion Projects in Eclipse

Adding new projects is very easy. The only difficult part may be determining the repository structure, which is decision based on preference and source management requirements rather than technical limitations. The structure used in these examples is not meant to represent an ideal option; it is only one chose for convenience during the writing.

Right-click on the project to add and select TeamShare Project.

From this point on, you can do yes, yes, next, next, and so on. As noted earlier, comments are up to your own conscious or your team processes, whichever you follow.

Common File Handling Tasks

There are a couple of common tasks that, while not used on a daily basis, are handy to understand.

Moving Files

If you need to re-package files, there are several options. Simple moves can be accomplished by using the standard Eclipse refactoring menu and then checking in from the highest point in the tree of the changes. More complex moves are easier to check in from the Team Synchronize Perspective, keeping in mind the various dependencies involved, such as the folder needs to be in source control before the file within it. Also, you want to commit the new location before committing the old location, which is a delete. Large moves are more easily managed using the Refactor context (right-click) menu in the SVN Repository perspective. This perspective provides access to the full repository, so it is slower than the other options, but definitely safer if you are unfamiliar with moving files in SVN.

Managing Non-Source Files

More than just source control, Subversion is a handy place to store project files. Admittedly I was initially against storing documents in a source control application, but it had so many advantages that I changed my mind.

In many cases locked-down enterprise machines won’t allow installing various file management applications or block the ports that such applications use. Often this does not extend to Eclipse plugins and the ports used by SVN.

To store documents and other non-source code files in Eclipse, it is easiest to create a single project in Eclipse for such items. If your repository is structured to manage these files then you can simply check out the relevant project. If not, you can create a generic project in Eclipse and then check out the non-code folders from SVN as Folders in a Project.

Free and Low-Cost Services

Here is a listing of free SVN project-hosting services. I used XP-Dev only because I received a certificate error with Firefox at OpenSVN and sometimes need to access the repository from secure networks.

Those Pesky SVN Files

One thing I don’t like about SVN is the .svn files it leaves behind. They use up a lot of disk space and make it a pain to migrate files from one machine to another outside of using SVN. This happens regardless of whether you integrate with your IDE or not. A couple of workarounds I have found to this is to export projects rather than copy them in the file system, and to use Robocopy with anything including .svn to be ignored (/XD *.svn).

One thing that people run into when they transition from managing their SVN repository from outside Eclipse is accidently importing the svn files into their projects. The simplest fix is to start a new workspace. If your build process picks up all files, you should configure it to ignore the SVN file.

Conclusion

If ignorance is bliss, I hope you have something other than source control from within your IDE to keep you happy. All kidding aside, they say it takes only three to seven times to make something a habit, so practice these tasks daily for a couple of weeks and you probably will forget ever having done differently.