Monday, December 18, 2006

Mixed Revision Working Copies

Subversion includes a powerful and useful feature known as Mixed Revision Working Copies. However, aspects of this feature regularly cause problems and confusion to new users of Subversion and its various clients like Subclipse. Problems related to this feature come up so often on the Subclipse mailing list that we had to create an FAQ for it.

The definitive explanation of mixed revision working copies can be found in the book that is maintained by the Subversion developers. See: Mixed Revision Working Copies. I'd encourage you to read this explanation, and really the entire chapter contained on the linked page, to gain a better understanding of Subversion and how it works. The following passage summarizes the feature:
"For example, suppose you have a working copy entirely at revision 10. You edit the file foo.html and then perform an svn commit, which creates revision 15 in the repository. After the commit succeeds, many new users would expect the working copy to be entirely at revision 15, but that's not the case! Any number of changes might have happened in the repository between revisions 10 and 15. The client knows nothing of those changes in the repository, since you haven't yet run svn update, and svn commit doesn't pull down new changes."
The end result of this example is that, after the commit, the file foo.html is at revision 15, but the rest of the working copy, including the parent folder of foo.html, is still at revision 10 and will remain at revision 10 until you run svn update.

This scenario trips up inexperienced users later on when they attempt to do something like commit a property change on the parent folder of foo.html or perhaps rename the parent folder. Subversion will not allow a property change, rename or delete of a folder to be commited unless the folder is at its HEAD revision in the repository. When you attempt to commit an item in this scenario, the commit will fail with an error message like this:

Transaction is out of date
svn: Commit failed (details follow):
svn: Out of date: '/Project1/src/folder1' in transaction '1221-1'

The solution at this point is to run the svn update command so that the folder in your working copy is updated to its HEAD revision. Of course all of this is also true for files. The difference is that with files it is much easier for the user to understand when and why they get out of date as it only happens when an explicit change is made to the file or its versioned properties.

In my opinion, users that are using a graphical Subversion client, or IDE integration, are much more likely to run into this problem than someone that uses the command line. The reason is simple, command line users are likely to simply run the svn update command at the root of their project in order to save typing. This has the beneficial side effect of bringing all of the folders in the working copy up to date with the repository. Conversely, a user in a graphical client will often take operations in a context that results in actions only being performed on the specific selections. In Subclipse, as an example, many users use the Eclipse Synchronize view to see all incoming and outgoing changes. This view encourages the user to only commit and update the specific files that have been modified, making it more likely that they will run into this issue.

1 comment:

Anonymous said...

Great, thanks, using Subclipse will be now more clear :-)