From bdf0a3d7dc97abe1e789b9b70e2365c40f270cb0 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Tue, 20 Aug 2024 09:23:08 -0400 Subject: [PATCH 1/2] Add hyperlinks section to manual --- manual/src/SUMMARY.md | 1 + manual/src/git-blame.md | 1 + manual/src/grep.md | 19 +------- manual/src/hyperlinks.md | 44 +++++++++++++++++++ .../using-delta-with-vscode.md | 2 + 5 files changed, 49 insertions(+), 18 deletions(-) create mode 100644 manual/src/hyperlinks.md diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md index 588727ae2..38b621228 100644 --- a/manual/src/SUMMARY.md +++ b/manual/src/SUMMARY.md @@ -10,6 +10,7 @@ - [Usage](./usage.md) - [Choosing colors (styles)](./choosing-colors-styles.md) - [Line numbers](./line-numbers.md) + - [Hyperlinks](./hyperlinks.md) - [Side-by-side view](./side-by-side-view.md) - [Grep](./grep.md) - ["Features": named groups of settings](./features-named-groups-of-settings.md) diff --git a/manual/src/git-blame.md b/manual/src/git-blame.md index 6798fe13f..94d5def36 100644 --- a/manual/src/git-blame.md +++ b/manual/src/git-blame.md @@ -2,5 +2,6 @@ Set delta as the pager for `blame` in the `[pager]` section of your gitconfig: see the [example gitconfig](./get-started.md). If `hyperlinks` is enabled in the `[delta]` section then each blame commit will link to the commit on GitHub/GitLab/Bitbucket/etc. + See [hyperlinks](./hyperlinks.md).
image
diff --git a/manual/src/grep.md b/manual/src/grep.md index a090389c9..9892541de 100644 --- a/manual/src/grep.md +++ b/manual/src/grep.md @@ -14,21 +14,4 @@ rg --json -C 2 handle | delta image -If you enable hyperlinks then grep hits will be formatted as [OSC8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) in terminal emulators that support the feature. If you're using VSCode, IntelliJ, or PyCharm, then use the dedicated URL handlers. I.e. one of the following lines: - -```gitconfig -[delta] - hyperlinks = true - hyperlinks-file-link-format = "vscode://file/{path}:{line}" - # or: hyperlinks-file-link-format = "idea://open?file={path}&line={line}" - # or: hyperlinks-file-link-format = "pycharm://open?file={path}&line={line}" -``` - -For editors that don't have special URL handlers, it is possible to use a tool like to make your OS handle a click on those links by opening your editor at the correct file and line number, e.g. - -```gitconfig -[delta] - hyperlinks = true - hyperlinks-file-link-format = "file-line://{path}:{line}" - # Now configure your OS to handle "file-line" URLs -``` +With `hyperlinks` enabled, the line numbers in the grep output will be clickable links. See [hyperlinks](./hyperlinks.md). diff --git a/manual/src/hyperlinks.md b/manual/src/hyperlinks.md new file mode 100644 index 000000000..c91e3209e --- /dev/null +++ b/manual/src/hyperlinks.md @@ -0,0 +1,44 @@ +# Hyperlinks + +Delta uses [terminal hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) to turn line numbers, file paths, commit hashes, etc into clickable links, as long as your terminal emulator supports the feature. Enable the feature with + +```gitconfig +[delta] + hyperlinks = true +``` + +Commit hashes link to GitHub/GitLab/Bitbucket (use `hyperlinks-commit-link-format` for full control). + +The links on line numbers (in grep output, as well as diffs) are particularly interesting: with a little bit of effort, they can be made to open your editor or IDE at the correct line. +Use `hyperlinks-file-link-format` to construct the correct URL for your system. +For VSCode and JetBrains IDEs this is easy, since they support their own special URL protocols. Here are examples: + +```gitconfig +[delta] + hyperlinks = true + hyperlinks-file-link-format = "vscode://file/{path}:{line}" + # or: hyperlinks-file-link-format = "idea://open?file={path}&line={line}" + # or: hyperlinks-file-link-format = "pycharm://open?file={path}&line={line}" +``` + +Zed also supports its own URL protocol, and probably others. + +If your editor does not have its own URL protocol, then there are still many possibilities, although they may be more work. + +- The easiest is probably to write a toy HTTP server (e.g. in [Python](https://docs.python.org/3/library/http.server.html)) that opens the links in the way that you need. Then your delta config would look something like + ```gitconfig + [delta] + hyperlinks = true + hyperlinks-file-link-format = "http://localhost:8000/open-file?file={path}&line={line}" + # Now write an HTTP server that handles those requests by opening your editor at the file and line + ``` + + +- Another possibility is to register a custom protocol with your OS (like VSCode does) that invokes a script to open the file. [dandavison/open-in-editor](https://github.com/dandavison/open-in-editor) is a project that aimed to do that and may be helpful. However, registering the protocol with your OS can be frustrating, depending on your appetite for such things. If you go this route, your delta configuration would look like + ```gitconfig + [delta] + hyperlinks = true + hyperlinks-file-link-format = "my-file-line-protocol://{path}:{line}" + # Now configure your OS to handle "my-file-line-protocol" URLs! + ``` +- Finally, you can just use traditional `file://` links (making sure your OS is configured to use the correct editor). But then your editor won't open the file at the correct line, which would be missing out on something very useful. \ No newline at end of file diff --git a/manual/src/tips-and-tricks/using-delta-with-vscode.md b/manual/src/tips-and-tricks/using-delta-with-vscode.md index 3deafbbbe..daea0e027 100644 --- a/manual/src/tips-and-tricks/using-delta-with-vscode.md +++ b/manual/src/tips-and-tricks/using-delta-with-vscode.md @@ -11,3 +11,5 @@ To format file links for opening in VSCode from other terminal emulators, use th ``` (To use VSCode Insiders, change that to `vscode-insiders://file/{path}:{line}`). + + See [hyperlinks](./hyperlinks.md). From cc38a15a3c252645b952e73e56414adac2fc54a9 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Tue, 20 Aug 2024 10:21:47 -0400 Subject: [PATCH 2/2] Add example server code to hyperlinks manual page --- manual/src/hyperlinks.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/manual/src/hyperlinks.md b/manual/src/hyperlinks.md index c91e3209e..6b33df6a0 100644 --- a/manual/src/hyperlinks.md +++ b/manual/src/hyperlinks.md @@ -29,10 +29,31 @@ If your editor does not have its own URL protocol, then there are still many pos ```gitconfig [delta] hyperlinks = true - hyperlinks-file-link-format = "http://localhost:8000/open-file?file={path}&line={line}" + hyperlinks-file-link-format = "http://localhost:8000/open-in-editor?path={path}&line={line}" # Now write an HTTP server that handles those requests by opening your editor at the file and line ``` + Here's some Python code that could be used as a starting point: + ```python + from http.server import BaseHTTPRequestHandler, HTTPServer + from subprocess import call + from urllib.parse import parse_qs, urlparse + + class OpenInEditor(BaseHTTPRequestHandler): + def do_GET(self): + if self.path.startswith("/open-in-editor"): + query = parse_qs(urlparse(self.path).query) + [path], [line] = query["path"], query["line"] + # Replace with the right command for your editor + call(["code", "-g", f"{path}:{line}"]) + self.send_response(200) + else: + self.send_response(404) + self.end_headers() + + print("Starting httpd server on port 8000...") + HTTPServer(("", 8000), OpenInEditor).serve_forever() + ``` - Another possibility is to register a custom protocol with your OS (like VSCode does) that invokes a script to open the file. [dandavison/open-in-editor](https://github.com/dandavison/open-in-editor) is a project that aimed to do that and may be helpful. However, registering the protocol with your OS can be frustrating, depending on your appetite for such things. If you go this route, your delta configuration would look like ```gitconfig