Org-roam V2 has been in the works for over half a year (original Discourse post). It marks a significant technical and conceptual break from V1 of Org-roam. It introduces a new paradigm, while improving on the original intent: “Org-roam is a tool for networked thought. It reproduces some of Roam Research’s key features within Org-mode (Org-roam User Manual).” Examples of the breaking changes include the deprecation of file-based linking in V1, instead opting for Org-ID-based “nodes” in V2.

As of 17 Jul 2021, V2 has been released and merged into master. Both MELPA and MELPA-Stable have picked up changes and built the v2 package. This means that package upgrades via MELPA, or those who do not pin their packages will automatically upgrade to v2.

This means that users of Org-roam, regardless of being on v1 or v2, will have to prepare for the changes brought in by V2.

Org-roam V2 does not recognize file: links. It only recognizes files and headings with ID. Use property drawer and specify ID for relevant files and headings – you can use Org-ID (M-x org-id-get-create) to automatically generate IDs; or alternatively, you can manually type an ID.

org-roam-mode is no longer a global minor mode to activate Org-roam.

WARNING: be sure to remove any invocations of org-roam-mode in your init.el file, otherwise this can cause emacs-daemon to mysteriously hang.

To turn on/off Org-roam, use:

• org-roam-db-autosync-mode (turn on)
• org-roam-db-autosync-disable (turn off)

In v2, there is only one function to use: org-roam-db-sync. It is called within org-roam-db-autosync-mode. org-roam-db-autosync-mode ensures that the database is always in sync with your notes.

There is no more customization option on when the database is updated. V2 is fast and the defaults are sufficient.

To display backlink buffer, use org-roam-buffer or org-roam-buffer-toggle. By default, the backlink buffer gets created in a normal window (not in a side-window like V1).

This org-roam buffer has org-roam-mode turned on, so you can have a mode specific keybindings available via org-roam-mode-map.

To enable the org-roam to refresh based on the current node your point is at, use org-roam-buffer-toggle. You should see the backlink buffer refresh by just moving around in a file across different nodes.

Configuration of the display of the buffer (whether it should be a side-window, and in what width/height) is controlled via the built-in display-buffer-alist. As an example:

;; for org-roam-buffer-toggle
;; Recommendation in the official manual
(add-to-list 'display-buffer-alist
               '("\\*org-roam\\*"
                  (display-buffer-in-direction)
                  (direction . right)
                  (window-width . 0.33)
                  (window-height . fit-window-to-buffer)))

or

;; for org-roam-buffer-toggle
;; Use side-window like V1
;; This can take advantage of slots available with it
(add-to-list 'display-buffer-alist
    '("\\*org-roam\\*"
        (display-buffer-in-side-window)
        (side . right)
        (slot . 0)
        (window-width . 0.25)
        (preserve-size . (t . nil))
        (window-parameters . ((no-other-window . t)
                              (no-delete-other-windows . t)))))

Source: https://orgroam.slack.com/archives/CV160S8EL/p1626626511202600

Navigation in the backlink buffer is intuitive (use RET, C-u RET).

For mouse users, to add back mouse click to visit the node in the backlink buffer:

(define-key org-roam-mode-map [mouse-1] #'org-roam-visit-thing)

If org-roam-visit-thing does not work for you, this below might:

(define-key org-roam-mode-map [mouse-1] #'org-roam-preview-visit)

V2 has overhauled and upgraded the template system. Please refer to the default template for org-roam-capture-templates and its docstring for reference.

Notable differences include introduction of new mandatory element :if-new, and treatment of file and head differ from that of V1, as well as support for entry types, OLP, and datetree.

V2 removes the overloading of “tags” that v1 had. V2 now only recognizes official Org tags.

Org Export supports ID links, but requires some additional setup. First, it is recommended to use org-id-track-globally to track all Org IDs. This allows Org export to figure out the file to link to.

To ensure that anchor links directly to the headline are functional, we need to patch `ox-html` to respect the ID property as the anchor tag. This gist does exactly that.

You don’t have to do anything. When you receive the upgrade, a warning will show (more below).

While not recommended, you can opt to stay on v1 by fetching the content from this repository: https://github.com/org-roam/org-roam-v1

You can find more installation instructions there.

Upon upgrading to v2, you should see a warning as follows:

------------------------------------
WARNING: You're now on Org-roam v2!
------------------------------------

You may have arrived here from a general package upgrade. v2 of
Org-roam is incompatible with v1, and you may need to migrate the
notes you have already taken. To run through the wizard, run:

  M-x org-roam-migrate-wizard

If you have arrived on v2 via a package upgrade but wish to stay
on v1, v1 is unfortunately not distributed on MELPA. See
org-roam/org-roam-v1 on GitHub on how to install v1.

If you've gone through the migration steps (if necessary), and
know what you're doing set `org-roam-v2-ack' to `t' to disable
this warning. You can do so by adding:

(setq org-roam-v2-ack t)

To your init file.

This means that you have successfully obtained v2 of Org-roam. However, if you had been using v1 before, then your notes may at the moment be incompatible with v2. As the warning states, to migrate your notes to v2, you will need to first configure your org-roam-directory:

(setq org-roam-directory (file-truename "/path/to/org/files"))

and then run M-x org-roam-migrate-wizard.

This migration wizard may take some time, as it processes your notes one by one. Note that it backs up your notes in a folder called org-roam.bak in the directory your org-roam-directory is located. When that is complete, you can check that you have upgraded sucessfully by running M-x org-roam-node-find. You should see your list of notes.

If you get a “selecting deleted buffer” error disable the global-git-gutter+-mode.

If you have never used Org-ID in Emacs, you might get an error with a message: “org-id-add-location: Wrong type argument: hash-table-p, nil”. In this case, call M-x org-id-update-id-locations before the wizard.

Once you have confirmed that everything is working correctly, you can add (setq org-roam-v2-ack t) to your init file.

If you face any issues during migration, please file a report on GitHub with relevant information (backtrace, expected/actual results etc.), or ask for help on Slack or Discourse.

The key concept to understand is that Org-roam v2 now tracks “nodes”. A node is any file or headline with an ID. You can create IDs for your files and headlines by using M-x org-id-get-create.

The core functions we use in Org-roam v2 are the following:

• org-roam-capture
• org-roam-node-find
• org-roam-node-insert
• org-roam-buffer-toggle

It is recommended that you give these interactive commands a try. For more information, please refer to the manual.