Kaleidoscope 5.1 comes with a URL scheme, yet another new way to integrate with other apps on your Mac. Why would someone need that? Glad you asked!
Some apps are unable to use any of the other methods we already provide, like our system services, the share extension, Shortcuts, a command-line command, custom integrations, … But more importantly, it may just be most convenient to provide everything needed to compare multiple files in one single “command” in the form of a URL. Many apps on macOS detect URLs and make them interactive links. A single click is enough to open a URL, and that click will then open a comparison in Kaleidoscope.
There’s a very specific use case we had in mind when adding this feature: running tests within Xcode, in particular snapshot testing using swift-snapshot-testing. Let’s start with the benefit: here’s a default error message you would get for a failed test comparing a previous snapshot of a screen with the current test run:
Note the folks of swift-snapshot-testing even suggest to use ksdiff as a diffTool instead. Then this is what you get in Xcode:
Now we can select that ksdiff command inside the error bubble:
And paste the command into a Terminal window to open the comparison in Kaleidoscope:
This is already a huge improvement, compared to seeing only two file:// urls in the Xcode error, which we then could open manually in Kaleidoscope. But now we can do even better…
New in Kaleidoscope 5.1
Using the new Kaleidoscope 5.1 and a little diffTool configuration for SnapshortTesting, you instead get a clickable link within Xcode:
One single click and you immediately see what went wrong in the test:
This is all code that was required in our test file to define Kaleidoscope as a new diffTool, using the URL scheme:
The URL scheme
Now that we have seen a use case, let’s look at what the URL scheme hast to offer. The basic form of a URL recognized by Kaleidoscope is very simple:
kaleidoscope://<command>?<arguments>
Commands
compare | diff | The compare and diff commands are interchangeable and open the files specified in parameters in a comparison. |
clipboard | pasteboard | Add the contents of the macOS clipboard to a comparison. Use the label parameter to specify a destination document. |
history | The history command requires a single file in parameters. In case the file specified is inside a git working directory, Kaleidoscope will open the Git File History for that file. |
changeset | This command will try to open the changeset for the git commit identifier provided in arguments. |
Arguments
Arguments supply the content to be used with a command and control overall behavior. Parameters are separated by the & character.
label | The label parameter is a key=value parameter in the form label=<string>. When supplied, the value of <string> will be used as title of the document. This is useful for repeatedly sending content to the same document as before. |
files | File paths can be provided in one of two formats: – As pure file path. Paths can be either absolute or use ~ to reference the user home directory. An absolute path starts with /. – As key/values pair. Here, key will be used to name the file in Kaleidoscope. This is particularly helpful when the file path is not self-explanatory, such as when supplying files generated by a tool that automatically names files. For the path itself, see above. |
commit identifier | Provide a git commit identifier for the changeset command. This can be either full 40-character commit hash or one shortened to 8 characters.Note that the repository containing the commit needs to be in the Repositories list of Kaleidoscope for this to work. |
Note that strings and paths supplied as parameters need to be URL encoded, e.g., if a file path contains a space character, it needs to be encoded as %20 in the parameter.
