Version Control Concepts

In an iterative development process (like Extreme Programming) files undergo numerous changes. Keeping track of all these different versions becomes critical. Code, owned by the team, needs to be accessable by everyone. The diagram below shows some of the basic concepts and terminology of working with a software repository. Developers code within a working directory on a local machine while group access is provided by placing and retrieving code to and from a repository available to the team (steps 1-3 in the diagram).

Some Issues to Consider

These issues are rather generic to the concepts of version control. Different tools and teams may develop particular policies to handle them.

Not all files should be stored on the repository; in particular files that can be generated from primary sources (such as binaries from source code) do not need to be stored. There may also be files which help to set each individual machine's local environment.
Various versions of files can be stored. How to refer/to retrieve other than the latest? Branching versions?
The commit process also provides an opportunity to comment on the modifications made.
Can a file be checked out by multiple developers? What happens when changes conflict?
What happens if bad code is committed (ie. compile breaks)? How to handle?
How to physically implement the repository? (shared memory, CD/disk, server machine ...)

Using Version Control from within Eclipse

In this tutorial article we will examine subversion, a freely available open source tool for storing, sharing and managing code. Subversion is a free open source version control system and is widely regarded as the successor to CVS, which is another widely used version control system (most features of CVS are also in Subversion).

Like CVS, Subversion uses a client-server model to allow multiple users to access a code repository stored on a Subversion server. Here we describe several common Subversion operations using Eclipse with the subclipse plugin as the client for accessing projects stored on the Subversion server.

Connecting to the subversion server (must be on SIUC network or using VPN)

Register your repository with Eclipse

Change to the SVN Repository Exploring perspective (Window->Open Perspective->SVN Repository Exploring)
Use the right menu within the (probably empty) SVN Repository view. Select New->Repository Location...
You will be asked for the repository name as a URL. (Typically something like)

svn://lab.cs.siu.edu/___________

Putting an existing project under version control

To begin with, we assume that you have an existing Java project that you would like to place into Subversion. Furthermore, we assume that the Subversion repository has already been registered.

Change to Java Perspective (Window->Open perspective->Java).Right click on the existing java project that you'd like to place under version control, and select Team->Share Project
In the Share Project dialog select SVN and click next.
In the Share Project with SVN Repository dialog box, make sure that Use Existing Repository location is checked and that the repository location you registered earlier is selected. Click next.
By default, the Subversion folder name is the same as the Eclipse project name. Check the Use project name as folder name radio button and click Finish
Assuming your project is not empty, you will have to mark files to place under version. Importantly also mark files to not place under version control (local.properties, compiled code, various files starting with a ".") with svn ignore.

Checking out a project from the repository (first time)

A co-worker could obtain the project from the repository by checking it out. The SVN repository should be registered for the coworker's Eclipse environment. Then these steps should be followed to initially place the project on that machine.

Change to SVN Repository perspective (Window->Open Perspective->SVN repository exploring) and expand the HEAD entry in the repository . Doing so shows SVNROOT directory (SVN's administration directory) and any modules that have been checked in to this repository.
Select the module (not entire repository) that you are interested in, right click on it, and select Checkout from the context menu.
In the Checkout from SVN dialog, use the Project Wizard. and hit "Finish". The Wizard will ask more questions.
Specify that it is a Java Project. Allow it to be created in your workspace and give it a good name. Check the option that says it will use separate folders for source and binaries. Hit finish. The warning about overwriting should not be a problem if you are creating a new project in your workspace ( you have named it uniquely).
Allow the system to switch to the Java perspective.
Add your local.properties file for the location of Junit on your machine. Tell svn to ignore this file.

Refreshing your local copy of a project with the latest files from the repository

If this project is already in your workspace and you want to get the latest files from the repository (Your local files will be overwritten with files from the repository)

Select the project in the navigator view. Right click on it select Team->Share Project. Enter your user name and password.
Right click on the project again and this time select Replace With->Latest from Repository
In the Confirm Overwrite dialog, click OK.

Adding a new file to the repository

Note that just adding a file does not cause it to be placed in the repository, it must also be committed.

Place the file under version control (Right click on the file then select Team-->Add to Version Control)
Commit the file (Right click on the file then select Team-->Commit). Be sure to give meaningful commit comments.

The development team should carefully consider the directory structure of a project. For instance source files, image files, libraries, documentation etc. may all be placed in separate directories. Adopt standard conventions for your team.

Updating your files with newer information from the repository

Refreshing your local workspace copy of code with the latest version from the repository is called updating. Right click the file, and select Team->Update, and then resolve any conflicts (if you have changed the same lines that someone else has changed). Alternatively if you just want to replace your version with what's in the SVN repository, right click on the file/project and select Replace With->Latest from Repository.

If the update reveals conflicts - Eclipse combines the changes into a single file that you need to edit by hand. This is a messy error prone process which is more conveniently performed by merging using Eclipse’s Synchronize Repository feature.

Select the project in the Package Explorer and right-click on it.
Select Team->Synchronize with Repository from the context menu.
Double click the file on the structure compare view to take a look at the synchronization issues for that file. Note the side by side comparison going on; here the local file is compared to that of the repository. Lines appear connecting the differences.
You can use the up and down arrow buttons in the Java Source Compare view to navigate between changes. You can also use the two arrow buttons next to the navigation buttons to accept or make changes. The button with the left facing arrow copies the current change from the repository to your local code, and the button with the right facing arrow copies the current change from your local file to the repository.
After you have synchronized your version of code with that of the repository, right click on the file name in the Synchronize view (if not open, then open it with Window->Open Perspective->Team Synchronizing View) and select Mark as Merged to indicate that you’ve resolved the conflict. Commit the file by right clicking on either the file name or the project name and selecting Commit. Enter a comment when prompted.

Committing your work(in your local workspace) to the repository

Right click on the individual file or project and select Team->Update. (Conflicts may need to be resolved.)
Again Right Click on the individual file or project and select Team->Commit. You should see the version numbers change.

Additional References and Information sources

Subversion book

Subversion FAQ

This article was put together over several semesters with the help of CS435 TAs throughout the years. Thanks.
Ajay Narayanan, Kalyana Gundamaraju, Pranav Shrestha, Leon Zhou
-Michael Wainer