Kaleidoscope comes with a hidden gem that drives many integrations with system technologies and software programs: the ksdiff command. We’ll show you how to make the most of Kaleidoscope by harnessing the power of this gem in this two part series.
This first article describes the basic usage of the ksdiff command line tool, and why you should consider using it. (If you are hesitant to use the command line, aka the Terminal, we’ve provided a few short examples to show you how easy it can be used with Kaleidoscope. Check out our Terminal Basics intro.)
In our next article, we’ll cover a few advanced tips and tricks to help you make the most of ksdiff in your workflow.
If you’re not familiar with using Terminal and command line commands, we created a quick intro for the purpose of this series.
Install the Kaleidoscope Command-Line Tool (ksdiff)
To get started, we need to ensure ksdiff is installed. Command line tools are ideally installed in specific locations. But don’t worry—Kaleidoscope takes care of the hard work. From the menu, go to Kaleidoscope > Integration… You’ll be greeted by the section covering ksdiff.
If you haven’t seen the Integration window before, take a look around. Integration with other parts of macOS (such as Services, Shortcuts and Share menus) as well as many other apps makes Kaleidoscope really powerful.
Because ksdiff is required for many integrations to work, such as git, it may already be installed. If not, follow the instructions to install.
There are two typical ways to use ksdiff: to compare text files, images files, or folders, and to merge two text files into one. Attempting to merge those two files may result in conflicts, where it’s unclear which part should end up in the final result.
Comparing Files
To compare two files, simply type
ksdiff file1.txt file2.txtKaleidoscope will open and compare those files.
ksdiff file1.txt file2.txt is equivalent to the more complete call specifying the diff command explicitly: ksdiff --diff file1.txt file2.txt
This works with text files, image files, and folders. Files don‘t even have to be the same format, as long as they are readable by Kaleidoscope.
As another example, you can easily compare the quality of an original file with a heavily compressed version of the same image with this command:
ksdiff original.jpg compressed.jpgNote that each call to ksdiff can have only text, images or folders. You can’t mix and match, so comparing a text file to a folder is not possible.
Photo by Milad Fakurian on Unsplash
Files don’t need to be in the same location. You can specify the full path, the home relative path using ~, or the relative path from the current working directory. And you are not limited to just two files.
Here’s a sample comparing the Info.plist of three different system apps. Note that the command needs to be in one long line in order to work:
ksdiff /System/Library/CoreServices/Finder.app/Contents/Info.plist /System/Applications/Contacts.app/Contents/Info.plist /System/Applications/FaceTime.app/Contents/Info.plist
Merging and Conflicts
Things get more interesting if you have two files with overlapping content that you want to consolidate into a third, clean file. This works by using ksdiff with the --merge command and specifying an output file using the --output <path> argument. The output file does not need to exist before the call. It will be automatically created by Kaleidoscope.
Real-world example: Consolidating text changes
Let’s say you sent a draft of an article written in Markdown to your coworkers Jean and Chris, asking for their feedback. They both made some really useful changes, but you notice that they rewrote the same parts, in different ways. You now have the original article.md, the edited files edit-jean.md and edit-chris.md. The final version needs to to be a single article, not three. Your task is to create the final version by using the best parts of both edits.
Time to dive into Terminal and use ksdiff again.
ksdiff --merge --output final.md edit-jean.md edit-chris.mdThis will create final.md and show both edit-jean.md and edit-chris.md in the columns next to it, so you can choose one of the conflicting parts, or even rewrite certain parts yet again. For this example, make sure you are viewing the results in Block View by selecting the first icon in upper right, so you can see all three documents in columns.
The orange background indicates areas with a conflict, where left and right (jean and chris) are different. The green background shows that “Added Paragraph 7” was added by Chris.
Using the --base option in addition, you can help Kaleidoscope by telling it what your original (base) version was. Most of the time, this will improve the automatic merges, as can be seen in this example:
ksdiff --merge --output final.md --base article.md edit-jean.md edit-chris.mdWhat’s the difference? In the previous example, we only gave Kaleidoscope the two edited versions as input. Therefor it was unable to detect that “Paragraph 1” and “Paragraph 3” actually had a common source in article.md. Given that added information, Kaleidoscope can show the Jean amended “Paragraph 1” and Chris added to “Paragraph 3,” but those changes are actually not in conflict with each other. So they are highlighted in blue to indicate changes. Only “Paragraph 5” remains in conflict, as both Jean and Chris made changes that cannot be merged automatically.
Note: this is exactly what a call to git mergetool or clients like Git Tower do, once set up to use Kaleidoscope.
Help and more
In addition to the above, ksdiff has two very useful options:
ksdiff --version prints out the version of the tool itself. And ksdiff --help shows a help page covering everything you learned so far in this article and many more advanced options, some of them explained in our next post.
We hope this overview helped you get an idea of why using ksdiff may be a good idea, even if you are not yet a command line wizard. If you want to learn more to unleash the real power of integrating your workflow with ksdiff beyond the basics, stay tuned for the next article in this series.
And as usual, if you have questions, want to share your use case, or if you have an idea for a future addition to ksdiff or Kaleidoscope, please don’t hesitate to contact us. We love hearing from our users! And we are here to provide you with the best tool for your needs.
Pingback: Combining the power of Unix and Kaleidoscope – Tips for using ksdiff – Kaleidoscope Blog
Comments are closed.