User Guide: Configuring an External Editor

Phabricator User Documentation (Application User Guides)

Setting up an external editor to integrate with Diffusion and Differential.

Overview

You can configure a URI handler to allow you to open files referenced in Differential and Diffusion in your preferred text editor on your local machine.

Configuring Editors

To configure an external editor, go to Settings → Application Settings → External Editor and set "Editor Link" to a URI pattern (see below). This will enable an "Open in Editor" link in Differential, and an "Edit" button in Diffusion.

In general, you'll set this field to something like this, although the particular pattern to use depends on your editor and environment:

editor://open/?file=%f

Mapping Repositories

When you open a file in an external editor, Phabricator needs to be able to build a URI which includes the correct absolute path on disk to the local version of the file, including the repository directory.

If all your repositories are named consistently in a single directory, you may be able to use the %n (repository short name) variable to do this. For example:

editor://open/?file=/Users/alice/repositories/%n/%f

If your repositories aren't named consistently or aren't in a single location, you can build a local directory of symlinks which map a repositoriy identifier to the right location on disk:

/Users/alice/editor_links/ $ ls -l
... search-service/ -> /Users/alice/backend/search/
... site-templates/ -> /Users/alice/frontend/site/

Then use this directory in your editor URI:

editor://open/?file=/Users/alice/editor_links/%n/%f

Instead of %n (repository short name), you can also use %d (repository ID) or %p (repository PHID). These identifiers are immutable and all repositories always have both identifiers, but they're less human-readable.

Configuring: TextMate on macOS

TextMate installs a txmt:// handler by default, so it's easy to configure this feature if you use TextMate.

First, identify the parent directory where your repositories are stored (for example, /Users/alice/repositories/). Then, configure your editor pattern like this:

txmt://open/?url=file:///Users/alice/repositories/%n/%f&line=%l