Command Line Tool

Kaleidoscope comes with a command-line tool, called ksdiff, which you can use to open files from the command-line or from a script.

Installation

Before you can use ksdiff, you need to install it from the Integration window. To install ksdiff:

Choose Kaleidoscope > Integration… from the main menu
Go to the "Command Line Tool" section
Follow the instructions

Starting a Comparison with ksdiff

Examples:

ksdiff file1 file2 file3
ksdiff ~/Desktop/*.jpg
ksdiff folderA/ folderB/

If you give ksdiff a set of paths as arguments, it will launch Kaleidoscope if it isn't open yet, and then create a new tab with those documents. If you supply more than 2 files as arguments, Kaleidoscope will open the File Shelf and display all the files.

Waiting Before Exiting

ksdiff -w file1 file2\

If you use ksdiff in a script, it might be preferable to have ksdiff open until the comparison it started closes again. This way you can remove temporary files you created after the comparison is done, or do some other action after you're sure the user has seen the comparison. This can be done with the -w or --wait command line switch.

To learn more about the ksdiff command line tool, run ksdiff --help to get an overview of its options:

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]