# The Org-roam v2 Great Migration **URL:** \ **Category:** Development\ **Created:** [April 25, 2021, 2:40am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505 "2021-04-25T02:40:11Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![jethro](https://avatars.discourse-cdn.com/v4/letter/j/b5a626/32.png) [@jethro](https://org-roam.discourse.group/u/jethro)\ **Post date:** [April 25, 2021, 2:40am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/1 "2021-04-25T02:40:11Z")
I’ve been personally using and developing Org-roam v2 for a few months now (along with some others), and I think it’s finally stable and usable enough for public testing. I’ve released a tag on GitHub that marks this milestone: > **[Release Org-roam v2.0.0a1 · org-roam/org-roam](https://github.com/org-roam/org-roam/releases/tag/2.0.0a1)** > > Org-roam v2.0.0a1 > This is the first alpha release of Org-roam v2. > Why should you migrate to v2? > > only v2 is in active development > the v2 codebase is greatly simplified and should provide a much smo... This thread is for handling any problems/queries wrt to upgrading to v2. ## Why should you migrate to v2? - only v2 is in active development - the v2 codebase is greatly simplified and should provide a much smoother experience - Experience the upgraded Org-roam buffer Sample configuration: ```auto (use-package org-roam :custom (org-roam-directory "/path/to/org-files/") :bind (("C-c n l" . org-roam-buffer-toggle) ("C-c n f" . org-roam-node-find)) :config (org-roam-setup)) ``` Read more about Org-roam v2 [here](https://org-roam.discourse.group/t/org-roam-major-redesign/1198) ## How do I migrate to v2? You should be able to (for the most part) convert your v1 files to the v2 format as follows: > `roam:` links, and `roam_tags` are not automatically converted. ## Should you hold off on the migration? Stick to Org-roam v1 if: - You dislike using ID links - You rely on external packages like `org-roam-server` and `org-roam-bibtex` - You rely on org-roam graphing ---
**Author:** ![spicy](https://avatars.discourse-cdn.com/v4/letter/s/2acd7d/32.png) [@spicy](https://org-roam.discourse.group/u/spicy)\ **Post date:** [April 25, 2021, 8:34am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/2 "2021-04-25T08:34:57Z")
That’s awesome, that migration script is very useful I still have some nores hanging around in v1 format. Thanks @jethro! I’m going to try this now ---
**Author:** ![alanz](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/alanz/32/717_2.png) [@alanz](https://org-roam.discourse.group/u/alanz)\ **Post date:** [April 25, 2021, 8:56am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/3 "2021-04-25T08:56:19Z")
Maybe the migration script should be included in the org-roam source for v2, and exposed as a command? ---
**Author:** ![hieuphay](https://avatars.discourse-cdn.com/v4/letter/h/90ced4/32.png) [@hieuphay](https://org-roam.discourse.group/u/hieuphay)\ **Post date:** [April 25, 2021, 11:01am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/4 "2021-04-25T11:01:02Z")
> [@jethro](#): > > You should be able to (for the most part) convert your v1 files to the v2 format as follows: There seems to be unmatched parenthesis error in this migration script. ---
**Author:** ![bruce](https://avatars.discourse-cdn.com/v4/letter/b/ccd318/32.png) [@bruce](https://org-roam.discourse.group/u/bruce)\ **Post date:** [April 25, 2021, 1:27pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/5 "2021-04-25T13:27:53Z")
You might want to explicitly say that 2 is currently on the branch, and when you plan to merge to master? ---
**Author:** ![public\_image\_limited](https://avatars.discourse-cdn.com/v4/letter/p/5e9695/32.png) [@public\_image\_limited](https://org-roam.discourse.group/u/public_image_limited)\ **Post date:** [April 25, 2021, 2:34pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/6 "2021-04-25T14:34:29Z")
Great work!! Conversion went relatively smoothly, yet there are some questions. Don’t know where’s the place to ask, so here they are: - Org Roam files now can have filetags attached. They seem no to be inherited, however. Are there any plans to allow tag inheritance à la org mode? - What is the conceptual difference between filetags (or tags at headings) and ROAM\_TAGS? In v1, I used the ladder as a type category (“Thought”, “Reference”, “Quotation”, “Overview”, etc.). Is it recommended to use filetags for that now? They show up in the node completion, ROAM\_TAGS don’t. - I added an ID to every heading and have more than 3.000 nodes now. It would make sense, for me, to display the nodes in an hierarchical manner (“Title/Heading/Subheading”) when "find"ing a node. Is anything like that planned? - How is “org-setup” supposed to be used? I do not understand why it is not a global major mode, since that’s all it does. I put it in the `:config` part of my `use-package` declaration, but it feels wrong. ---
**Author:** ![hieuphay](https://avatars.discourse-cdn.com/v4/letter/h/90ced4/32.png) [@hieuphay](https://org-roam.discourse.group/u/hieuphay)\ **Post date:** [April 25, 2021, 3:57pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/7 "2021-04-25T15:57:41Z")
I’ve been eyeing on `v2` for a while and tried it out today. I reverted to `v1` shortly after. Here’s my thoughts and experience. I think most of them are non-issues, and will soon be fixed going forward, but I’m echoing my voice anyway. Before I start, I want to mention that I use Doom Emacs. I have all my notes already version controlled, so I can easily revert changes to my notes, but it is not the same for many others. As such, introducing automated changes to notes should be made with caution. ## Installing For some reason, I could not fetch `v2` by adding `:branch v2` into my `package!` recipe, even when I copied the recipe from the wiki guide. I ended up going to my local `straight.el` clone and switch the branch to the alpha release. I’m guessing this is not Org-roam problems. Moving on. ## Migrating notes - Firstly I found the downloaded migrate script have some syntax error, as I pointed out in a reply above. A trivial fix is enough to make the script functional Step 1: - As the script runs, it opened the buffer for every single notes. So I have to wait for inline Latex previews to render. - The script made error and halt for my old notes, because the `#+latex_header: \addbibresource{...}` parts in those notes was wrong and I had to fix this. I don’t know why the script cares about bib sources. Maybe it tried to re-render math previews in those files, but the LaTeX previews did not re-render when I manually visited those files – the preview images were already cached. Step 2: - Lots of duplicate ID errors popped up and I don’t know why, but they did not halt the script, so I let it happened - After this step, I tried restarting Emacs, but it asked me to confirm changes to _all_ 664 of my notes. A quick check via `magit` shown that all notes have been created with IDs, so I kill emacs without saving all visited files. - I restarted Emacs. The duplicate errors popped up again. And I ran step 3. I also change all `#+roam_tags` to `#+filetags`, using `rg` and `ivy-occur`, and I restarted again. ## Using `v2` - `org-roam-find-node` successfully found my nodes. However, none of them showed any backlinks. A project-wise `rg` search returned almost zero `file:` links in my notes folder; that should mean that links are successfully converted. So why no backlinks are displayed? - Calling the template for `org-dailies` returned an error. I guess the dailies functionality has not been made into `v2` yet? After playing around with `v2` a little, I decided to revert back to `v1`. Backlinks and capturing didn’t work for me, so I think I should wait a little more until `v2` rounds its edges. ---
**Author:** ![jethro](https://avatars.discourse-cdn.com/v4/letter/j/b5a626/32.png) [@jethro](https://org-roam.discourse.group/u/jethro)\ **Post date:** [April 25, 2021, 4:36pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/8 "2021-04-25T16:36:51Z")
> [@alanz](#): > > Maybe the migration script should be included in the org-roam source for v2, and exposed as a command? Hmm, I think it’s fine left outside as a separate standalone script, I’ve added execution instructions to the script for those less adept with Emacs Lisp. > [@bruce](#): > > You might want to explicitly say that 2 is currently on the branch, and when you plan to merge to master? Yeah I’ve left out how to actually switch branches… Will add to the original post. I don’t know when I plan to merge to master yet, I guess when more people are onboard and there are fewer bug reports. ---
**Author:** ![jethro](https://avatars.discourse-cdn.com/v4/letter/j/b5a626/32.png) [@jethro](https://org-roam.discourse.group/u/jethro)\ **Post date:** [April 25, 2021, 4:40pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/9 "2021-04-25T16:40:56Z")
> [@public\_image\_limited](#): > > Org Roam files now can have filetags attached. They seem no to be inherited, however. Are there any plans to allow tag inheritance à la org mode? Tag inheritance should work now: I have nodes that inherit the file node’s `#+filetags`. If they don’t for you, do share: - your Org-roam config - your Org files - the commit version on v2 > [@public\_image\_limited](#): > > What is the conceptual difference between filetags (or tags at headings) and ROAM\_TAGS? In v1, I used the ladder as a type category (“Thought”, “Reference”, “Quotation”, “Overview”, etc.). Is it recommended to use filetags for that now? They show up in the node completion, ROAM\_TAGS don’t. There is no more `ROAM_TAGS`, there’s only one tag source now, and that is how Org computes it. > [@public\_image\_limited](#): > > I added an ID to every heading and have more than 3.000 nodes now. It would make sense, for me, to display the nodes in an hierarchical manner (“Title/Heading/Subheading”) when "find"ing a node. Is anything like that planned? I think you should be more selective towards what you add IDs to, but I am considering storing the outline path in the DB and allowing for its use in the completions. > [@public\_image\_limited](#): > > How is “org-setup” supposed to be used? I do not understand why it is not a global major mode, since that’s all it does. I put it in the `:config` part of my `use-package` declaration, but it feels wrong. Putting it in `:config` is correct, just think of it as a one-time executable thing that sets up Org-roam. `org-roam-teardown` removes what `org-roam-setup` sets up. ---
**Author:** ![alanz](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/alanz/32/717_2.png) [@alanz](https://org-roam.discourse.group/u/alanz)\ **Post date:** [April 25, 2021, 5:00pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/10 "2021-04-25T17:00:59Z")
Perhaps it would be better to call it `org-roam-startup`. When I see the word `setup` I think about configuring it to work, and expect that to be a one-time thing, or when something changes. ---
**Author:** ![nobiot](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/nobiot/32/159_2.png) [@nobiot](https://org-roam.discourse.group/u/nobiot)\ **Post date:** [April 25, 2021, 6:54pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/11 "2021-04-25T18:54:46Z")
> [@jethro](#): > > Yeah I’ve left out how to actually switch branches… Will add to the original post. Let me suggest to simply add a link to the [wiki](https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2) – it mentions V2 branch with a direct link. Even a bit of how-to for Doom users (albeit a report of it not working; I guess someone can look at it). I have kept the wiki fairly up-to-date, including the recent change over to a user option for sections. If any part of the content is obsolete, simply update it. Or if there are too many inconsistencies to update, then I’d suggest that we declare that it has served its intended bridging purposes and archive it (remove it) to avoid further confusion. ---
**Author:** ![public\_image\_limited](https://avatars.discourse-cdn.com/v4/letter/p/5e9695/32.png) [@public\_image\_limited](https://org-roam.discourse.group/u/public_image_limited)\ **Post date:** [April 26, 2021, 9:56am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/12 "2021-04-26T09:56:55Z")
Still, it should be wrapped in a global minor mode, because that’s exactly what they are for. I’ll do PR if I find some time; but here’s a starter: ``` (define-minor-mode org-roam-active-mode "Set up hooks for org roam." :global t (if org-roam-active-mode (org-roam-setup) (org-roam-teardown))) (org-roam-active-mode +1) ``` ---
**Author:** ![public\_image\_limited](https://avatars.discourse-cdn.com/v4/letter/p/5e9695/32.png) [@public\_image\_limited](https://org-roam.discourse.group/u/public_image_limited)\ **Post date:** [April 26, 2021, 10:00am UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/13 "2021-04-26T10:00:21Z")
Thanks for the detailed responses! As to the ID stuff, I think the point is rather that IDs should not be necessary to FIND a node, that’s all. So adding an outline path to the DB is great; even greater would be to allow to access all headings, independently if they have an ID or not. This would reduce the need to create many IDs, because they would then be only used for links. But to find links, it is very useful to access all headings, not just those already linked. I remember reading somewhere on discourse that one reason against such a system is that there are “general headings” which should not show up as a node. My suggestion is to display only those un-ID’ed headings which do not have a further subheading - this would automatically filter out all those top-level headings which are used for sorting only. The idea is that only those headings with the deepest nesting actually contain information, while the other (“upper” ones) are for internal organization. That’s at least how I organize my reference pages. Re: “inheritance of filetags”: I use commit “38b5375” of the v2 branch, but I have no time to debug it right now. I’ll look into it and file a more detailed issue on github if the issue persists with the latest commit. ---
**Author:** ![jeyj0](https://avatars.discourse-cdn.com/v4/letter/j/b19c9b/32.png) [@jeyj0](https://org-roam.discourse.group/u/jeyj0)\ **Post date:** [April 26, 2021, 1:38pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/15 "2021-04-26T13:38:50Z")
Re “inheritance of filetags”: have you tried using `C-c C-c` on the line containing the `#+filetags`? ---
**Author:** ![public\_image\_limited](https://avatars.discourse-cdn.com/v4/letter/p/5e9695/32.png) [@public\_image\_limited](https://org-roam.discourse.group/u/public_image_limited)\ **Post date:** [April 26, 2021, 2:16pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/16 "2021-04-26T14:16:49Z")
thanks for asking! The behavior is inconsistent. I just had an actual note where tag inheritance did not work. Reading your comment, I created a minimal page to make it reproducible – and alas, here tag inheritance did work. 😑 So time to dig into it some time later… EDIT: I found the problem, it was a missing colon in one file. File tag inheritance is working fine! That’s actually a cool feature, I like it. ---
**Author:** ![jprussell](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/jprussell/32/360_2.png) [@jprussell](https://org-roam.discourse.group/u/jprussell)\ **Post date:** [April 27, 2021, 10:23pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/17 "2021-04-27T22:23:41Z")
I just got migrated, and so far I’m liking it quite a bit. For one thing, emacs startup time is _way_ faster, so that’s great. A few things I’ve run into with migrating: - To get straight.el to build from the v2 branch, I had to rm -rf my existing org-roam repo folder. To do this without throwing an error, you need to remove org-roam from your init, restart emacs, close emacs, _then_ delete the repo, then add the new, updated recipe to your init file. - I received a few hundred errors for non-unique IDs when running the script provided by @jethro linked above. I haven’t checked to see if that has caused any issues or done anything to try to mitigate yet - I’m running into a small, strange apparent bug. If I attempt to call `org-roam-capture` _before_ I have called `org-roam-node-find` after a restart of emacs, I get the error ` (void-variable org-roam-find-file-hook)` (see below for full debugger output). Re-evaluating `org-roam-setup` does not seem to cause the error again, nor does `org-roam-db-sync`. Here’s the full debugger output: ```auto Debugger entered--Lisp error: (void-variable org-roam-find-file-hook) (member #'org-roam-db--update-on-save-h org-roam-find-file-hook) (if (member #'org-roam-db--update-on-save-h org-roam-find-file-hook) org-roam-find-file-hook (setq org-roam-find-file-hook (cons #'org-roam-db--update-on-save-h org-roam-find-file-hook))) eval-buffer(# nil "/Users/Jeff/.emacs.d/straight/build/org-roam/org-roam-db.el" nil t) ; Reading at buffer position 18477 load-with-code-conversion("/Users/Jeff/.emacs.d/straight/build/org-roam/org-roam-db.el" "/Users/Jeff/.emacs.d/straight/build/org-roam/org-roam-db.el" nil t) require(org-roam-db) eval-buffer(# nil "/Users/Jeff/.emacs.d/straight/build/org-roam/org-roam-capture.el" nil t) ; Reading at buffer position 1439 load-with-code-conversion("/Users/Jeff/.emacs.d/straight/build/org-roam/org-roam-capture.el" "/Users/Jeff/.emacs.d/straight/build/org-roam/org-roam-capture.el" nil t) autoload-do-load((autoload "org-roam-capture" "Launches an `org-capture' process for a new or existing note.\nThis uses the templates defined at `org-roam-capture-templates'.\nArguments GOTO and KEYS see `org-capture'.\n\n(fn &optional GOTO KEYS)" t nil) org-roam-capture) command-execute(org-roam-capture) ``` ---
**Author:** ![Gustav](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/gustav/32/511_2.png) [@Gustav](https://org-roam.discourse.group/u/Gustav)\ **Post date:** [April 27, 2021, 10:37pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/18 "2021-04-27T22:37:25Z")
> [@jethro](#): > > I think you should be more selective towards what you add IDs to, but I am considering storing the outline path in the DB and allowing for its use in the completions. Let me just +1 using the outline path for completions. Selective with ID’s or not, the nodes within files have a context, just as files within folders has. Using that hierarchy makes total sense, even if each node is its own entity as well. ---
**Author:** ![nickanderson](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/nickanderson/32/753_2.png) [@nickanderson](https://org-roam.discourse.group/u/nickanderson)\ **Post date:** [April 30, 2021, 6:29pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/19 "2021-04-30T18:29:26Z")
For the spacemacs users, I used this little patch to layers/+emacs/org/packages.el ``` - (org-roam :toggle org-enable-roam-support) + (org-roam :toggle org-enable-roam-support + :location (recipe :fetcher github :repo "org-roam/org-roam" :branch "v2") + ) ``` ---
**Author:** ![jwang](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/jwang/32/540_2.png) [@jwang](https://org-roam.discourse.group/u/jwang)\ **Post date:** [May 2, 2021, 8:06pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/20 "2021-05-02T20:06:25Z")
Just failed to migrate from v1 to v2 by using the mentioned script in this thread. - files are successfully added ID and aliases - but db is not successfully build, because some emacs sql expression error - file links were not converted to IDs - org-roam-node-find can only find my 4 notes (among of hundreds of them) I would give a try next time when the migration script is more stable and I have more time. ---
**Author:** ![gcoladon](https://yyz2.discourse-cdn.com/free1/user_avatar/org-roam.discourse.group/gcoladon/32/976_2.png) [@gcoladon](https://org-roam.discourse.group/u/gcoladon)\ **Post date:** [May 2, 2021, 10:38pm UTC](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505/21 "2021-05-02T22:38:26Z")
> [@jwang](#): > > - but db is not successfully build, because some emacs sql expression error Next time you try, if you can capture the sql error – ideally as text but even as screenshot otherwise – and post it here, it would almost certainly help us/people figure out what went wrong so we can make it more stable more quickly 🙂 [Next page](https://org-roam.discourse.group/t/the-org-roam-v2-great-migration/1505.md?page=2)