Editing Text in External Editors

Sometimes you want to change text while looking at a comparison. While Kaleidoscope will gain built-in editing capabilities in a future version, we recognize that dedicated code editors offer a more comprehensive feature set and that you may prefer to work in your familiar editor or IDE.

That's why Kaleidoscope seamlessly integrates with your preferred editor to enable editing in that app, making your workflow as smooth as possible.

Kaleidoscope currently integrates with TextEdit, Xcode, BBEdit, CotEditor, VSCode, Nova, Sublime Text, Cursor, SubEthaEdit and Zed. More details on each of these apps below.

Prerequisites

There are two main prerequisites you need to take care of before using one of the supported editors in Kaleidoscope:

The editor needs to be installed, including its command line tool. See the table in Supported Editors below for specific tool and version requirements.Open Settings > General and select your preferred editor.

Editing

As soon as setup is completed and you are looking at a text comparison with editable files, there are many different ways to jump into your editor. For this example we are using Xcode, but any of the supported editors will work the same way:

• The most obvious affordances are the new edit toolbar buttons in the bottom toolbar. Click the one below A or B to open that file in the editor.

• Right-click (or control-click) any text inside the editor and select Edit in Xcode from the contextual menu.

• From the File menu, select the submenu for item A or B, then choose Edit in Xcode.

• In the Path Bar, click either file name and select Edit in Xcode from the menu.

• Open the File Shelf in case it's not yet open, bring up the menu of an item by either clicking the triangle in the bottom right or right (control) clicking an item, then select Edit in Xcode from the menu.

Once you have made a change, just Save the file in your editor. Kaleidoscope will immediately update the comparison.

Notes

• You can only edit "regular" text files. In particular, temporary files (such as git revisions, clipboard content, …) or content from file types like Microsoft Word documents cannot be edited. All affordances in Kaleidoscope will be disabled.If you want to edit a temporary file, save it to a regular file first. Use the Save As… command built into Kaleidoscope, e.g, from the Path Bar, or the File > Item A/B submenu.

• When you make changes to a file in Kaleidoscope before trying to open it in an editor, Kaleidoscope will prompt you to save or discard those changes. Kaleidoscope does intentionally not auto-save changes.

• If JSON Normalization or any Text Filter is enabled, Kaleidoscope cannot open the editor at a specific location or keep a selection.

Supported Editors

The capabilities of various editors / IDEs vary greatly. Some IDEs will open files automatically in the context of a project, assuming that project is already open. Also, some editors allow to specify the exact location along with the file, even including a selection. In those cases, Kaleidoscope will send the precise location and potential selection to the editor. Others may only be able to jump to a specific line or not offer any location. See the table below for details.

As mentioned above, please ensure that both the editor and its command line tool are installed. Follow instructions provided by the editor's documentation to install the command line tool.