Skip to content
  • Florian 
  • 5 min read

Folder vs. File Changes. Why are there differences?

There’s a difference between how Kaleidoscope compares files in the folder comparison and in the direct (text) file comparison. This can cause unexpected results. Here’s a support email we recently received:

Kaleidoscope still flags some files that are identical as having been modified in direct file comparisons. I haven’t been able to determine why it thinks that the files are different. When I open them in Kaleidoscope, Kaleidoscope says there are “No Changes”. And if I compare file permissions, the file permissions between the files are also identical. It doesn’t seem to do this with all files.  It’s just some of them.

Basically, I just take two folders of files with minor differences, drop them both into Kaleidoscope, and most of what Kaleidoscope finds are files with actually differences.  But there are always a few stragglers where Kaleidoscope says there are differences when there aren’t.

Any idea how to fix that?

The short answer in most scenarios is to turn off Ignore Whitespace and Normalize JSON in Settings > Text.

So much for the quick tip. Here’s why, if you’re curious:

How Kaleidoscope compares folders

When comparing files as part of a folder comparison, Kaleidoscope does not actually load and interpret the content of each file, it only compares the raw data on disk. The simple reason is performance. If Kaleidoscope were to read each file into memory, interpret the contents and compare those contents, even smaller folder comparisons would be extremely slow.

The result is that any difference in a pair of files on the data level causes Kaleidoscope to claim that those two files are different.

We recently wrote a more comprehensive article about the Folder Comparison if you want to dig deeper.

What about text files?

For the text comparison, Kaleidoscope focuses on comparing the actual text, it doesn’t really care about the file that carried the text. (The same goes for images.)

There may be differences in a text file that are not relevant when comparing the resulting text. Examples are how the text data in a text file is encoded and which newline characters are being used, just to name a few. Kaleidoscope 4.0 introduced File Properties to make all that file-related information accessible.

Coming back to content and the starting question, by far the most common difference is in whitespace (leading and trailing to be precise) or in the order of JSON content (when comparing JSON files). When Ignore Whitespace and Normalize JSON in Settings > Text are enabled, Kaleidoscope will not compare the text data as it is stored in the file, but instead compare some derivative that honors these settings.

For the performance reasons explained above, the folder comparison does not implement those settings (which is why they are located in Settings > Text instead of Settings > General). As a result, a pair of files can have different comparison results, depending on how you look at those results: in the folder of the file comparison.

If there are differences in whitespace like one file using tabs to indent, the other one using spaces, the resulting text may be equal if you ignore those whitespace changes. The same is the case if elements in a JSON file have been reshuffled while the normalized version of those JSON files is still (semantically) equal.

Other scenarios

In some cases, there are differences not covered above and the text comparison still shows no differences. Now you should take a look at the File Properties. Most of the time, the size of the files will be different. There are a number of properties that can cause that:

  • Encoding. This has by far the largest impact on file size. We can’t go into full details here, but “normal” files on macOS are encoded in UTF-8, meaning each single character in the text takes 8 bits (= 1 byte) of disk space. But there’s also UTF-16 and UTF-32, taking twice or even four times that space, per character. And these are just 3 popular encodings, there are many more.
  • Line Endings. Historically, computing platforms used different ways to encode when one line of text ends and a new one begins. Most types of endings take one character (in the encoding above), but some also need two characters.
  • BOM (Byte Order Mark). Now we are getting deep. In cases where one character is encoded in more than one byte, there’s also the question to answer how those multiple bytes need to be ordered to make up the character. This is encoded in the BOM at the beginning of a text file. The fun part is that some apps on some platforms also add a BOM in the beginning of files that don’t even need it, such as UTF-8. Since Kaleidoscope 5.1.1, the File Properties show the existence of a BOM in UTF-8. Once again, the resulting text is the same, whether the file had a BOM or not.

As you see, text files (the data representation of text on a disk) are a lot more complex than what one may natively assume. And we only barely scratched the surface. Luckily, modern computer operating system take away the burden of dealing with these details.

But when it comes to comparing text files and their content, you may suddenly find yourself looking for differences that are hard to explain. We hope that this article can help shed some light on the more obscure aspects. But still, start with Ignore Whitespace and Normalize JSON, as they are the likely “culprits”.