Tuesday, December 19, 2006

Subclipse Synchronize Feature: Show Out of Date Folders

Recent versions of Subclipse have added a feature to the Synchronize view called "Show Out of Date Folders". This can be toggled on/off via an option on the view menu and also in the SVN Preferences. It is on by default, and I'd recommend you leave it on. The feature is a response to problems that are created for the user by Subversion's mixed revision working copies feature. See my previous post on that topic for more details and some of the issues you encounter when working with mixed revision working copies.

Historically, the Synchronize view has shown similar output to what one would get if they ran the svn status -u command. With the exception of folder adds and deletes, the svn status command will only include a folder in the list of incoming changes if the properties on the folder have been changed in the repository. However, as my previous post on mixed revision working copies articulates, if any file anywhere beneath the folder, or its children, has been modified, then the folder's revision will also have been incremented within the repository. Consequently, that means that your local copy of the folder is out of date as far as Subversion is concerned. Generally this is not a problem as most day to day activities do not require your folders to be up to date. However, there are several types of changes that you cannot commit unless the folder is fully up to date. Examples of these are if you perform an operation such as setting properties on the folder or if you want to delete or rename/refactor the folder. If you perform one of these operations, then when you try to commit the change, the commit would fail because the folder is out of date.

Just to reiterate this again, every time you commit a change to the repository, all parent folders (all the way back to the repository root) of the items you commit have their revision bumped in the repository. However, the revision of these folders in your local working copy is not bumped by a commit. The folder has to be updated with svn update in order for this to happen. This has caused a lot of confusion with users, especially since the Synchronize view should theoretically show them this.

Well, with the addition of this feature, it now does.

There was a second reason the feature was added, and that was to make update work better -- to allow the Synchronize view to help the user correctly update the folder revisions in their working copy. The Synchronize view is kind of a strange animal, although I cannot think of a better way it could work. When Subclipse populates the view, we are giving it the list of resources that are incoming or outgoing, based on the output we get from running the Subversion status API. The view then uses that list to construct the UI. If you are familiar with the view, you know that it is a tree-like view that shows the folder structure.

Since Eclipse adds the tree structure to make the UI look right, many of those tree nodes are not really there. What I mean by this is that when you select something like the tree root and choose the update option, the Subclipse code that is fired then has to ask Eclipse what you selected so that it can process the option. Eclipse gives back only the resources Subclipse gave it when the view was created, based of course on what you have selected. Subclipse does not receive back the tree nodes that Eclipse created for the UI.

We tried several techniques where we would figure out the UI element you selected and then try to do the right thing, but nothing ever worked perfectly. What worked best was to just update the resources that Eclipse told us you selected. However, this is where the update problem surfaces. Since svn status -u typically does not include folders, Subclipse typically never receives folders as items to update. Consequently, when you would run update from this view, your folders would never get updated and would always be out of date. This feature fixes this problem, as folders now show up as changes and therefore are included in the selections. This has allowed Subclipse to resolve all of the issues we have fought with on getting update to work the way we want from this view.

Of course, there is something of a negative side-effect to this feature too. Namely, that most the time you do not really want to see this extra information. Also, after you commit some files, you are always going to have incoming out of date folders (because that is how Subversion works). There really isn't any way around this. The folders are out of date after a commit, so the view shows them. Now that Subclipse is giving you all the information you need, you are at least armed with the information you need to decide when you want to update those folders.

Update: I rewrote the 2nd paragraph into what is now the 2nd and 3rd paragraph in an attempt to explain this more clearly. It is definitely a hard thing to explain clearly.


Paul said...

Nice post Mark, very useful information. I like the format of the new blog too; Clean, simple and uncluttered.

Anonymous said...

Very useful. Thanks.

Anonymous said...

Thanks for making it clear for me. Was looking through the issues and found it as a bug there. I always thought it was a bug because I believe in earlier test-versions it didn't work correctly when updating with the changes, seem to remember a faulty directory structure at one point. I tried now and it works - so I guess I don't have to restart Eclipse all the time anymore to get them away, yay! ;)

Anonymous said...

"There really isn't any way around this. The folders are out of date after a commit, so the view shows them."

I am trying Subclipse for the first time today and this 'feature' seems like a bug to me. Your text does not describe why my local folders are not automatically updated when I commit a file and the server increments the version properties on the containing folders.

As it is, this means every commit from a user results in a required update: a manual process. You're saying that the software requires a human to take multiple steps and face a UI that /seems/ to indicate someone else made a change until one takes the time to look closely at the revision history.

I'm having a hard time selling this to my users :\ Is there something built into svn that makes it impossible to know what changes "I" have caused by virtue of my own commit?

Mark Phippard said...

It is not a required update, it is information. You are free to ignore it, and you are free to turn off the feature.

Subversion does not do an update as part of a commit and neither does Subclipse. You would not want to receive unexpected changes from other developers as part of doing a commit. The links to the post on Mixed Revision Working Copies explains why this is so.

If you will doing a lot of move/renames or setting folder props, then I would leave the feature on as it wilk likely be helpful. Otherwise, just turn it off.

Anonymous said...

I must concur with "earthe" regarding this issue.

The "Show out of date folders" (working after restart of Eclipse) is not a good enough hack.
The revision numbers on the parent folders should be automatically updated when commiting a file - IF there are no outstanding updates in the repository along that path!

Jens Gabe

PS: The Subvesive client have no probs with this! The correct revisions are shown on the folders after a commit.

Mark Phippard said...

It is not a bug and it is not a hack, it is the way Subversion works, and the article explains why. If you do not like it then try and convince the Subversion developers that a commit should also update your working copy.

Subversive has this exact same feature and it works exactly the same. In the same situation, they give identical results to Subclipse. The only difference is there feature is off by default and ours is on by default.

Anonymous said...

I thought Subclipse was broken for a while when I updated Subclipse because of the new left pointing arrows in "synchronize view" after a commit.

The way Subclipse works now may be technically correct, but it just seems scary and broken to users. Maybe the pref pane where you uncheck this option should explain more or maybe it should be unchecked by default. I for one thought that the latest Subclipse was buggy.

Peter Ewald said...

Thanks for the in-depth explanation, Mark!
I definitely had a hard time in understanding this new feature - and I am the most "advanced" SVN user in our company.
Like nathan and earthe, I would strongly recommend turning that feature off by default in the next release. Experts will always find the way to turn it on, all others will not understand (and not google) it.

Mark Phippard said...

It is off by default in trunk. Unfortunately, since it is a preference, this will only change it for new users/workspaces where the preferences get initialized.

Anonymous said...

Why not simply update after commit if there were no other changes?

rustynut1 said...

Why does a commit bump folder's revision, but doesn't require an up-to-date folder? Common sense tells me it should be both or none.

I agree that automatically updating after a commit is a bad idea. So I think the solution is: if I committed a file, and its folders were up to date before the commit, then the affected local folders should be bumped 1 revision. In the rarest case when someone actually updated the folder between my check and my commit, he would also bump folder's revision, and I'm still going to see it as incoming change since I bump it +1 when it'll be at +2.

Mark Phippard said...

The revision of the folder in the repository is bumped by a commit to any child location. This is a by product of the repository design and the way it "bubbles-up" a change.

The folder only needs to be at latest revision when the folder itself is being committed from your working copy.

Anonymous said...

Mark, I have a question regarding the topic you addressed in your December 19th, 2006 posting on the Subversion Move/Rename feature. Has the issue you described regarding the move/rename feature in Subversion been at all addressed since that posting in recent releases? I am currently on a project in the middle of a decision point as to which source control we should use - MS Visual Source Safe, CVS, or Subversion. Please provide any advice you can, especially as far as any update on the move/rename issue you raised in that posting. Thanks!


Anonymous said...

The described feature looks like a bug. Yes, actually you cannot auto update folders after commit. But just don't show them by default - it will be much better for all users

Anonymous said...

You use the wording ‘this feature’ a few times, and it is not entirely clear to me what you mean by it: the newly added feature to Subclipse, or one of the Subversion features you talk about. Could you maybe clarify this? Specifically, in the penultimate paragraph:

‘Consequently, when you would run update from this view, your folders would never get updated and would always be out of date. This feature fixes this problem, as folders now show up as changes and therefore are included in the selections.’

What is ‘this feature’ here? Yours, or the Subversion one?

Mark Phippard said...

I think the post already addresses your questions. When you perform commits in SVN, the revision of all parent folders is bumped in the repository causing the folder in your WC to technically be out of date. This situation then manifests as a problem if you perform an operation that requires that the folder be in synch with the HEAD revision. So this "feature" is a Subclipse feature, as the blog post heading indicates. The feature is to have Subclipse show out of date folders as incoming changes from the repository so that you can update them to the HEAD revision.

Gats said...

Thanks for this mate. Very helpful info. Implementing source control and tired of saying "I don't know why the icons went blue after you commited".