Wednesday, 28 January 2009

notes on SVN and Eclipse Team usage

This is just a few notes about SVN and Eclipse Team usage - stuff that has come up recently which I've had to explain and it occurred to me is probably useful to new and existing SVN/Eclipse users.

When using SVN in Eclipse we use the SVN plugin 'org.tigris.subversion.subclipse_1.2.4' which I believe is fairly old now, but seems to work without any problems. We have tried to upgrade to newer versions, but it has caused problems and I don't like to fix things that aren't broken as a general rule.

Note, the 'quoted' actions are SVN actions, but only on the local working copy.

Decorators

There are a number of decorators which indicate the status of files stored under SVN:

When decorated like this, it means that the file, folder's contents or sub-folder's contents have not been changed locally.

--

This decoration indicates that the folder's contents have changed. This could mean that something new is present or one of the files (in any sub-folder) has been changed.

--

This decoration indicates that the file is unknown to the local SVN working copy. It should be 'added' (using Team -> Add to Version Control) and then 'committed' (Team -> Commit). However, if you commit the parent folder a confirmation and comment dialog will appear with a list of resources that are about to be committed. New files are usually left unchecked as SVN does not know what to do with them and will not be push to the remote repository as part of the commit. At this point you can check new filesthey will automatically be 'added' and 'commited' in one fell swoop.

--

This decoration shows that a resource has been 'added' but not 'committed'. In most cases new resources are added automatically when committed if you select them during a commit of the parent folder, but if you follow the process steps explicitly, this is what you'll see. You also most likely see this decoration after a refactoring operation. For instance, renaming a package will:
- create a folder
- 'add' new folder
- 'move' resources from original folder to new folder
- 'delete' original folder

The resources in the new package will decorated having been changed and needing to be 'commited'. All of the above can be rolled back, but I'll describe two methods for that further on.

--

This decoration indicates that a folder has been 'deleted'. This is quite important and is different from how resources (e.g. files) are handled.

If you delete a resource or folder then Eclipse effectively issues the SVN 'delete' command. Resources (files) are removed from the file system, but folders are not. In both cases the working copy needs to be committed and the decoration changes to reflect this.

--

That's essentially it. Eclipse uses decorations to indicate the 'state' of resources and folders.

Rolling Back Changes

To roll back a change there are a number of methods, but from within Eclipse only the following should be used.

Right click on the resource (or parent folder) and select Replace With. There are three options, but to roll back local changes use either Base Revision or Latest from Repository. Only select a branch/tag if you know what you're doing!

Replacing with the Base Revision is often the safest option. SVN stores a copy of all resources so that changes can be undone without having to go back to the server by simply copying the resource back in to the desired location and then updating the state of the working copy. However, there is a down side - if you've 'moved' folders or deleted certain resources, they will not have the supporting SVN data to restore them without contacting the server. You'll get a message like 'resource is not in working copy'. In this instance, you'll have to replace with the Latest from Repository...

Replacing with the Latest from Repository should be handled with care because you'll get any changes that have been committed to the file/folder which might not be compatible with the rest of the resources in your project. For instance, if someone has refactored a method on an interface and you decide to get the latest version of that interface without updating the rest of the project, you might end up with compilation errors.

I tend to use Base Revision for rolling back individual file edits and Latest from Repository for rolling back major refactoring operations.

Copying SVN Controlled Resources

My final note is regarding the copying of resources that are under souce control.

Each folder has a .svn folder within it which contains various SVN related data (e.g. the base revision, and other meta data). Unix operating systems tend to hide files that start with a period and on Windows this folder seems to have the hidden attribute set. In Finder (Mac) and Windows these files and folders are hidden by default. On Windows change the View options to show hidden files (and I tend to apply that to all views). This tip shows how to change a default system property on Mac in order to display these files.

Also note, last time I checked you couldn't create files or folders starting with a period through Windows Explorer or the Command Prompt, though it is possible from with programs, but I haven't checked for years, so that could be different now. If that's still the case, it makes dealing with these folders a little tricky, though you should never have a need to create one during normal usage scenarios.

If you copy a folder that is under source control and then add that folder to another project you'll copy the .svn folder as well.

This will confuse Eclipse, but probably not until you come to commit and you'll get bizarre messages about the resource already being under source control. Even after running SVN cleanup, this might not fix the problem for you as the folders are consider under source control with no problem.

Again, there are a number of solutions:
  • export the source project, which seems to automatically exclude source control meta data
  • disconnect the source project from source control (Team -> Disconnect) and choose to 'Also delete the SVN meta information from the file system'. This approach is often undesirable as you then have to checkout that project again before you can continue working on it.
  • copy the source folder using Finder (Mac) or Windows Explorer and manually delete the .svn folders after enabling your UI to make them visible. Be sure to find them all or you risk partially committing a project in various states, though SVN seems to be quite good at recovering from that if you commit all resources at once (i.e. it seems to be atomic when on the repository side).
Once you've got your folder under your project, refresh Eclipse. Issuing an SVN update command should show you if your SVN working copy is in order.

No comments: