From f02024615ad3f033f383aed8b7a1c729025db184 Mon Sep 17 00:00:00 2001 From: epriestley Date: Sat, 18 Apr 2020 16:19:25 -0700 Subject: [PATCH] Add "short name", "id", and "phid" variables for external editor URIs Summary: Ref T13515. External editor URIs currently depend on repositories having callsigns, but callsigns are no longer required. Add some variables to support configuring this feature for repositories that do not have callsigns. Test Plan: Changed settings to use new variables, saw links generate appropriately. Maniphest Tasks: T13515 Differential Revision: https://secure.phabricator.com/D21147 --- .../setting/PhabricatorEditorSetting.php | 4 +- .../user/userguide/external_editor.diviner | 60 +++++++++++++++---- .../editor/PhabricatorEditorURIEngine.php | 31 +++++++--- 3 files changed, 72 insertions(+), 23 deletions(-) diff --git a/src/applications/settings/setting/PhabricatorEditorSetting.php b/src/applications/settings/setting/PhabricatorEditorSetting.php index 6884217a3e..a0f1b43c95 100644 --- a/src/applications/settings/setting/PhabricatorEditorSetting.php +++ b/src/applications/settings/setting/PhabricatorEditorSetting.php @@ -26,7 +26,7 @@ final class PhabricatorEditorSetting "\n\n". "Provide a URI pattern for building external editor URIs in your ". "environment. For example, if you use TextMate on macOS, the pattern ". - "for your machine look like this:". + "for your machine may look something like this:". "\n\n". "```name=\"Example: TextMate on macOS\"\n". "%s\n". @@ -36,7 +36,7 @@ final class PhabricatorEditorSetting "see **[[ %s | %s ]]**.". "\n\n". "See the tables below for a list of supported variables and protocols.", - 'txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l', + 'txmt://open/?url=file:///Users/alincoln/editor_links/%n/%f&line=%l', PhabricatorEnv::getDoclink('User Guide: Configuring an External Editor'), pht('User Guide: Configuring an External Editor')); } diff --git a/src/docs/user/userguide/external_editor.diviner b/src/docs/user/userguide/external_editor.diviner index 07aa9db290..ce39ad6610 100644 --- a/src/docs/user/userguide/external_editor.diviner +++ b/src/docs/user/userguide/external_editor.diviner @@ -6,8 +6,10 @@ Setting up an external editor to integrate with Diffusion and Differential. Overview ======== -You can configure a URI handler to allow you to open files from Differential -and Diffusion in your preferred text editor. +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 =================== @@ -17,28 +19,60 @@ 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: +In general, you'll set this field to something like this, although the +particular pattern to use depends on your editor and environment: ```lang=uri 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: + +```lang=uri +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: + +```lang=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, create a local directory with symlinks for each repository callsign. For -example, if you're developing Phabricator, it might look like this: - - /Users/alincoln/editor_links/ $ ls -l - ... ARC -> /Users/alincoln/workspace/arcanist/ - ... P -> /Users/alincoln/workspace/phabricator/ - ... PHU -> /Users/alincoln/workspace/libphutil/ - -Then set your "Editor Link" to: +First, identify the parent directory where your repositories are stored +(for example, `/Users/alice/repositories/`). Then, configure your editor +pattern like this: ```lang=uri -txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l +txmt://open/?url=file:///Users/alice/repositories/%n/%f&line=%l ``` diff --git a/src/infrastructure/editor/PhabricatorEditorURIEngine.php b/src/infrastructure/editor/PhabricatorEditorURIEngine.php index 6abfa98677..bf0c1d1b4b 100644 --- a/src/infrastructure/editor/PhabricatorEditorURIEngine.php +++ b/src/infrastructure/editor/PhabricatorEditorURIEngine.php @@ -90,14 +90,6 @@ final class PhabricatorEditorURIEngine public static function getVariableDefinitions() { return array( - '%' => array( - 'name' => pht('Literal Percent Symbol'), - 'example' => '%', - ), - 'r' => array( - 'name' => pht('Repository Callsign'), - 'example' => 'XYZ', - ), 'f' => array( 'name' => pht('File Name'), 'example' => pht('path/to/source.c'), @@ -106,6 +98,26 @@ final class PhabricatorEditorURIEngine 'name' => pht('Line Number'), 'example' => '777', ), + 'n' => array( + 'name' => pht('Repository Short Name'), + 'example' => 'arcanist', + ), + 'd' => array( + 'name' => pht('Repository ID'), + 'example' => '42', + ), + 'p' => array( + 'name' => pht('Repository PHID'), + 'example' => 'PHID-REPO-abcdefghijklmnopqrst', + ), + 'r' => array( + 'name' => pht('Repository Callsign'), + 'example' => 'XYZ', + ), + '%' => array( + 'name' => pht('Literal Percent Symbol'), + 'example' => '%', + ), ); } @@ -119,6 +131,9 @@ final class PhabricatorEditorURIEngine $variables = array( 'r' => $this->escapeToken($repository->getCallsign()), + 'n' => $this->escapeToken($repository->getRepositorySlug()), + 'd' => $this->escapeToken($repository->getID()), + 'p' => $this->escapeToken($repository->getPHID()), ); return $this->newTokensWithVariables($tokens, $variables);