The framework behind our great image browser.

• Easily get folder contents

• Stay up to date as files get moved, deleted, renamed, and updated

• Implement move, copy, rename, and move-to-trash from within your app

• BSD license

Download Now

See on Github


OS X Framework


The IMFilesystemTools framework is a very useful tool for developers whose applications work with large file heirarchies. While writing gBrowser, we discovered that keeping track of files and associated information was our #1 job, and this framework was born of that need.

Keep up with filesystem changes

What happens when the user – or some other process – moves, renames, deletes, or updates a file that your app wants to know about? For a few files, you might use GCD with a DISPATCH_SOURCE_TYPE_VNODE source for the folder they’re in, then re-scan the folder any time there’s a change. For larger jobs, it’s probably more efficient to use FSEvents. But even FSEvents only does half the job – it’s still up to you to scan your folders and figure out exactly where and what the change was. This means keeping track of the state of each of your files and comparing that with the current state of the filesystem whenever you recieve one of those notifications. That’s a lot of work. The IMFilesystemTools framework is there to keep track of every file your app is using. It retains data about the state of every file in your heirarchy, and when something in your heriarchy changes, it will very efficiently scan the directory in question and report the specific changes to each file back to your app.

Not just filesystem updates

We make a big deal about tracking file changes because it’s a lot of work, but IMFilesystemTools isn’t a one-trick pony. The IMFilesystemTools makes it easy to quickly and efficiently read the files in a directory or recursively through a whole heirarchy.

File operations

The framework includes methods to do large-scale Finder-style copying, moving, and deleting of files, with appropriate validation and progress updates.


The IMFilesystemTools framework takes full advantage of NSOperationQueues and NSOperations. When you read a directory’s file listing, you can choose to do this in a background thread. If you need to scan in an entire heirarchy, the framework’s built-in method to do so can utilize threads as well, with no extra effort on your part.

IMFile objects & subclasses

IMFilesystemTools deals with IMFile objects – or whatever subclass of IMFile you choose to create and use. The framework ensures there’s only one unique IMFile object for any unique file in the filesystem, so IMFile subclasses are a way to efficiently reuse file-related data and metadata when your app is working on files in multiple places. For example, gBrowser uses this when displaying the same files in the sidebar, thumbnail pane, and a slideshow – if the user chooses to display file size information in all of these places, it is only looked up once and cached thereafter.  Each IMFile object also keeps track of the current state of the file with the help of the IMFileManager, so whenever the file is changed in some way, your information can be automatically updated. And because each IMFile object is unique and hashable, they can be used in sets or as keys in dictionaries , which turns out to be very useful. The IMFile class gives you quick and easy access to file information, such as the file’s path, url, FSRef, file type, uti, display name, modification date, and whether it is a folder / bundle / package / application / visible / invisible / alias / symlink. Your own subclass can give you even more power.

Persistent file data

IMFile objects (and subclasses) are able to write persistent state data to an NSDictionary for archiving to disk. When your app wants that data back later, it can unarchive the NSDictionary and pass it to the IMFilesystemTools framework to get ahold of that IMFile object again (even if the file has moved), complete with whatever metadata the subclasses chose to store.