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