Today was one of the days I decided to upgrade all my installed Emacs packages via
The upgrade to Org-roam v2 should have not surprised me – it is and has been widely talked about in the community the developer – but it did
¯\_(ツ)_/¯. This meant of course the adjustment of my configuration to meet the requirements of the new version.
Having followed the upfront chatter about the “breaking upgrade” I was afraid to have some work cut out for me. But in hind side I realize that this was not the case at all. Most time spent with the migration is this post really.
I will not discus the changes or the new feature of Org-roam v2. This is just a fairly fast How-To to get a working configuration before diving in deeper. There are some links to resources further down however.
So if I can manage then it should be a breeze for you. The tl;dr version of my changes can be found in this commit. Let us get into some details though.
There are really just 3 steps in my humble opinion that you should take care of. But – for the love of god – backup your Org-roam directory first!
1. Adjust your configuration
Note that the
org-roam.db can be separated from the
org-roam-directory. I however choose to put the db in the same location.
(with-eval-after-load 'org (progn (setq org-roam-v2-ack t) ;; acknowledge upgrade and remove warning at startup (require 'org-roam nil t) (setq org-roam-directory (file-truename "/path/to/org-roam-directory")) (setq org-roam-db-location (concat org-roam-directory "org-roam.db")) (org-roam-setup)))
org-roam-mode. This sets up Org-roam and initializes it at Emacs startup.
In case you are using
use-package like me the following configuration should do the trick.
(use-package org-roam :ensure t :after org :init (setq org-roam-v2-ack t) ;; acknowledge upgrade and remove warning at startup :config (setq org-roam-directory (file-truename "/path/to/org-roam-directory")) (setq org-roam-db-location (concat org-roam-directory "org-roam.db")) (org-roam-setup))
2. Change keybindings to the new functions
I personally truly only use 3 Keybindings for Org-roam. You should of course change the bindings to your liking.
;; insert a link to an org-roam file – `org-roam-insert' in v1: (global-set-key (kbd "C-M-i") 'org-roam-node-insert) ;; open a file in org-roam – `org-roam-find-file' in v1: (global-set-key (kbd "C-M-o") 'org-roam-node-find) ;; open backlinks buffer – `org-roam' in v1: (global-set-key (kbd "C-M-r") 'org-roam-buffer-toggle)
3. Migrate your Org-roam
- Eval your new configuration. I just restart Emacs.
- Run the provided migration wizard
- For good measure sync changes to your DB –
Admittedly I don’t handle very big DBs with Org-roam (max 145 files). I choose to have multiple directories rather than a huge
org-roam-directory. For that your results may vary, but I am fairly convinced that – as mentioned further up – it will not hurt a lot.