Modifying Emacs link-hint Package Open URL Behavior for Local Repositories
Summary: A blog post that introduces org capture to clock, but is really about how I’m intercepting the opening a URL in a browser by first checking if that file might be in a local repository. And if it is, opening the local file instead.
I use Org-Mode 📖 as my markdown format of choice. One feature that I use as I work through code is capturing to a current clock. (Sidenote: See Clocking Work Time (The Org Manual).) My Custom Org-Mode Capture Function for Annotating Bad Code walks through some of that functionality; however I’ll go over a refined workflow.
Background
As part of my new role, I’m working on a code base that is new to me. It’s also in a language that I’m familiar with but by no means an expert: Javascript. And the framework chosen is Angular. All told a lot of new concepts.
I have a task at work that requires fixing a bug; and it’s confounding as it’s related to mutating state.
In order to orient, I use the capture to clock concept. In my projects file, I created a headline (example given (e.g. 📖) “Working through UI Reset Bug”). Then I start a clock for that headline. And I begin my code exploration.
When I find a bit of code to consider, or that I want to “find again”, I invoke org-capture
(Sidenote:
See Capture (The Org Manual).)
and pick my “Capture to Clock”.
(Sidenote:
My “Capture to Clock” template is defined here.)
This grabs the current selected region and creates a link to the remote repository. I then add some more information about why it’s important and then complete the capture.
Prior to , I would also include a link to the local file. But I removed that. In part because I would often times export that headline as a PDF or Markdown and share with teammates; and they likely didn’t have those files on their machine.
I still wanted to open those code blocks locally in Emacs 📖 over opening the remote document. Which lead me down a bit of exploration.
Link Hint Package
I have for quite some time used the Link Hint package. I love it. I invoke M-x link-hint-open-link and am presented with several overlays of characters. Each overlay is position above a “link” that Emacs
knows how to handle.
(Sidenote:
Which is a lot of things.)
I type the character combination to select the link I want, and it opens the link in the “correct” application. In the case of https, it defaults to using my browser…until .
I added some advice that will intercept handling any Org-Mode link and test if the link’s URI is a Github URL.
If it is, I test if I have that repository on my local machine. And when I do, I jump to the local file.
Below is that code:
(defun jf/link-hint--apply (advised-function func &rest args)
"Hijack opening `org-mode' URLs by attempting to open local file.
The ADVISED-FUNCTION is the original `link-hint--apply'.
The FUNC is the dispatched function for handling the link
type (e.g. `link-hint--open-org-link').
The ARGS are the rest of the ARGS passed to the ADVISED-FUNCTION."
(if (and
(eq 'link-hint--open-org-link func)
(eq :open (caddr args)))
(progn
(if-let* ((url
(car args))
(_match
(string-match
(concat "^https://github.com/"
"\\([^/]+\\)/\\([^/]+\\)" ;; org/repo
"/[^/]+/[^/]+/" ;; blob/sha
"\\([^#]+\\)" ;; path to fil
"\\(#L\\([0-9]+\\)\\)?") ;; line number
url)))
;; Due to my present file structure I have some repositories
;; in ~/git/ and others in ~/git/sub-dir
;;
;; In most every case, the Github org and repo match the
;; remote URL.
(let ((filename-without-org
(format "~/git/%s/%s"
(match-string 2 url)
(match-string 3 url)))
(filename-with-org
(format "~/git/%s/%s/%s"
(match-string 1 url)
(match-string 2 url)
(match-string 3 url)))
(line-number
(match-string 5 url)))
(cond
((f-exists? filename-without-org)
(progn
(find-file filename-without-org)
(when line-number
(goto-char (point-min))
(forward-line
(1- (string-to-number line-number))))))
((f-exists? filename-with-org)
(progn
(find-file filename-with-org)
(when line-number
(goto-char (point-min))
(forward-line
(1- (string-to-number line-number))))))
(t (funcall func args))))
(funcall func args)))
(apply advised-function func args)))
(advice-add 'link-hint--apply
:around #'jf/link-hint--apply)
As always, there’s room for refactor. But this gets the job done.
Conclusion
When exploring a code-base, I’m finding it helpful to annotate my explorations and be able to refer back to those findings.
With this change, I can continue to do that without sharing documents that have extra chatter regarding “local links.”
I used the above process (with local links) to add my working notes to a Github issue. I intended for those notes to be a way-finding tools for other folks who might come along; or for someone who might help guide me in a more fruitful direction.
Post Script
I’ve also used the process of capturing to a clock to create blog posts as well as run-book pages. In fact, for this post I started a clock on the Link Hint Package heading and then used my capture process to grab the code.