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

  [-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
  --no-stdin                            never read stdin even if we receive an
                                        open pipe - needed for some host apps
                                        e.g. JetBrains products
  [-s, --snapshot | -S, --no-snapshot]  whether the file is temporary. this
                                        option will override the heuristics
                                        ksdiff would otherwise use to determine
                                        this state.

 [--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.


Can’t find an answer to your question here? Send us an email and we’ll help you.