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 accessible 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). Here is a link to the subclipse installation instructions. These instructions are based upon an earlier version of Eclipse - follow your screens carefully to add a new plugin site for the newest subclipse plugin and select and install it.

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 - fill in the blank)

svn://cslab.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
If a dialog pops up asking if you would like to switch to synchronize perspective answer "No" - stay in the Java perspective.
Assuming your project is not empty, you will have to mark files to place under version control or not. In the package explorer view, you will see small question marks on the icons for files which indicate that the system does not know if they should be put versioned or not. Importantly, also mark files to not place under version control (local.properties, compiled code (bin), various files starting with a ".") with svn ignore. Right-menu selected directories/files in the package explorer and under "Team" select whether to "Add" or "ignore". This can also be done through the "synchronize" perspective.
See "Committing your work to the repository"

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

A small "*" by package explorer icons indicates that there is a difference between the local workspace and the version stored in the subversion repository. Don't leave differences between your local copy and the repository for any length of time. The repository acts as a backup, history and resource for sharing and communicating among the team. Apply a "Commit" operation and make a habit of including comments as you make changes 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. Make a habit of including comments as you make changes to the repository. You should see the version numbers change.

In general you should modify code incrementally frequently updating and committing to the repository. Please don't break the compile! A fresh copy of the project downloaded from the repository should always compile. Teammates working on other parts of the project should not be stymied from their work because changes elsewhere have broken the compile. It is OK to make several commits a day (or even during an hour) while in the process of completing a story.

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.
If needed, 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

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