Mac OS X

Lion's Versions Feature

In Mac OS X Lion, applications can make use of a feature to auto-save and version files. This feature locks files that are inactive for editing and when the file is unlocked then starts automatically saving versions. If you have a problem with the file you can then always step back to a previous version of the file. The feature is manifested in the title bar and the file menu of applications that make use of it. When you open a file, it can be locked. Viewing the file in the Finder also shows that it is locked. Clicking on locked provides the option to unlock. Once unlocked you can make changes as you normally would. The next time you save the file, a version is created. Hovering the mouse over the title of a file results in a disclosure triangle. clicking that results in some options otherwise located in the file menu.

Clicking on the Lock option again locks the file. Files inactive can automatically be locked as well. The Duplication option is similar to that of Save As. You are asked where you want to duplicate the file to. No versioning information is sent with the file. These same options are in the File menu as well.

The command-S will still save a file, and in fact now it does more and it saves a new version of the file (also done as part of the auto-save routine). The Revert to Saved options in the File menu and title bar menu will bring up an interface similar to that of Time Machine. You can navigate through here to find a version that you want to restore and restore your data.

Versioning information is persistent across a restore. In fact, once restored, you can revert back to a more recent save than that which was restored. In my testing so far, versioning information is not always persistent across restores of files (works with Time Machine, doesn’t work with 3 other applications I’ve tested). But YMMV there as patches are introduced in (hopefully) the next few weeks. Versions data is stored in /.DocumentRevisions-V100. In the /.DocumentRevisions-V100/db-V1 directory is a sqlite database with information and pages files are stored in containers by UID of local users in the /.DocumentRevisions-V100/PerUID directory. Permissions here are owner of root, group of wheel and d–x–x–x.

bash-3.2# cd /.DocumentRevisions-V100/
bash-3.2# ls -al
total 0
d--x--x--x   7 root  wheel   238 Jul 18 22:39 .
drwxr-xr-x  36 root  wheel  1292 Jul 28 23:24 ..
drwx------   5 root  wheel   170 Jul 28 23:27 .cs
drw-------   2 root  wheel    68 Jul 18 22:39 ChunkTemp
d--x--x--x   3 root  wheel   102 Jul 18 22:39 PerUID
drwx------   4 root  wheel   136 Jul 28 23:27 db-V1
drwx--x--x   2 root  wheel    68 Jul 18 22:39 staging

Changing the permissions to 000 causes the feature to report no versions for the files but then you also cannot save changes to files. If you remove the .DocumentRevisions-V100 directory altogether it does not automatically recreate itself at the creation of a new document; however, it does not create itself initially until the first time you’re saving a document. Putting the directory structure back in place resolves any saving problems (is all this sounding a bit like how Spotlight indexes work to anyone???). Versioning is saved locally for files that are stored on network volumes. If you move a file that was versioned locally to a network volume and back then it will loose versioning information. If you open a file from a network share there is no versioning information in the file unless the local computer you are using had been used to make those versions. When you save a file stored on a network volume you are informed that the volume does not support permanent version storage. If you open the file and start editing it on another host and changes occur on both hosts (which the system will allow to happen) then at the next save you will get an alert that states that the file has been changed by another application. Clicking Save Anyway will overwrite changes from the other computer and Revert will revert to the last saved document or more likely error out with a complaint about permissions (even if those permissions are 777). Continuing to make changes on both hosts will eventually cause a “GSLibraryErrorDomain error 1” error code; however, the file will remain open so you can copy your changes off into another file. A few other points of information:

  • Initially I had read that Time Machine was required to make use of this feature. That is incorrect. It works perfectly well with Time Machine disabled. Having said this, the app does report a message about Time Machine but this can safely be disregarded.
  • Initially I had read that it saves data into the ~/Library/Saved Application State directory. That too is incorrect. The state of versions-enabled applications is saved there but not the data
  • Large (> 500 page files) will auto-save very slowly if you have made a lot of changes in them. This is due to the fact that versioning results in copy operations.
  • Root can traverse into other users version files.
  • I have found no way thus far to change the auto-save interval (will hopefully update this when I do).
  • Pasting graphics into large files is much slower than previous versions (but likely offset by the new ability to flip through versions of files).
  • Not all applications have built-in Versions options yet (e.g. Office) but I think most will at some point in the future.

You can still mv a file to a .zip, unzip it and extract images and raw index data; however the versioning information is not actually saved there. Scanning the file system for changes during a version change only nets the file itself and the temp file (nested within /tmp) as having been altered. The Apple Developer Library explains Versioning as follows:

In the applications that ship as part of Mac OS X v10.7, users no longer need to save documents explicitly or be concerned about losing unsaved changes. Document-based Cocoa applications can opt into this autosaving behavior with a simple override. With automatic saving enabled, the system automatically writes document data to disk as necessary so that data displayed in a document window is, in effect, always the same as the document data on disk. A file coordination mechanism maintains sequential access to files. (See “Mac OS X File Coordination.”) Applications that support automatic saving also support document version history browsing. To browse previous versions of a document, choose Browse All Versions from the pull-down menu at the right end of the menu bar.

For more on NSDocumentController here’s Apple’s page for that.

Overall, Versions has taken me a little while to get used to. Especially in TextEdit. But I’ll take the latency in exchange for the ability to roll back changes. If you are rolling out Lion in a larger environment, you’re going to want to check out whether or not users expect this to persist across network shares, copying files to additional computers or even backups in many cases.