SVN for Eclipse Quickstart for Beginners

This is well trod ground, but I didn’t find a lot of really basic info about what to do, what not to do, and generally how to get your feet wet with SVN, and what to do when suddenly you’re up to your neck. I’m certainly no expert on source control, but sometimes a fellow beginner can explain things more gently.

The first hurdle is getting the plugin(s) installed. I’m personally not sure which are best. Try them for yourself and see. At the time of writing, here are the Eclipse update URLs to add for installing several SVN-for-Eclipse clients. I like the subversive icon set on the Team menu specifically, so I’m including it even though the download site was an absolute pain. I had to download to my local drive first. Your mileage may vary.

• http://eclipse.svnkit.com/1.3.x/
• http://subclipse.tigris.org/update_1.6.x
• http://download.eclipse.org/technology/subversive/0.7/update-site/ (if it works for you, didn’t for me) I downloaded from:
• http://www.eclipse.org/downloads/download.php?file=/technology/subversive/0.7/builds/Subversive-incubation-0.7.8.I20090904-1300.zip”>Subversive-incubation-0.7.8.I20090904-1300.zip

Here’re those pretty icons. I like them because they help remind me what direction the operation goes in. “Update” Does that mean update my stuff or their stuff? “Commit” Which direction is that?

1. Go to the Window Menu >> Software Updates
2. Go to the “Available Software” tab
3. Add Site
4. Enter the URL or local hard drive path
5. Click OK
6. Click the Refresh button on the list of  update locations.
7. Wait for Eclipse to do its thing.
8. Check off the subclipse, subversive, and / or svnkit bits you’d like to install.
9. Click the Install button.
10. Restart Eclipse.

Next hurdle is getting logged in. If you’re also setting up your first SVN server, best of luck to you. We’re not covering that here today. You probably want to be familiar configuring an SVN client before you try setting up a server as the access control can be really tricky, especially if it’s remote, which, usually it is.

Window >> Show View… >> Other… >> SVN Repositories

Right-click (Control-click Mac) >> New

Set yourself up a connection with the URL, username, and password provided by your system administrator.

Say a prayer.

With any luck, you’ll be browsing the project tree!

Checking out a New (to you) Project

Browse to a project you’d like to check out in the SVN Repositories window.

Right-click (Control-click Mac) >> Check out

What you select from here depends on whether your team members have agreed to share their entire Eclipse project workspace (the second bullet) or if individual team members are managing their own Eclipse projects on some level (the default bullet). Confer with someone already on the project.

Click Finish!

Take a moment and look at the SVN Settings for icons in the Explorer view. You’ll actually learn a little about the terminology you’ll soon master, and begin to be able to recognize the state of a file by glancing at it’s icon and know what step needs to be done next.

Eclipse Menu >> Preferences… >> Team >> SVN >> Label Decorations

Go to the Icons tab.

If you toggle the checkboxes back and forth, you’ll be able to see which labels go with which icons. This is really useful to know.

Adding a New (local) Project to the SVN Repository

Chances are, if you’re just starting, your first project already exists, and you can skip ahead for now. If not:

Right-click your main project folder in the Explorer view >> Team >> Share Project

SVN >> Next

Choose your repository >> Next

I think “Use project name” is best. Next

Get used to entering comments that describe what you’re checking in. This dialog gives you the opportunity to do that. It’s probably pre-populated with something brief about sharing this project.

Click Finish!

The project will be analyzed and you’ll be given the opportunity to de-select any files you don’t wish to add to the repository.

Once the files are successfully shared via SVN, your files’ icons should change to reflect their state with respect to SVN. This comes in handy. You’ll also see a version number appended to your filenames. You can modify details in Eclipse preferences.

Adding a New (SVN) Project to Your (local) Workspace

Use the SVN Repositories view to browse to the project’s root folder.

Right-click and choose “Check Out”

If you already have a project at the default location, you’ll be asked to reconcile conflicts / overwrite files. Otherwise, you should have a brand new project in your workspace!

Getting the Latest Updates

Ok, someone’s made a change to files you’ve previously checked out, and you need to update your local copy.

Always do this before making changes (see the next section). It will keep you and the rest of your team from spending a lot of time in the last section.

Right-click the project folder >> Team >> Update

Commits – Making Changes

You’ve changed some things, and you’re ready to check them into the repository.

Right-click the project folder >> Team >> Commit

(It also doesn’t hurt to update again after a commit.)

Adding Files

Some SVN clients require you to “Add” files to the repository before you “Commit” your changes. It’s a bit like when you “add,” you only add an empty entry. It’s the commit that sends the data. This separation keeps you from thinking you’re adding a brand new file, when in fact there’s already an existing file with that name in the repository. Eclipse’s plugins seem to handle this automatically.

Deleting Files

Delete the file(s) as you normally would.

Perform a commit on the containing folder. SVN should detect the change and update the remote repository.

When Things Go Wrong (and They Will)

I can’t Update because I’ve got a conflicting Local File.

(or)

I can’t Commit because there’s a conflicting Remote File.

Sometimes, the conflicting changes can be (and are) resolved automatically. Sometimes, it’ll require more manual effort. The parent folder will have some new files with names based on the one having a conflict.

MyClass.as (your local working copy — it probably contains some diff comments now)
MyClass.as.mine (an untouched copy of your local version)
MyClass.as.rVERSION_NUMBER (the last good copy known by both the local machine and SVN)
MyClass.as.rVERSION_NUMBER+ (SVN’s latest copy)

If you don’t see these in your Explorer view, right-click the parent folder and choose Refresh.

Still nothing? Do an Update and repeat.

There should be enough here to help you resolve the issue and no risk of loosing anything.

Edit MyClass.as so that it contains whatever you now believe to be correct. You can use Eclipse Synchronization perspective, an external diff / merge tool (I like DeltaWalker), or the standard Eclipse editor.

To use Eclipse’s tools, Right-click the file with conflicts >> Team >> Edit Conflicts

The local working copy should appear in a left pane with the most recent repository version on the right. The goal here is to get the local working copy to contain the “correct” code. Merge anything from the SVN version on the right that should be present in the new version. (Eclipse will not allow you to make any edits to the SVN version.) When you’re done, Save. Close the Edit Conflicts tab. Your changes should migrate to the local working file. Note: If you Edit Conflicts again (before Committing), you may loose the merges you made the first time. This is a bug or a feature depending on how you think about it.

I set up a custom DeltaWalker launcher shell script as an external diff / merge tool. Let me know if you’d like to try it. I doubt there’s much (any?) functionality that isn’t available in Eclipse’s Edit Conflicts, but I really like DeltaWalker’s GUI, color scheme, etc.

Right-click the file >> Team >> Mark as Merged (or Mark Resolved…) Click Ok.

Immediately Commit changes! You aren’t finished resolving the conflict until you do so!

The Three-Way Merge

What you’ve probably worked with so far is a two-way merge. SVN also keeps track of the latest known good ancestor to those two files. In the Edit Conflicts view, click the icon in the toolbar to enable this pane. I rarely find this necessary, but it’s good to know it’s there if you need it.