Skip to content
  • Florian 
  • 9 min read

Folder Comparison Reinvented

Recently, we have spent a lot of time on many aspects of the folder comparison feature for Kaleidoscope 4.4 and 4.5. We have overhauled some of the underpinnings and worked hard to improve reliability and speed. But we also added some major new features. It’s time to tell you a bit what they are and how you can benefit from those changes.

Give me an outline!

For years, an outline view (aka tree view) has been by far the biggest request. Most people don’t just compare two simple folders with a handful of files. Typically, the folders you are comparing contain subfolders, often lots of them, several levels deep.

When comparing two folders of that type, you don’t just want to see what’s changed on the top level. You really want to understand what has changed in the entire folder hierarchy. Until the advent of Kaleidoscope 4.4, if you wanted to know why two folders were shown as different between A and B, you had to double-click changed folders until you arrived in the directory that contained the changes, in the form or removed, added or changed files.

Here’s a screen recording using Kaleidoscope 4.3.1. We are comparing two tagged versions of the Earthworm project, popular on GitHub. We dive down into one folder named apps that is shown as different on the top level. We have to burrow down through 4 levels of folders to arrive at the file app.module.ts and see the actual changes that caused the difference we can see on the top level.

Comparing two folders in Kaleidoscope 4.3. It takes 5 steps to find out what actually changed in one file in a nested folder.

Enter Kaleidoscope 4.5

Now you can expand any folder, synchronously in A and B, without the need to open a new document. In addition, upon completion of the difference calculation, Kaleidoscope will automatically expand folders with changes in them and leave all the others collapsed. This means you’ll get an overview of all changes with no additional interaction required.

Let’s revisit the Earthworm example. In this screen recording using Kaleidoscope 4.5, you see at a glance that a file named app.module.ts, several levels deep in the hierarchy, has been modified. You don’t have to do a thing to see that. You probably don’t even care about the rest of the folder names in the hierarchy. Just double-clicking on the file opens the text comparison, and shows you the exact changes of that file.

Comparing the same folders using Kaleidoscope 4.5: you immediately see all changes and it takes only one step.

Always remember that you can also filter items in order not to display items that are identical or unmatched. This way, you will only see items that exist both in A and B, and do not match. In the sample above, we chose to not show identical items, as they are typically not very interesting when trying to determine what is different between two folders.

The outline works as you would expect as a power user: option () clicking a folder will not only toggle its expansion state but also the state of all children. When navigating with the keyboard, hit and to collapse and expand, and use ⌥◀ and ⌥► to toggle children along the way. And there are commands to close all folders and expand the changed ones, accessible both from the bottom toolbar and the View menu.

Opening items

As before, you can still double-click a folder (or use the enter key, or Navigate > Open Selection) to open that item in a new document under a tab in the same window. This is helpful when dealing with larger structures, or when trying to copy items from one side to the other.

Using the same method, you can compare text and image files directly from a folder comparison, as you would expect, and get all the great comparison features for text and images.

Sometimes you just want to quickly glance at the content. For that, hit the space bar (or View > Quick Look ⌘Y) to get a Quick Look preview of that item. This is particularly useful for file types that are not natively supported by Kaleidoscope.

Automatic updates

As you are making changes to folders you are comparing, Kaleidoscope will dynamically and quickly update the comparison, on any level. This never used to work in deeper levels of the hierarchy. Now it does, and it is very helpful.

But be aware when comparing directories that receive numerous changes, such as project folders of an IDE in Xcode or VSCode. Each change will trigger a recalculation of the comparison, and while some data is being cached, you could still end up in a loop where comparisons never finish.


And we didn’t forget about the metadata details, which makes the folder comparison even more useful.

The date format now changes depending on available column width, so that dates don’t get cut off. When hovering over any information, you get a tooltip with precise information. For Name, you get the entire path, which helps with deep structures. For Date Modified, you always see a more complete format, and for Size you can inspect the exact byte size. Also new: folder sizes are displayed.

Kaleidoscope shows tooltips with more information when hovering the Name, Date Modified, or Size column.

When an entry is an alias or a symlink, the name is shown in italics, like the Finder does, and the size displayed in that case is the size of the link, not the size of the linked file, as was previously the case.

Metadata Differences

When Date Modified or Size for an item is the same between A and B, a regular font is used. If there is a difference, the font style is bolder. In addition, the side with the more recent date or the bigger size is shown in blue, providing you with information at a glance.

Metadata shown in semibold when different between A and B.
Additionally shown in blue on the side where Date Modified is more recent and where Size is larger.

Also note that the screenshot above uses large icons and a bigger font size. Head to Settings > Folders to find new customization options. This is also where you find an option to turn off the automatic expansion of folders with changes.

File Properties

To see metadata for the folders that you are comparing, head to the File Properties (View > Show File Properties or ⌘I). This shows a popover with detailed metadata, including Creation Date and Permissions.

If you want to see those detailed properties for any item in your comparison, just double-click that item and look at its File Properties.

The File Properties popover.

More info for the curious

Some of our customers are very tech-savvy and want to know how the folder comparison works. In particular, users notice that sometimes information changes while the difference is being calculated. Items are initially shown as different but later on marked as equal. Why is that?

Here’s an overview of how Kaleidoscope figures out the difference between two folders:

  1. In a first step, Kaleidoscope looks at the top-level items in A and B, so it can quickly show something to you, while it’s still busy doing steps 2 and 3.
  2. In a second step, all directory contents on all levels are being gathered and metadata about items (name, size, dates, …) and read from disk. Depending on the total number of items and speed of the disk, this task can take anywhere from milliseconds to many minutes. Once that data is present for A and B, Kaleidoscope can show you a first estimate of the difference. If an item only exists in A or B, the decision is easy. If an item exists in both A and B, but its size is different, there definitely is a difference between A and B for that item. Easy once again. If the size is equal, but the modification date is different, Kaleidoscope assumes for a moment that the item is different, until it finds out the whole truth. Unfortunately, for typical folder comparisons (most users tend to compare a lot of equal stuff, why compare otherwise?) this happens to be the common case.
 This is the reason sometimes items are listed as different while processing is still ongoing, but end up as being equal. For the final result, true to its nature as a diff tool, Kaleidoscope only considers the content of two items to judge if these items are different. In other words, two items are marked equal, even if their modification date is different, as long as the contents are equal.
  3. In the third and final step, Kaleidoscope compares each single item, byte-by-byte. It does that through a hashing process. Again, the duration of that step varies a lot. For small files stored on a SSD it’s almost unnoticeable, but for massive media files on a spinning disk, it can take a very long time. 
Also note that there is a user setting to define a file limit, beyond which Kaleidoscope will assume files of equal byte size to be equal, skipping the full byte-by-byte check. This is because it’s almost impossible to create huge media files (sound files, large photos, movies) that have the same byte size but different content.

In reality, all of the above happens interleaved and in parallel, depending on your machine. In typical cases, with a few thousand small files on an internal SSD, you hardly notice any delay. But when comparing two copies of a large photo library located on spinning disks, you may have to wait for several hours for the final result.


This major overhaul of the folder comparison feature makes Kaleidoscope more powerful, faster, and hopefully more fun to use. Let us know how you like the latest additions and what features you are missing. In a future post, we’ll also talk about improvements in combination with git difftool -d. Feel free to try it out until then.