I would like to understand the internal architecture and strategy used by org-mode.

how does org-mode avoid re-parsing the document after every change?

For example, let's say I have a 2 meg org-mode file/buffer.

There is a TODO in the middle of the file.

I accidentally put a space in the middle of "TODO", so it becomes "TO DO".

After that insert, org-mode needs to remove that TODO (and possibly its children) from its internal data structures. However, from what I can tell, org wouldn't know what the change was. It would have to reparse the whole buffer and then compare the old tree with the new tree. Any agenda views would also have to update after this single keystroke.

How does org-avoid having to perform such an expensive computation for every key stroke?

  • org-mode updates with font-lock-mode, whereas the *Org Agenda* buffer is created manually each time a user creates a search or regenerates manually via a specific operation ... If are interested, you can grep the source code for the term font-lock and you'll see how the definitions are set out ... The function org-set-font-lock-defaults (which gets called when org-mode is activated) has a lot of stuff that you may find interesting ...
    – lawlist
    Mar 18, 2018 at 4:23
  • The *Org Agenda* buffer uses text-properties (instead of font-lock) for colors and lots of hidden information about each item. The text-properties consist of what what may have existed when the data was gathered from the org-mode buffer, and additional text-properties are added while the data is being gathered following a search; e.g., org-search-view, org-tags-view, org-agenda-list. To see more about the hidden text-properties, place your cursor on a an entry in the org-agenda buffer and type: M-x eval-expression RET (text-properties-at (point)) RET.
    – lawlist
    Mar 18, 2018 at 16:58
  • thanks lawlist, I think I'm gathering that org-mode does not attempt to react to text, only org specific commands. So agenda views have to be refreshed manually. Is that an accurate summary?
    – drudru
    Mar 19, 2018 at 1:31
  • font-lock mode, which is used by org-mode (but not org-agenda-mode), refreshes whatever has changed and initially processes the buffer by hunks. The jit-lock library works in conjunction with font-lock and there are customizations to control when certain things are processed, and there is also a timer function. As to font-lock/jit-lock, Emacs makes decisions every command loop regarding what to do, and there are probably some org-specific triggers. The *Org Agenda* buffer is fairly static/non-changing, except as to mouse-overs.
    – lawlist
    Mar 19, 2018 at 2:05

1 Answer 1


After doing some research, integrating comments from lawlist, and a private email from bzg, I believe I have a clearer picture.

org-mode doesn't try to maintain a consistent parallel structure represented by the text in the buffer. You can insert or delete text anywhere in the buffer.

org-mode assumes that the user will use the org-mode commands to create, update, or archive entries. Also, org-mode Agenda views make a similar assumption.

org-mode presents the illusion of consistency by relying on font-lock's syntax highlighting. If the user makes a mistake, the user will have to make the correction. There are no guard rails.

One minor note, if org-element-use-cache is set to t, Org keeps an internal representation of the element at point -- you can see line 4759 of org-element.el. This probably just makes certain commands perform better.

bzg recommended reading:

p.s. I edited this in spacemacs org-mode

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.