Pipe content into ksdiff using -. This command will compare an original LoremIpsum.txt file with one where all u characters have been replaced with v.
cat LoremIpsum.txt | sed "s/u/v/g" | ksdiff LoremIpsum.txt -
Process Substitution can help comparing the output of multiple other calls. The following sample will compare the output of sorting file1 with the output of sorting file2, without the need to store the sorted files somewhere.
ksdiff <(sort file1) <(sort file2)
Repeatedly send content into the same Kaleidoscope window using the -l option (and piping). The following command will show processes that consume at least 1% of CPU. Use multiple times to compare over time.
Services is one of the most underrated features of macOS. It provides a unified way to send content from one app to another.
The services provided by Kaleidoscope allow sending anything that can be made into text, images or files to Kaleidoscope for comparing.
Installation
Kaleidoscope provides its services automatically to the system, so there is no need to install anything.
Configure in System Preferences
To enable/disable and configure services to your needs, open System Preferences.
1
Open System Preferences. Select Keyboard.
2
Switch to the Shortcuts tab, then select Services from the list on the left.
3
The list on the right side shows all services available on your Mac, grouped by categories. You'll find the following services offered by Kaleidoscope:
Pictures: Compare Images in Kaleidoscope
Files and Folders: Open in Kaleidoscope
Text: Compare Text in Kaleidoscope
Each row allows you to enable/disable that service on the whole system using the checkbox on the left, and to set a keyboard shortcut by pressing the Add Shortcut button.
Service Functionality
All apps supporting services have a menu called Services in the application menu.
For example, select two text or image files in Finder, head to the Finder menu, select Services, and in the submenu find Open in Kaleidoscope inside the Files and Folders category. Kaleidoscope opens and shows the comparison of those two files. Note that there was no need to drag and drop or use the clipboard to copy and paste.
Many apps also include a Services entry in contextual menus, to make services directly accessible from where you work, without the need to travel to the application menu.
Share Extension – Use in Finder and many other apps
Share Extensions are a useful way to export content from one app to another.
Many apps allow sending Text and Image content to Kaleidoscope via a Share menu.
Compare the content of web pages from Safari, text from a Note or different versions of a document from Pages. Or compare different edits of a photo from Photos. The only limit is your creativity.
Installation
Kaleidoscope offers its Share Extension automatically to the system, there's no need to install anything.
Enable in System Preferences
Before using, Share Extensions needs to be enabled in System Preferences.
1
Open System Preferences. Select Extensions.
2
Select Share Menu from the list on the left.
3
In the list on the right side, find Kaleidoscope and ensure the checkbox is turned on.
Share Functionality
Apps have different ways to plug into the Share functionality and share different kinds of content. Anything that will be shared as text, image or file can be compared using Kaleidoscope.
Take a look at Safari as an example: Open any web page in Safari, then click the Share icon in the toolbar and select Kaleidoscope from the menu.
Now you see the whole text of that web page in Kaleidoscope. If you repeat the process for another web page, you can compare the text content of those pages
You can even select just a part of a page to share with Kaleidoscope. This can be very useful when trying to compare paragraphs of articles on different websites or compare text from a Word/Pages document with what was published on a website.
Shortcuts – Automation for macOS
New for macOS Monterey, Kaleidoscope contains actions for Shortcuts.
These actions allow you to fully automate sending text or image files, text, or files as folder comparison to Kaleidoscope as a part of a larger workflow that can be triggered in various ways.
Installation
Kaleidoscope offers its actions automatically to Shortcuts, there's no need to install anything.
!
macOS Big Sur (Version 11.x) does not support Shortcuts. You need to upgrade to macOS Monterey or later.
Compare Quick Action Example
This example of a Finder Quick Action allows comparing files from the contextual menu or by pressing a button.
Follow these steps to get it installed and show its usefulness:
1
Please update to macOS Monterey or later to use this shortcut.Open the shortcut in the Shortcuts app.
2
In the window that appears, click Add Shortcut.
3
Now we need to enable the shortcut as Quick Action:
Open System Preferences
Select Extensions
Select Finder from the list on the left
Enable Kaleidoscope Compare on the right
4
Switch to Finder, select a few files and bring up the contextual menu. Select Quick Actions > Kaleidoscope Compare. Enjoy!
Actions
Currently, Kaleidoscope provides three actions to the Shortcuts app:
Compare Files
This will show the input file(s) passed to the action in Kaleidoscope. Accepts one or more files.
By default, repeated calls will be shown in the same Kaleidoscope window, Use the Open a New Window option to trigger opening a new window. There is also an option to send the content to a specific document by specifying a Document Title. If a document with that title doesn't exist, it will be created.
Note that Open in New Window takes precedence. When checked, a new window will always be created, even if a document with a specified name already exists.
Compare Text
Works exactly like Compare Files, but accepts text as input.
Compare Folders
This compares a list of files in a Folder Comparison. You may optionally specify a Folder Name, to name the folder being compared in Kaleidoscope.
The remaining options Open in New Window and Document Title work the same way as in the actions above.
A use case for this action is to combine it with the Extract Archive action to compare the contents of archives like zip. See the Kaleidoscope Blog for more on that topic, including a sample workflow.
Feedback
Tell us about your needs, so we can improve these actions over time. Use Help > Send Feedback… from the menu to get in touch.
Git Command Line Integration
To integrate Kaleidoscope directly with Git, set up Kaleidoscope as a Git diff and merge tool.
Installation
To make Kaleidoscope your default diff and merge tool, follow these steps:
1
First install the ksdiff command line tool
2
Make Kaleidoscope Git's default diff and merge tool
Usage example:
git difftool
git mergetool
To automatically configure Kaleidoscope as an optional diff and merge tool without making it the default:
1
First install the ksdiff command line tool
2
Make Kaleidoscope one of Git's diff and merge tools
Usage example:
git difftool -y -t Kaleidoscope
git mergetool -y -t Kaleidoscope
git difftool takes the same arguments as git diff, see the man page for more information. To learn how Kaleidoscope's Git integration works, or for instructions on how to manually edit your .gitconfig to add Kaleidoscope integration, see the Git Integration topic in Kaleidoscope Help.
Xcode Debugger Integration
Integrate Kaleidoscope directly with the Xcode command line debugger.
Installation
To make Kaleidoscope available from lldb, follow these steps:
1
First install the ksdiff command line tool
2
Configure to make the ksp and kspo commands available in lldb.Commands are available, the include has been added to ~/.lldbinit
3
When Xcode is already running, either restart the app, or type the following in lldb:
command source ~/.lldbinit
Usage Examples
Call multiple times to compare the register state at various times:
ksp register read
Compare the description of two array objects:
kspo myArray1 kspo myArray2
Compare two view hierarchies by dumping their recursive descriptions:
Make Kaleidoscope default diff and merge toolKaleidoscope is enabled as diff and/or merge tool.
Quit and restart your JetBrains IDE for the automatic configuration to take effect.
These are the preferences settings for manual configuration:
Path to executable (both diff and merge tool):
/usr/local/bin/ksdiff
Parameters (diff tool):
--no-stdin %1 %2 %3
Parameters (merge tool):
--no-stdin --merge --output %4 --base %3 %1 %2
Turn onTrust process exit code
Android Studio IDE integration
1
First install the ksdiff command line tool
2
Make Kaleidoscope default diff and merge toolKaleidoscope is enabled as diff and/or merge tool.
3
Quit and restart Android Studio for the automatic configuration to take effect
These are the preferences settings for manual configuration:
Path to executable (both diff and merge tool):
/usr/local/bin/ksdiff
Parameters (diff tool):
--no-stdin %1 %2 %3
Parameters (merge tool):
--no-stdin --merge --output %4 --base %3 %1 %2
Turn onTrust process exit code
Safari Developer Tools
Kaleidoscope Developer Tools (Dev Tools) for Safari is a Safari extension to help you develop web pages and web apps. The extension needs to be enabled in Safari.
Installation
Kaleidoscope makes the Extension available automatically in Safari, so there is not need to install anything.
Enable in Safari
1
Open Safari
2
From the menu, select Safari > Preferences…, then select Extensions in the toolbar.
3
In the list of extensions, find Kaleidoscope Dev Tool and turn on its checkbox.
4
Confirm by clicking Turn On in the alert that immediately follows.
Configure Toolbar Button
If you turn on Kaleidoscope Dev Tools, its toolbar button will automatically be added to the Safari toolbar. Customize the toolbar in Safari to suit your needs.
Usage
Kaleidoscope Dev Tools offers 4 distinct pieces of functionality:
ksdiff Page Source
Triggered through the Kaleidoscope toolbar button in Safari, this action will send the whole source of the currently displayed page to Kaleidoscope. After making changes, reload the page and trigger again to see the comparison. This is useful when developing sites or apps and the results of your edits in HTML or JavaScript are not entirely trivial.
ksdiff Element HTML
Accessed via the context menu on a page selection, this action will send the enclosing HTML tag to Kaleidoscope. Again, use multiple times to compare elements.
ksdiff Element CSS
Similar to the above, this will send all style information of the current selection to Kaleidoscope.
ksdiff JavaScript function
A ksdiff function is added to the Console of the Web Inspector. Pass any text into it to send to Kaleidoscope. This allows inspecting and comparing of complex JavaScript objects or other elements.
Note
Some security related web sites (i.e. banking) may refuse to work with the Kaleidoscope Developer Tools extension enabled. As Safari does not offer a way to blacklist extensions from certain websites, so you need to manually disable the extension from Safari > Preferences > Extensions when visiting such a site.
VSCode Editor & Git Integration
Kaleidoscope for Visual Studio Code (VSCode) helps you work with changes and merges inside the VSCode app.
It offers various functionalities, available through a toolbar button and several action and contextual menus:
Installation
Kaleidoscope for VSCode needs to be installed via the Visual Studio Code Marketplace by Microsoft. The Marketplace can be accessed from within VSCode.
1
First install the ksdiff command line tool
2
To use Kaleidoscope with Git from within VSCode, make Kaleidoscope one of Git's diff and merge tools
3
Ensure Visual Studio Code is installed on your Mac
4
Open the Extension Page on the Marketplace
5
Click the Install button on that page and follow further instructions
Settings
No configuration is necessary to use the extension. Check out the available settings in VSCode via the menu Code > Preferences > Settings…. Inside Settings, disclose the Extensions entry, then select Kaleidoscope from the list.
Usage
Open with Kaleidoscope
This allows sending entire files to Kaleidoscope for comparison. Use multiple times to compare.
Compare with Kaleidoscope
Send selected text in any editor to Kaleidoscope. Use multiple times to compare.
Show Changes (Kaleidoscope)
Available from various places in the Source Control area, this will open Kaleidoscope via git difftool, showing source control changes in all selected files in one changeset window.
Start Merge (Kaleidoscope)
Available from the Source Control area in case of a conflict, this will open Kaleidoscope via git mergetool for a single file, allowing you to use Kaleidoscope for merging of conflicts..
Versions Subversion Client
Kaleidoscope is supported by Versions 1.0.8 and later.
1
Select Kaleidoscope as your comparison tool in Versions' Preferences
Quit and restart Versions if Kaleidoscope doesn't appear right away.
Subversion Command Line Integration
To integrate Kaleidoscope directly with the Subversion command line integration, set it up as your default SVN diff or merge tool, or use it without making it the default. To make Kaleidoscope your default diff or merge tool, follow these steps:
To diff images from SVN, you need to add the --force parameter:
svn diff --force img/icon.png
To use Kaleidoscope with Subversion without making it your default diff tool:
1
Install the ksdiff command line tool
Usage example:
svn diff --diff-cmd=ksdiff /path/to/working_copy
If an svn update command results in merge conflicts, it prompts you as to the action you wish to take. The l (lowercase l, for launch) option will launch Kaleidoscope to complete the merge.
Mercurial Command Line Integration
To integrate Kaleidoscope directly with Mercurial, you'll need the extdiff extension. This extension is included in Mercurial by default, but it will need to be activated.
Use the Diff last 2 Clipboards action to quickly compare the last two pieces of text you copied to the clipboard using the Alfred Clipboard History.
The Diff Files in File Buffer action lets you run a comparison of files you previously added to the Alfred File Buffer.
Installation
To integrate Kaleidoscope directly with Alfred, you need to install our Alfred workflow.
!
Update Available
An improved version of the integration is available. Please update.
To set everything up, follow these instructions:
1
Ensure Alfred is installed and you have a Powerpack License.
2
Configure to make the Workflow available and open it in Alfred.To remove, locate Kaleidoscope Alfred Integration in the Workflows list, select it, and click the minus (-) button on the bottom.Update the Integration.
Settings
Two hotkeys for immediate actions that can be defined. To set them, open the workflow in Alfred Preferences > Workflows > Kaleidoscope Integration.
File Buffer: Triggering that hotkey will immediately send the Alfred File Buffer contents to Kaleidoscope for comparison.
Finder Selection: This hotkey will send the currently selected files in Finder to Kaleidoscope for comparison.
Usage
Compare the last two entries in the Alfred Clipboard History:
Bring up the Alfred search window
Type ksclip
Compare any number of files (of the same kind), using the Alfred File Buffer:
The Diff Unsaved Changes in Kaleidoscope script helps you to compare changes you made to a file in BBEdit, before saving it.
The Compare Text in Kaleidoscope service allows to compare any text selections using Kaleidoscope.
Installation
To integrate Kaleidoscope directly with BBEdit, follow these instructions:
!
Update Available
An improved version of the integration is available. Please update.
1
First install the ksdiff command line tool
2
Ensure BBEdit is installed and has run before.
3
Configure to make the script available in BBEdit.This will remove the script from BBEdit.Update the script to the latest version.
Usage
Compare the last saved version of a file with the current editor state:
Open a file in BBEdit
Make some changes to the document, without saving.
Select Diff Unsaved Changes in Kaleidoscope from the script () menu.
Services Support
Being a good Mac app, BBEdit also supports the use of services, text services to be precise. That way, you can send any selected text into Kaleidoscope, either via the context menu or the BBEdit menu.
To compare any two selections of text using Kaleidoscope:
Open a file in BBEdit
Select a first piece of text you want to compare.
Choose Compare Text in Kaleidoscope from the bottom of the context menu. It can either be found in a submenu called Services, or directly in the context menu.
Kaleidoscope will activate and open a document. Go back to BBEdit.
Select a second block of text.
Again, choose Compare Text in Kaleidoscope from the context menu.
Kaleidoscope will activate and show the comparison of those two text blocks.
Note
In case the context menu does not offer Compare Text in Kaleidoscope, head to the Services section to learn how to configure it correctly.
To integrate Kaleidoscope directly with the Perforce Command Line Client, you can use the p4 command line tool. To set up the command line tool, follow these instructions:
To integrate Kaleidoscope directly with Perforce, you can use the P4V GUI application. To set up P4V, follow these instructions:
1
First install the ksdiff command line tool
2
Open P4V
3
Open preferences
4
Select Diff
Set Location to:
/usr/local/bin/ksdiff
Set Arguments to:
%1 %2
5
Select Merge
Set Location to:
/usr/local/bin/ksdiff
Set Arguments to:
--no-stdin --merge --output %r --base %b -- %1 %2
Bazaar Command Line Integration
To integrate Kaleidoscope directly with Bazaar, set it up as your default diff and merge tool, or configure it without making it the default. To use it as an external merge tool, you'll need qbzr and Bazaar 2.4 or later. To make Kaleidoscope your default diff and merge tool, follow these steps:
1
First install the ksdiff command line tool
2
Make Kaleidoscope Bazaar's default diff and merge tool
Usage example:
bzr diff
To set up Kaleidoscope as a diff/merge tool without making it the default:
1
First install the ksdiff command line tool
2
Make Kaleidoscope one of Bazaar's diff/merge tools
Diff usage example:
bzr ksdiff
Merge usage example:
bzr qconflicts
TextMate Subversion Integration
To use Kaleidoscope as TextMate's Subversion diff tool, follow these instructions:
1
First install the ksdiff command line tool
2
Open TextMate and go to TextMate's preferences
3
Go to the “Variables” tab (TextMate 1 users, go to “Advanced” tab, and then to “Shell Variables”)
4
Create a new variable by pressing the plus button
5
Enter the following variable name:
TM_SVN_DIFF_CMD
6
Enter the following value:
/usr/local/bin/ksdiff
Usage example:
Select a changed file in the file shelf. Press ⌃⇧A (control + shift + A) to pop up the Subversion Bundle commands. Select "Diff with Working Copy". Your changes should now be displayed in Kaleidoscope.
TextMate Mercurial Integration
To use Kaleidoscope as TextMate's Mercurial diff tool, follow these instructions:
1
First install the ksdiff command line tool
2
Open TextMate and go to TextMate's preferences
3
Go to the “Variables” tab (TextMate 1 users, go to “Advanced” tab, and then to “Shell Variables”)
4
Create a new variable by pressing the plus button
5
Enter the following variable name:
TM_HG_EXT_DIFF
6
Enter the following value:
/usr/local/bin/ksdiff
7
Create a new variable by pressing the plus button
8
Enter the following variable name:
TM_HG
9
Enter the following value:
/usr/local/bin/hg
Usage example:
Select a changed file in the file shelf. Press ⌃⇧M (control + shift + M) to pop up the Mercurial Bundle commands. Select "Diff with Working Copy". Your changes should now be displayed in Kaleidoscope.