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.

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.