Using Subclipse (the Subversion Plug-in for Eclipse) for Configuration Management

Laurie Williams, Dright Ho, Sarah Heckman, and Andy Meneely. [Contact Authors]
Department of Computer Science
North Carolina State University

Back to Software Engineering Tutorials

0.0 Outline
1.0 Background of Subversion and Subclipse
2.0 Adding Subclipse Plug-in to Eclipse
3.0 Subclipse Perspective
4.0 Adding a Repository
5.0 Adding an Already Existent Project to the Repository
6.0 Checking out a Project from the Repository
7.0 Committing Resources into the Repository
8.0 Synchronizing Resources
9.0 History
10.0 Disconnecting a Project from the Repository
11.0 Exercise
12.0 Sources and Further Information
1.0 Background of Subversion and Subclipse

Subversion is a version control system, similar to CVS. Subversion is used as a configuration management system to allow multiple users to develop on one project at the same time. Programmers can check out the latest version of the code from a repository, make their changes to the code, and then commit the files back to Subversion. Subversion keeps track of the changes and then integrates the changes back into the main code base or lets the programmer know if other modifications where made between their last download and subsequent upload.

Subclipse is an Eclipse plug-in that provides the functionality to interact with a Subversion server, and to manipulate a project on a Subversion server in the Eclipse environment.

Terminology
In the course of working on a project, a developer should work in the following manner. How to perform all of these task is outlined below.

If the project is new, the following is done the first time:

  • A developer checks in a project for the first time, putting all of the files on the repository.
  • Other developers check out the project into their workspace. If a developer changes workspaces, the code would need to be checked out again.
In the course of working, a developer should strictly follow these steps:
  1. Update their code, to obtain any changes that others made
  2. Work on their code
  3. Periodically (about every half-hour to an hour), the developer should synchronize, which displays any recent changes to the repository and which local code has been changed (synchronize doesn't actually do anything, it just tells you what needs to be done).
  4. If the developer has changed a file locally, and the files on the repository have been changed since the last update, a merge will need to take place
  5. The developer commits his/her changes of the local code to the repository
Top | Contents
2.0 Adding Subclipse Plug-in to Eclipse

If you are working in the laboratory, Subclipse should already be installed.

You can add the Subclipse plug-in to Eclipse by creating an update site in Eclipse and download and install Subclipse.

2.1 Create an update site for Subclipse

2.1.1 Select Help > Software Updates > Find and Install. Select Search for new features to install. Click Next.

2.1.2 Click the New Remote Site button. Give the update site a name, like Subclipse, and type in the following address: http://subclipse.tigris.org/update_1.2.x. Click OK. A new update site will be added to the list.

2.1.3 Press the + next to your Subclipse update site. Eclipse will connect with the site and list all of the updates available. Select the most recent Subclipse update by checking the box next to the update. Click Next.

2.1.4 Check the Subversion feature that you want to install. Click Next.

2.1.5 Accept the terms of the license agreement. Click Next.

2.1.6 Make sure that the Subversion feature is selected to install. Click Finish.

2.1.7 You will be asked to verify the feature that you wish to install. After you have, click Install.

2.1.8 You will now be asked to restart the workbench. Click Yes.
Top | Contents
3.0 Subclipse Perspectives

To change to the Subclipse perspective select Window > Open Perspective > Other... > SVN Repository Exploring.

The SVN Repository Exploring gives you three new views: SVN Repository, SVN Annotate, and SVN Resource History. The SVN Repository view lists all of the current repositories that you have access to. You can also create a new SVN Repository. The SVN Annotate view shows the annotations of a file in the repository. In order to view the annotations of a file, you must right click on the file and select Team > Show Annotations. The last view, SVN Resource History, shows the revision history for a file that is selected in the SVN Repository view.
Top | Contents
4.0 Adding a Repository URL to Subclipse

To add a repository you can right click in the SVN Repository view and select New > SVN Repository, or you can click the add repository button in the toolbar of the SVN Repository view.

4.1 First you need to fill out the URL for the repository.

4.2 Provide your user id and password.

4.3 Click Finish.

Your repository will be located in the SVN Repository view.
Top | Contents
5.0 Check In: Adding an Already Existing Project to the Repository

Switch to the Java perspective or Plug-in perspective where your project is located.

5.1 To add your project to the repository, right click on the project and select Team > Share Project....

5.2 Select SVN from the list of repository types. Click Next.

5.2.1 If the project had not been previously shared, Eclipse will ask if you would like to create a new repository to share the project in or if you would like to use an already existent repository to share the project in. Choose the repository that you have already created for your project and click Next.

5.2.1.1 Select the radio button that says Use project name as module name. You can choose to have other module names if you are afraid of name space conflicts. Click Next.

5.2.1.2 Click Finish.

5.2.2 If the project has been previously shared, Eclipse will ask if you wish to connect. Click Finish.

By convention, a project should be located in the trunk/ directory of the repository, NOT in the root. If an Eclipse project is in the repository (e.g. iTrust), then the project should be in /trunk/iTrust/.
Top | Contents
6.0 Checking Out a Project from the Repository
Switch to the SVN Repository Exploring perspective. Click the + next to your repository. To check out a project right click on any folder/project and select Check Out as Project. If the project that you are checking out already exists in the workspace, the old project will be destroyed and the project from the SVN repository will be created in its place. Otherwise a new project will be created in the workspace. Switch back to the Java or Plug-in Development perspective to modify the code.
Top | Contents
7.0 Synchronizing and Committing Resources to the Repository

Any resources that you have modified will have a black asterisk in front of the resource name, and any added will have a question mark in front of the name.

It is always a good idea to see what needs to be done before committing files.

To synchronize resources, right click on a project and select Team > Synchronize with Repository .... You will be switched to the Team Synchronizing view. From there you can look at your outgoing changes, and others incoming changes, and synchronize your code before committing to the repository. Double-clicking on a file will open a side-by-side view of the file and its changes.

If a file has a two-way red arrow on it, then there is a conflict. Someone else has changed that file while you were working on it. Double-click the file to get a compare editor, and copy-paste what you need to resolve onto your local copy. When you have the local copy finished, right-click on the file and choose Mark as Merged. Note: PLEASE USE THIS FEATURE RESPONSIBLY!! Think very hard before selecting "Mark as Merged", as it will override what is in the repository. An entire history is kept in case you make a mistake, but always pause and check your work before marking as merged.

Note: constantly updating your code from the repository helps avoid conflicts
Top | Contents
8.0 Synchronizing Resources

To commit changes to files in your project, right click on the project and select Team > Commit.... Or, if your are in the "Team Synchronizing" perspective, right-click on the resources and select "Commit". Then you will edit the commit comment, or add a new commit comment to document what changes were made. Always add meaningful commit comments! There is also a list of previously used commit comments to choose from. Once you have committed code, the black asterisk should be gone from modified files.
Top | Contents
9.0 History
To compare your code with the latest from the repository, you may either recheck out the project or right click on the project in the Java/Plug-in Development perspectives and select Compare With > Latest from repository. Using copy and paste, one can recover old code this way. Using Compare With Revision... or Replace With Revision are also helpful.

Also, Team > Show History shows an entire history of a folder/file.
Top | Contents
10.0 Disconnecting a Project from the Repository
Switch to the Java/Plug-in Development perspective. To disconnect a project from the repository, right click on the project and select Team > Disconnect. Eclipse will prompt asking if you wish to delete the metadata associated with the Subversion connection. Choose No. If you choose yes, you will have to delete the project in your workspace in order to check out another copy of the code.

Note: You will rarely need this feature.
Top | Contents
11.0 Exercise
Submit a file called "subclipse_answers.txt" which has the answers to the following questions.
  1. Suppose you are working on your code which as already been set up on the repository and has been set up on your machine. Place the following actions in the order in which you should work (some may not apply!):
    • Check-in
    • Check-out
    • Commit
    • Update
    • Synchronize
    • Work on your code
    • Mark as Merged (if necessary)
    • Resolve conflicts (if necessary)
  2. Suppose you have not set up your code in the repository yet. Place the following actions in the order in which you should work (some may not apply!):
    • Check-in
    • Check-out
    • Commit
    • Update
    • Synchronize
    • Work on your code
    • Mark as Merged (if necessary)
    • Resolve conflicts (if necessary)
  3. True or false? Developers should be committing to the repository often. Please explain why you chose that answer.
  4. True or false? Synchronizing your resources is the same as updating and committing, but in one step.
Top | Contents
12 .0 Sources and Further Information

Top | Contents

Back to Software Engineering Tutorials
Using Subclipse (the Subversion Plug-in for Eclipse) for Configuration Management Tutorial ©2003-2009 North Carolina State University,
Laurie Williams, Dright Ho, Sarah Heckman, and Ben Smith.
Email the authors with any questions or comments about this tutorial.
Last Updated: Wednesday, June 28, 2006 1:59:49 PM