• Treemacs Extension Tutorial
  • Intro
  • Setup Basics
  • Defining Node Types
  • Enabling the Extension
  • Asynchronous Nodes
  • Asynchronous Caching and Updates
  • Variadic Nodes and Non-Treemacs Buffers
  • Monotyped Nodes
  • Setting the Default-Directory
  • About Properties

The following is a step-by-step guide on how to create extensions for treemacs using its treelib api. The example used is a simple view of all existing buffers, except those that are hidden, grouped by their major-mode.

The code in this file is loadable with org-babel-load-file, you can see the results by calling showcase-buffer-groups. (Evaluating the code blocks one by one will not work since lexical scope is required in some cases)

First our basic dependencies:

;; -*- lexical-binding: t -*-

(require 'dash)
(require 'treemacs)
(require 'treemacs-treelib)

Since we are grouping buffers by their major-mode we will need two data sources:

• The list of the major-modes of all current buffers as our entry point
• The list of all buffers for a given major-mode

Both sources are filtered for hidden buffers whose names start with a space.

(defun treemacs-showcase--buffer-major-modes ()
  (->> (buffer-list)
       (--reject (string-prefix-p " " (buffer-name it)))
       (--map (buffer-local-value 'major-mode it))
       (-distinct)))

(defun treemacs-showcase--buffers-by-mode (mode)
  (->> (buffer-list)
       (--filter (eq mode (buffer-local-value 'major-mode it)))
       (--reject (string-prefix-p " " (buffer-name it)))))

We will also define a command to open a buffer using RET: (The ignored argument is the prefix arg; the :buffer text property will be stored by ourselves)

(defun treemacs-showcase-RET-buffer-action (&optional _)
  (let ((buffer (-some-> (treemacs-current-button)
                  (treemacs-button-get :buffer))))
    (when (buffer-live-p buffer)
      (pop-to-buffer buffer))))

And another command to visit buffers via the treemacs-visit-node-*** family of commands:

(defun treemacs-showcase-visit-buffer-action (btn)
  (let ((buffer (treemacs-safe-button-get btn :buffer)))
    (when (buffer-live-p buffer)
      (pop-to-buffer buffer))))

Now comes the interesting part, we will use treemacs’ api to tell it how we want our new trees to look, how they should fetch the information they display, and where to put them.

The entry point for an extension is created with treemacs-define-entry-node-type. A detailed explanation and documentation for every single argument can be found in the eldoc of treemacs-do-define-extension-type, so here we’ll only summarise the most important points:

• :label is the text next to the icon.
• The :key of every extension should be semi-unique - it does not need to be unique all on its own, but the “path” of all the parent nodes’ keys leading to a node must serve as a unique identifier for it, otherwise treemacs will not be able to find the node and operations like updating it will not work. At the end of this example a node identifying a specific buffer will have a path in the form of ('showcase-buffers <major-mode-symbol> <buffer-name>)
• The :children are what gets displayed when you expand a node of this type. Other than being a list there are no rules for the structure or content of the items returned here. The nodes we define just need to be able to extract the information they need from this list (as we’ll see in a bit).
• The argument values or not just static. They can contain arbitrary code that will be executed on every access (though of course it should be kept lean on account of performance). When applicable they will also have implicit access to the individual :children being rendered as we’ll see in the next example.

(treemacs-define-entry-node-type showcase-buffers
  :label (propertize "Buffers" 'face 'font-lock-keyword-face)
  :key 'showcase-buffers
  :open-icon (treemacs-get-icon-value 'list)
  :closed-icon (treemacs-get-icon-value 'list)
  :children (treemacs-showcase--buffer-major-modes)
  :child-type 'showcase-buffer-group)

We have created our entry point whose :children will be our buffers’ major-modes. We set its :child-type to be showcase-buffer-group, and that means that we now must create a node type with just that name.

Simple expandable nodes that are neither entry points nor leaves in our tree can be defined with treemacs-define-expandable-node-type.

Here we can see that the individual item, as returned by the previous nodes definition’s :children (in this case the major mode symbol), is bound as item, so we can use it to extract the information we need. We can save additional information as text properties in our node with :more-properties (a plist). We use that to save the exact major-mode so we can later use it query a buffer-group node’s children.

Finally :children is special in that it has access to 2 parameters:

• The item being rendered, as returned by its parent’s :children data source
• The btn for the node at point, as returned by treemacs-current-button (the value is a text-properties button as it would be created by the builtin button.el library, hence the name)

:on-expand and on-collapse are optional callbacks that are called at the end of the expand/collapse cycle. They too are called with btn as their parameter.

(treemacs-define-expandable-node-type showcase-buffer-group
  :closed-icon "+ "
  :open-icon "- "
  :label (propertize (symbol-name item) 'face 'font-lock-variable-name-face)
  :key item
  :children (treemacs-showcase--buffers-by-mode (treemacs-button-get btn :major-mode))
  :child-type 'showcase-buffer-leaf
  :more-properties `(:major-mode ,item)
  :on-expand (message "Expanding node with key %s" (treemacs-button-get btn :key))
  :on-collapse (message "Collapsing node with key %s" (treemacs-button-get btn :key)))

Finally all that’s left is to define the leaves of our tree - the nodes for the individual buffers.

Nothing new is happening here, we merely save the buffers in a text property so the commands to open and visit them that we have defined above can use that information.

(treemacs-define-leaf-node-type showcase-buffer-leaf
  :icon "• "
  :label (propertize (or (buffer-name item) "#<killed buffer>")
                     'face 'font-lock-string-face)
  :key item
  :more-properties `(:buffer ,item)
  :visit-action #'treemacs-showcase-visit-buffer-action
  :ret-action #'treemacs-showcase-RET-buffer-action)

Killed buffers also need to be taken into account. This is a precaution for when we later turn our buffer extension asynchronous. The chapter on async caching will explain exactly why this is necessary.

All that’s left now it to tell treemacs to actually use the extension we have created. There are 3 options for where the it should be placed:

• at the top-level, the same level as your projects
• under a project
• under a directory

We can also decide whether our extension goes at the top or the bottom of its location.

The latter two options may also accept a :predicate argument, so it is possible to determine exactly which projects and directories an extension will be used for.

For our example we will place the extension as the first item under the first project in the workspace:

(treemacs-enable-project-extension
 :extension 'showcase-buffers
 :position 'top
 :predicate (lambda (project) (eq project (car (treemacs-workspace->projects (treemacs-current-workspace))))))

The argument passed to :extension must be the same symbol that was used for treemacs-define-entry-node-type.

Treemacs also supports nodes that fetch their content from an asynchronous source like a language server. For our simple example we will re-use the buffer code from above and use timers to fake asynchronicity.

Most of the code is the same, there are only 2 differences:

• async nodes must set the :async flag to a non-nil value
• :children is different in that it receives a third argument: a callback function that must be called with the produced items once they are available

(treemacs-define-entry-node-type showcase-async-buffers
  :key 'showcase-buffers-async
  :label (propertize"Async Buffers" 'face 'font-lock-keyword-face)
  :open-icon (treemacs-get-icon-value 'list)
  :closed-icon (treemacs-get-icon-value 'list)
  :children
  (let ((items (treemacs-showcase--buffer-major-modes)))
    (run-with-timer
     (1+ (random 3)) nil
     (lambda () (funcall callback items))))
  :child-type 'showcase-async-buffer-group
  :async? t)

Leaves have no asynchronous parts, so the previous definition can be re-used directly.

(treemacs-define-expandable-node-type showcase-async-buffer-group
  :closed-icon "+ "
  :open-icon "- "
  :label (propertize (symbol-name item) 'face 'font-lock-variable-name-face)
  :key item
  :children
  (let ((items (treemacs-showcase--buffers-by-mode (treemacs-button-get btn :major-mode))))
    (run-with-timer
     (1+ (random 3)) nil
     (lambda () (funcall callback items))))
  :child-type 'showcase-buffer-leaf
  :more-properties `(:major-mode ,item)
  :async? t)

We’ll enable the asynchronous extension at the bottom of first project in treemacs:

(treemacs-enable-project-extension
 :extension 'showcase-async-buffers
 :predicate (lambda (project) (eq project (car (treemacs-workspace->projects (treemacs-current-workspace)))))
 :position 'bottom)

The next time you update your first project both extensions will be there, restarting treemacs is not necessary.

When you try out this async extension you will notice that the first time a node is expanded treemacs adds a Loading… annotation, and the node is only expanded after the 1-3 second delay we have introduced. However every subsequent expansion happens instantly, though sometimes buffers may appear or disappear, or their order changes.

The reason for this behaviour is that all results of asynchronous calls are cached in treemacs, and then re-used for instant updates. This setup is necessary to ensure a smooth experience in the treemacs UI. Imagine what an update would look like without this cache. The basic update procedure in treemacs is the same process as hitting TAB twice - close the node and open it again (this does not apply to filewatch-mode and git-mode, which are both capable of making only the necessary changes).

All this is not visible to the user, all you see is an instant change. This would not be the case for asynchronous nodes. Even if the delay in a real use-case can be measured in milliseconds, you would still see your tree collapse, then add the Loading… annotation, then it would open, then all its previously open subtrees would only open after the same delay, and so on. In addition to that if your point was somewhere in the updated tree it would be moved around, which would be quite annoying if the update happened automatically.

The async cache prevents all that from happening. A real update, fetching new information, does happen, but it happens in the background. Whenever an async node is expanded the cache for the entire subtree is refreshed. Once that is done a second update is run using the new cache.

That is why you sometimes see buffers (dis)appear, or their order change (we don’t do any sorting). That is also why we previously needed to ensure that we can explicitly label killed buffers (since calling buffer-name on a killed buffer throws an error). The initial refresh uses a potentially stale cache. Buffers that were shown once may since have been deleted. They’ll be removed from the view the next time we take a real look at the buffer-list, but in the meantime we’ll have to show a stopgap #<killed buffer> entry.

Using treemacs-update-node will iniate this 2-step update process. If you want to avoid that and directly run just the background update part you can use treemacs-update-async-node instead.

Treemacs’ extensions do not have to be used exclusively within treemacs itself, they may also be put into their own buffers. When doing so it might be useful for an extension to produce multiple top-level nodes from the start, instead of having one single entry point, like the Buffers node from the first example.

Treemacs calls this concept variadic nodes. The following example will demonsrate how to set up such a variadic extension that will produce major-mode buffer group nodes at the top level, and how display this extension in its own side window.

Most of the code from above can be re-used, we just need a new entry point, which we create with treemacs-define-variadic-entry-node-type. The setup is a subset of treemacs-define-entry-node-type - we are effectively creating an invisible entry point that is always extended, so it needs only a small subset of the usual information. Of particular note is the key which allows us the update all nodes created by this variadic entry in one go.

(treemacs-define-variadic-entry-node-type showcase-buffers-variadic
  :key 'showcase-buffers-variadic
  :children (->> (buffer-list)
                 (--reject (string-prefix-p " " (buffer-name it)))
                 (--map (buffer-local-value 'major-mode it))
                 (-distinct))
  :child-type 'showcase-buffer-group)

That’s it. Now we just need to define an interactive command that will display our buffers for us:

(defun showcase-buffer-groups ()
  (interactive)
  (let ((bufname "*Showcase Buffers*"))
    (--when-let (get-buffer bufname) (kill-buffer it))
    (let ((buf (get-buffer-create bufname)))
      (pop-to-buffer buf)
      (treemacs-initialize showcase-buffers-variadic
        :with-expand-depth 'all
        :and-do (setf treemacs-space-between-root-nodes t)))))

treemacs-initialize must be called for the buffer to be used by treemacs. It can optionally accept two keyword arguments:

:with-expand-depth

Indicates the extra depth that this extension should be expanded with. Can be either a number or a symbol like 'all to expand everything.

:and-do

General purpose form for code that should run as part of your setup, like setting buffer-local values (which could otherwise be overridden when initialisation enabled treemacs-mode)

Defining every node type individually is not necessary, it is possible to make do with a single definition. Some verbosity will remain because now it is necessary to dispatch (at a high enough scale, probably thousands of items, it might even impact performance), but it can still be worth it if the number of node types for your use-case is exceptionally high.

Treemacs calls this the monotyped approach to defining extensions.

In this example we combine both the buffer groups and individual buffer leaves into a single definition. (Note how the name of the extension and the :child-type are one and the same)

(treemacs-define-expandable-node-type showcase-monotype-buffers
  :closed-icon
  (if (bufferp item)
      "• "
    "+ ")
  :open-icon
  (if (bufferp item)
      "•"
    "- ")
  :label
  (if (bufferp item)
      (propertize (buffer-name item) 'face 'font-lock-string-face)
    (propertize (symbol-name item) 'face 'font-lock-variable-name-face))
  :key
  (if (bufferp item)
      (buffer-name item)
    item)
  :children
  (when (symbolp item)
    (treemacs-showcase--buffers-by-mode item))
  :child-type
  'showcase-monotype-buffers
  :more-properties
  (if (bufferp item)
      `(:buffer ,item :leaf t)
    `(:major-mode ,item)))

Note that a non-nil :leaf property must be placed manually via :more-properties, since without a distinct node state this is the only way for treemacs to know that the node is a leaf and cannot be expanded.

Entry points cannot be combined, they still need to be set up individually:

(treemacs-define-entry-node-type showcase-buffers-monotype-entry
  :key 'showcase-buffers-monotype-entry
  :label (propertize "Monotype Buffers" 'face 'font-lock-keyword-face)
  :open-icon (treemacs-get-icon-value 'list)
  :closed-icon (treemacs-get-icon-value 'list)
  :children (treemacs-showcase--buffer-major-modes)
  :more-properties nil
  :child-type 'showcase-monotype-buffers)

Finally we’ll enable the new extension to appear in our first project:

(treemacs-enable-project-extension
 :extension 'showcase-buffers-monotype-entry
 :predicate (lambda (project) (eq project (car (treemacs-workspace->projects (treemacs-current-workspace)))))
 :position 'top)

Treemacs sets the value of default-directory based on the nearest path at point. This allows commands like find-file and magit-status to do what you mean based on the current context. This option is also available for custom nodes: just set the property :default-directory and treemacs will make use of its value when the node is in focus.

The following property names are already in use by treemacs and should not be used in extensions’ :more-properties parameter:

• :project
• :state
• :depth
• :path
• :key
• :item
• :no-git
• :parent
• :default-face
• :symlink
• :marker
• :leaf
• :index
• :busy
• :custom
• 'button
• 'category
• 'face
• 'keymap