src/docs/user/userguide/external_editor.diviner

   1 @title User Guide: Configuring an External Editor
   2 @group userguide
   3
   4 Setting up an external editor to integrate with Diffusion and Differential.
   5
   6 Overview
   7 ========
   8
   9 You can configure a URI handler to allow you to open files referenced in
  10 Differential and Diffusion in your preferred text editor on your local
  11 machine.
  12
  13
  14 Configuring Editors
  15 ===================
  16
  17 To configure an external editor, go to {nav Settings > Application Settings >
  18 External Editor} and set "Editor Link" to a URI pattern (see below). This
  19 will enable an "Open in Editor" link in Differential, and an "Edit" button in
  20 Diffusion.
  21
  22 In general, you'll set this field to something like this, although the
  23 particular pattern to use depends on your editor and environment:
  24
  25 ```lang=uri
  26 editor://open/?file=%f
  27 ```
  28
  29
  30 Mapping Repositories
  31 ====================
  32
  33 When you open a file in an external editor, Phabricator needs to be able to
  34 build a URI which includes the correct absolute path on disk to the local
  35 version of the file, including the repository directory.
  36
  37 If all your repositories are named consistently in a single directory, you
  38 may be able to use the `%n` (repository short name) variable to do this.
  39 For example:
  40
  41 ```lang=uri
  42 editor://open/?file=/Users/alice/repositories/%n/%f
  43 ```
  44
  45 If your repositories aren't named consistently or aren't in a single location,
  46 you can build a local directory of symlinks which map a repositoriy identifier
  47 to the right location on disk:
  48
  49 ```
  50 /Users/alice/editor_links/ $ ls -l
  51 ... search-service/ -> /Users/alice/backend/search/
  52 ... site-templates/ -> /Users/alice/frontend/site/
  53 ```
  54
  55 Then use this directory in your editor URI:
  56
  57 ```lang=uri
  58 editor://open/?file=/Users/alice/editor_links/%n/%f
  59 ```
  60
  61 Instead of `%n` (repository short name), you can also use `%d` (repository ID)
  62 or `%p` (repository PHID). These identifiers are immutable and all repositories
  63 always have both identifiers, but they're less human-readable.
  64
  65
  66 Configuring: TextMate on macOS
  67 ==============================
  68
  69 TextMate installs a `txmt://` handler by default, so it's easy to configure
  70 this feature if you use TextMate.
  71
  72 First, identify the parent directory where your repositories are stored
  73 (for example, `/Users/alice/repositories/`). Then, configure your editor
  74 pattern like this:
  75
  76 ```lang=uri
  77 txmt://open/?url=file:///Users/alice/repositories/%n/%f&line=%l
  78 ```