Upgrade to org-roam v2 with use-package and quelpa

org-roam has become a core part of my personal knowledge management system (and I should probably also update that 2019 post to reflect this).

Behind the scenes, Jethro Kuan (creator and maintainer of org-roam) and collaborators have been hard at work on v2.

The most important functional difference is that any org heading (section) can now also function as a “node”, or zettel, just like a standalone org-file.

Jethro Kuan was planning to release the v2 rewrite by the end of June, so this might soon become the default.

I’ve been using v2 for a week or two now, and the unification mentioned above has brought improvements in utility, as well as many sparks of joy.

In this post, I show how I used quelpa with my existing use-package setup in order to be able to install and update the latest v2 org-roam straight from its branch on github.

You can do the same in five easy steps.

Backup your org-roam files

You’re going to run a script that will transmogrify all of the org-files in your org-roam-directory, so make a backup before you start.

Really. Do it.

Now.

Ok?

Configure quelpa and the quelpa-usepackage integration

Add the following code to your init.el, close to the start. In my case, it’s right after I extend my package-archives list with the melpa and org repos.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


;; bootstrap quelpa
;; https://github.com/quelpa/quelpa
(unless (package-installed-p 'quelpa)
  (with-temp-buffer
    (url-insert-file-contents "https://raw.githubusercontent.com/quelpa/quelpa/master/quelpa.el")
    (eval-buffer)
    (quelpa-self-upgrade)))

;; then bootstrap quelpa-use-package which will pull in use-package
;; https://github.com/quelpa/quelpa-use-package
(quelpa
 '(quelpa-use-package
   :fetcher git
   :url "https://github.com/quelpa/quelpa-use-package.git"))
(require 'quelpa-use-package)

;; make sure that use-package :ensure uses quelpa
(setq use-package-ensure-function 'quelpa)

;; commenting out use-package bootstrap, because quelpa-use-package above will do it
;; (unless (package-installed-p 'use-package)
;;   (package-refresh-contents)
;;   (package-install 'use-package))

Update your org-roam use-package sexp

Change your org-roam use-package to look like the code below. Note that this is different to your v1 in two ways: The quelpa invocation, and the org-roam configuration, especially the org-roam-setup call.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


(use-package org-roam
  :after org
  ;; upgrade t required, else it will refuse to update your existing org-roam
  :quelpa ((org-roam :fetcher github :repo "org-roam/org-roam" :branch "v2") :upgrade t)
  ;; in this specific case, we DO NOT use ensure, as we have an explicit quelpa
  ;; :ensure t
  :custom
  (org-roam-directory "/where/your/org-roam-org-files/live/")
  :bind
  ("C-c n l" . org-roam-buffer-toggle)
  ("C-c n f" . org-roam-node-find)
  (:map org-mode-map
        (("C-c n i" . org-roam-node-insert)))
  :config
  (setq org-roam-capture-templates '(("d" "default" plain "%?"
                                      :if-new (file+head "${slug}.org"
                                                         "#+TITLE: ${title}\n#+DATE: %T\n")
                                      :unnarrowed t)))
  ;; this sets up various file handling hooks so your DB remains up to date
  (org-roam-setup))

It would probably be safest to restart your Emacs at this point so it does the quelpa setup, and then installs org-roam v2 from github.

Convert all of your org-roam files

Copy the v2 migration script (in emacs-lisp of course) from this forum post by Jethro Kuan into an empty buffer, and then do M-x evaluate-buffer.

I did eval (org-roam--list-all-files) BEFORE I did that just to double-check that it showed me the org-files I expected.

Enjoy!

Step 5 is the nicest.