ksdiff
Introduction
ksdiff is a command line tool used to launch Kaleidoscope from the Terminal and other apps. It offers a solution for two common scenarios, comparing input and merging input into and output.
Comparing Files
The following simplest possible command will open file1 and file2 in a new comparison in Kaleidoscope.
ksdiff file1 file2
Merging and Conflicts
ksdiff also allows you to start a merge operation, helping you to resolve potential conflicts between the two inputs. Here's a simple sample call opening file1 and file2, allowing you to merge both into a result outfile. Note that outfile does not need to exist when you call ksdiff, it will be created if needed.
ksdiff --merge --output outputfile file1 file2
Advanced Usage
Enjoy the real power of ksdiff by combining ksdiff with other tools and constructs of your shell:
ksdiff <(pngquant 4 image.png -o -) <(pngquant 256 image.png -o -) image.png
The example above compares a PNG image with two compressed variants of itself using indexed colors. See below in Further Reading to find a blog post going into such use cases.
Help Page
This is what typing ksdiff --help shows on the command line.
usage: ksdiff - send files to Kaleidoscope
--version show version information and exit
-h, --help show this help message and exit
COMMON COMMAND OPTIONS
[-w, --wait | -W, --no-wait] whether to wait for the document to be
closed in Kaleidoscope before exiting
the implied default varies per command
[-l, --label LABEL] use LABEL as the visible label for the
tab in Kaleidoscope, instead of the
default value, which is inferred from
the arguments passed to ksdiff’s parent
process
--no-stdin never read stdin even if we receive an
open pipe - needed for some host apps
e.g. JetBrains products
FILE OPTIONS
[-s, --snapshot | -S, --no-snapshot] whether the file is temporary. this
option will override the heuristics
ksdiff would otherwise use to determine
this state.
COMMANDS
[--diff] send files to open ----------------------------( diff )--
default if no other command given
implies --no-wait
FILE [opt] [...] the files to diff, '-' represents stdin
stdin will be prepended to the file list
if no '-' is provided.
--partial-changeset send part of a changeset ---------( partial-changeset )--
implies --no-wait
[--UUID UUID] use UUID to select which document to
add this changeset item to; follow this
with --mark-changeset-as-closed UUID
to tell Kaleidoscope that no more
changes are expected. if unspecified,
Kaleidoscope will watch the process
calling ksdiff and close the changeset
when it exits.
[--relative-path PATH] use PATH to describe the filename and
location for this changeset item within
its root (e.g. a source repository)
FILE [opts] FILE [opts] the files to diff
--mark-changeset-as-closed UUID marks the partial changeset submitted
under the given UUID as being closed
--changeset send a complete changeset ---------------( changeset )--
implies --no-wait
--filelist begin a file list (changeset item)
[--relative-path PATH] use PATH to describe the filename and
location for this changeset item within
its root (e.g. a source repository)
FILE [opts] FILE [opts] the files to diff
--merge send a merge -------------------------------( merge )--
implies --wait
--output OUTPUT use OUTPUT as the destination path for
this merge. creates OUTPUT if it does
not exist.
[--base BASE] use BASE as the base content for this
merge. can improve the quality of the
default selections for some merges.
FILE [opts] FILE [opts] the files to merge
Further Reading
We recently posted a series of articles on our blog describing both basics and tips & tricks for ksdiff. After reading those articles you should be able to make the most of ksdiff for your workflow. We also posted a very brief tutorial on how to use the command line on macOS.
Questions
Can’t find an answer to your question here? Send us an email and we’ll help you.