• Quick Feature Overview
• Quick Start
• Detailed Feature List
  • Frame Locality
  • Follow-mode
  • Tag-follow-mode
  • Filewatch-mode
  • Session Persistence
  • Terminal Compatibility
  • Tag View
  • Additional Packages
    • treemacs-evil
    • treemacs-projectile
• Installation
• Configuration
  • Variables
  • Faces
  • Evil compatibility
  • Custom header function
  • Custom Icons
    • Directory Icons
    • Tag Icons
    • File Icons
    • Icons according to ~auto-mode-alist~
    • GUI vs TUI
    • Indent guide
• Keymap
  • Unbound functions
  • Default keymap
• Compatibility
• FAQ
• Working With The Code Base
• Dependencies

Treemacs is a file and project explorer in the same vein as NeoTree or vim’s NerdTree. It shows the file system outline in a simple tree layout allowing quick navigation and exploration, while also possessing basic file management utilities. Specifically a quick feature overview looks as follows:

• Easy navigation - quickly change the root directory or use shortcuts to jump to parent or neighbouring nodes.
• Versatile file access - decide exactly how and where a file will be opened, including using ace-window to choose a window or launching an external application.
• Treemacs respects frames - every frame will receive its own treemacs buffer that will live and die with that frame.
• Optionally always follow along and keep in focus the currently selected file or even the tag at point using treemacs-follow-mode and treemacs-tag-follow-mode respectively.
• Optional git integration - treemacs will use different faces for files based on their git status. The git process runs asynchronously and so won’t cause any perceptible delay.
• Winum integration - treemacs will always be assigned a static window number (10 by default), never interfering with the numbering layout of your other windows.
• Projectile integration via the treemacs-projectile package to quickly open treemacs at any known project’s root directory.
• Simple mouse interface - you can close/expand folders and open files by left-clicking.
• Dashing good looks - treemacs uses genuine png images in HD 22x22 resolution for its icons (quantity is, of course, another matter). When run in a terminal a very simple fallback is used.
• Session persistence with desktop-save-mode
• Treemacs is able to display files’ tags. All file types that emacs can generate a (semantic) imenu index for are supported.
• Ease of use - treemacs offers many configuration options, but comes with a set of (what hopefully should be) sane defaults. Installation aside there are two obligatory pieces of setup: 1) Choosing convenient keybindings to run treemacs and 2) If you use evil: requiring treemacs-evil to integrate treemacs with evil and enable j/k navigation. More on both below.

If you don’t care about reading the full readme here’s a list of some bare bones basics to get you started:

• First of all: press ? to summon the helpful hydra:
• If you use evil don’t forget to also install treemacs-evil
• If you use projectile you can install treemacs-projectile to allow treemacs to interact with projects.
• Treemacs doesn’t bind any global keys, you need to use whatever fits you best. A full install setup for spacemacs can be found below. Otherwise just bind treemacs and treemacs-toggle.
• For navigation use n/p (j/k when evil), M-n/M-p to move to same-height neighbour u to go to parent, h to move up a dir, l to move root to selected dir
• TAB always opens and closes nodes. Files can be opened, too - treemacs will show their imenu index.
• There’s half a dozen different ways to open nodes, all bound under o as prefix. Pick your favourite.
• RET runs a default action, configurable to your tastes under treemacs-default-actions

Treemacs buffers have a limited scope they are visible in: the frames they are created in. A treemacs buffer, once created, lives alongside and inside its frame, and is also destroyed with that frame. Calling a function like treemacs-toggle while inside a new frame will create a new buffer for it, reguardless how many other treemacs buffers already exist.

This allows to use treemacs to work on multiple projects inside the same emacs session.

A treemacs buffer that does not belong to a frame may still be made visible by manually selecting in in the buffer list. This would break various assumptions in treemacs’ code base and effectively falls under undefined behaviour - a bad idea all around.

treemacs-follow-mode is a minor mode which allows the treemacs view to always move its focus to the currently selected file. This is achieved by advising select-window, which is a ubiquitous function, often called multiple times in a row when emacs is working. This means two things:

1. treemacs-follow tries to be very specific about when it is run at all.
2. There may be times when something slips through (which-key for example would cause such a problem if treemacs

wasn’t made compatible with it by default). If you do see treemacs-follow behaving in a way it shouldn’t open up an issue. The fix shouldn’t be more than a single bit of advice away.

treemacs-tag-follow-mode is a minor mode which extends and effectively replaces treemacs-follow-mode. When activated it follows not just the current file, but also the current tag. This works alongside treemacs’ with imenu, so all file types providing an imenu implementation are compatible.

This mode runs on an idle timer - the exact duration of inactivity (in seconds) is determined by treemacs-tag-follow-delay.

Note that in order to move to a tag in treemacs the treemacs buffer’s window needs to be temporarily selected, which will reset blink-cursor-mode’s timer if it is enabled. This will result in the cursor blinking seemingly pausing for a short time and giving the appereance of the tag follow action lasting much longer than it really does.

treemacs-filewatch-mode is a minor mode which enables treemacs to watch the files it is displaying for changes and automatically refresh itself by means of treemacs-refresh when it detects a change that it decides is relevant.

A file event is relevant for treemacs if a new file has been created or deleted or a file has been changed and treemacs-git-integration is t. Events caused by files that are ignored as per treemacs-ignored-file-predicates are likewise counted as not relevant.

The refresh is not called immediately after an event was received, treemacs instead waits treemacs-file-event-delay ms to see if any more files have changed to avoid having to refresh multiple times over a short period of time. If the treemacs buffer exists, but is not visible, a refresh will be run the next time it is shown.

The change only applies to directories opened after this mode has been activated. This means that to enable file watching in an already existing treemacs buffer it needs to be torn down and rebuilt by calling treemacs or treemacs-projectile.

Turning off this mode is, on the other hand, instantaneous - it will immediately turn off all existing file watch processes and outstanding refresh actions.

Known limitations: Staging and committing changes does not produce any file change events of its own, if you use treemacs-git-integration you still need to do a manual refresh to see your files’ face go from ‘changed’ and ‘untracked’ to ‘unchanged’ after a commit.

To persist treemacs state beyond emacs’ shutdown treemacs offers integration with the builtin desktop-save-mode. This integration shoud work out of the box and require zero setup and configuration (aside from the option to turn it off with treemacs-never-persist).

The persisted state is saved under user-emacs-directory/.cache/treemacs-persist. The exact file location is saved in the variable treemacs--persist-file.

Persistence by means other than desktop-save-mode (like persp-mode) is not supported since treemacs’ frame-bound nature makes integration very difficult if not outright impossible.

When run in a terminal treemacs will fall back to a much simpler rendering system, foregoing its usual png icons and using simple + and - characters instead. Changes to the current rendering system are detected automatically - within some limits. The check for the change happens with treemacs’ functions which build or show/hide the treemacs buffer, namely treemacs(-projectile). treemacs(-projectile)-toggle and treemacs-refresh.

Treemacs is able to display not only the file system, but also tags found in individual files. The tags list is sourced using emacs’ builtin imenu functionality, so all file types that emacs can generate an imenu index for are supported. Imenu caches its result, so to avoid stale tag lists setting imenu-auto-rescan to t is recommended. Tags generated with the help of semantic-mode are likewise supported.

Tag view support is in an early beta release stage, and so (other than the increased likelihood of bugs), it’s currently missing certain features:

• It won’t look right in the terminal, there aren’t any terminal icons for tags yet.

Next to treemacs itself you can optionally install:

Must be installed and loaded if you use evil. The keybindings and the cursor will not be setup properly otherwise. It’ll also enable navigation navigation with j/k instead of n/p.

Introduces projectile-centric counterparts for treemacs-launching commands, namely treemacs-projectile and treemacs-projectile-toggle. Also adds treemacs-create-header-projectile to be used as a value for treemacs-header-function.

Treemacs is included in spacemacs. If you are using the development version of spacemacs you can simply add treemacs to dotspacemacs-configuration-layers to replace the default neotree. Check SPC h SPC treemacs for details.

Treemacs is also available from MELPA. If you just want to quickly start using it grab the use-package example below, and customize it as needed (remove treemacs-evil if you don’t use it, customize the keybinds as needed, the example code uses keys based on the spacemacs layer).

Either way keep in mind that treemacs has no default keybinds for its globally callable initialization functions. Each user is supposed to select keybinds for functions like treemacs, treemacs-toggle and their projectile counterparts based on whatever they find convenient.

You can find an exhaustive overview of all functions, their keybinds and functions you need to bind yourself below.

(use-package treemacs
  :ensure t
  :defer t
  :config
  (progn
    (use-package treemacs-evil
      :ensure t
      :demand t)
    (setq treemacs-follow-after-init          t
          treemacs-width                      35
          treemacs-indentation                2
          treemacs-git-integration            t
          treemacs-collapse-dirs              (if (executable-find "python") 3 0)
          treemacs-silent-refresh             nil
          treemacs-change-root-without-asking nil
          treemacs-sorting                    'alphabetic-desc
          treemacs-show-hidden-files          t
          treemacs-never-persist              nil
          treemacs-is-never-other-window      nil
          treemacs-goto-tag-strategy          'refetch-index)

    (treemacs-follow-mode t)
    (treemacs-filewatch-mode t))
  :bind
  (:map global-map
        ([f8]         . treemacs-toggle)
        ("M-0"        . treemacs-select-window)
        ("C-c 1"      . treemacs-delete-other-windows)
        ("M-m ft"     . treemacs-toggle)
        ("M-m fT"     . treemacs)
        ("M-m fB"     . treemacs-bookmark)
        ("M-m f C-t"  . treemacs-find-file)
        ("M-m f M-t"  . treemacs-find-tag)))
(use-package treemacs-projectile
  :defer t
  :ensure t
  :config
  (setq treemacs-header-function #'treemacs-projectile-create-header)
  :bind (:map global-map
              ("M-m fP" . treemacs-projectile)
              ("M-m fp" . treemacs-projectile-toggle)))

Treemacs offers the following configuration options:

Treemacs defines and uses the following faces:

To make treemacs get along with evil-mode you need to install and load treemacs-evil. It does not define any functions or offer any configuration options, making sure it is loaded is sufficient.

The function which creates the header in treemacs is easily replaced (see the entry for treemacs-header-function in the section about configuration variables for details). To use your own custom header you just need to define a function that formats the header as you wish and then tell treemacs to use it:

(defun treemacs-header-with-brackets (current-root)
  (format "<%s>" (file-name-nondirectory current-root)))
(setq treemacs-header-function #'treemacs-header-with-brackets)

The icons treemacs uses can be roughly divided into 3 groups (with the first 2 behaving identically). Each group also makes further adjustments depending on whether treemacs is shown in a GUI or terminal frame.

Changes to icons, as described below, will takes place when a treemacs buffer is reinitialized. This means you need to call a function like treemacs or treemacs-projectile.

The changes to icons can be reverted by calling treemacs-reset-icons.

Important: There is a restriction that all icons must must be exactly 2 characters long. That’s including the space that will separate an icon from filename.

These are the 2 icons used for expanded or closed directory nodes. They are stored in the variables treemacs-icop-open and treemacs-icon-closed. Depending on whether the treemacs instance runs in a gui or tui they’ll assume different values stored in other variables:

To change the display of directory nodes you need to overwrite the values of the png/text variables. For example the code to use unicode icons to display directories in gui mode could look like this:

(with-eval-after-load "treemacs"
  (setq treemacs-icon-open-png   (propertize "⊖ " 'face 'treemacs-directory-face)
        treemacs-icon-closed-png (propertize "⊕ " 'face 'treemacs-directory-face)))

Tag icons behave just like directory icons, except there’s 3 of them: one for closed tag sections, one for open tag sections and one for the tags proper:

Same as above, to change the display of tag nodes you need to overwrite the values of the png/text variables. For example the code to use unicode icons to display tags in gui mode could look like this:

(with-eval-after-load "treemacs"
  (setq treemacs-icon-tag-node-open-png   (propertize "− " 'face 'font-lock-keyword-face)
        treemacs-icon-tag-node-closed-png (propertize "+ " 'face 'font-lock-keyword-face)
        treemacs-icon-tag-leaf-png        (propertize "🞄 " 'face 'font-lock-keyword-face)))

First of all if you have an icon you’d like to make use of in treemacs my preferred solution is very much for you to open a pull request (adding a new icon is a one-liner in treemacs-visuals.el) or an issue to let me know about a good icon I can add.

If that’s not possible or if you’d like to use something like all-the-icons.el (which isn’t used in treemacs by default due to iconic fonts not being monospaced and so would look bad) treemacs offers the option to use your own custom file icons.

File icons are implemented differently than the other icon groups. They too exist as variables, usually named like treemacs-icon-html, but the selection process happens through a hashtable - treemacs-icons-hash - which maps file extensions to their icons. Note that treemacs has a very loose definition of what constitutes a file extension - it’s either everything past the last period, or just the file’s full name if there is no period. This makes it possible to match file names like ‘.gitignore’ and ‘Makefile’. Extensions are not case-sensitive and will be downcased.

There is also the special case of treemacs-icon-fallback, which is used when a file extension has no specific icon assigned to it. It takes the value treemacs-icon-text in a GUI and treemacs-icon-fallback-text in a TUI.

While it is possible to directly push a mapping to treemacs-icons-hash treemacs also offers the utility function treemacs-define-custom-icon. It takes as its arguments an icon (a string) and as &rest a list of file extension to use the icon for. Already present icons for the given extensions will be overwritten.

Using it would look like this:

(with-eval-after-load "treemacs"
  (defvar treemacs-custom-html-icon (all-the-icons-icon-for-file "name.html"))
  (treemacs-define-custom-icon treemacs-custom-html-icon "html" "htm"))

For some file extensions, like “.cc” or “.hh”, it is not immediately obvious which major mode will open these files, and thus which icon they should be assigned. Treemacs offers the option that automate this decision based on auto-mode-alist. You can use the function treemacs-map-icons-with-auto-mode-alist to change the assigned icons for a list of file extensions based on the major mode the icons are mapped to in auto-mode-alist.

treemacs-map-icons-with-auto-mode-alist takes 2 arguments: first a list of file extensions, then an alist that decides which icon should be used for which mapped major mode. For example the code to decide the icons for “.hh” and “.cc” files with auto-mode-alist would look like this:

(with-eval-after-load "treemacs"
  (treemacs-map-icons-with-auto-mode-alist
    '(".cc" ".hh")
    '((c-mode . treemacs-icon-c)
      (c++-mode . treemacs-icon-cpp))))

It is possible to force treemacs to use the simple TUI icons in GUI mode by setting treemacs-no-png-images to t.

Not really part of the icons, but a useful visual feature nonetheless: An indent guide like effect can be created by selecting appropriate values for treemacs-indentation and treemacs-indentation-string:

(setq treemacs-indentation-string (propertize " ⫶ " 'face 'font-lock-comment-face)
      treemacs-indentation 1)

These functions are not bound to any keys by default. It’s left up to users to find the most convenient key binds. Additionally treemacs-refresh, treemacs-select-window and treemacs-find-file may also be called from outside the treemacs window and might therefore need their own global binding.

By default Treemacs’s keymap looks as follows:

The correctness of treemacs’ display behaviour is, to a large degree, ensured through window properties and reacting to changes in the window configuration. The packages most likely to cause trouble for treemacs are therefore those that interfere with Emacs’ buffer spawning and window splitting behaviour. Treemacs is included in spacemacs and I am a spacemacs user, therefore treemacs guarantees first-class support & compatibility for window-managing packages used in spacemacs, namely persp, eyebrowse, popwin and window-purpose, as well as shackle. For everything else there may be issues and, depending on the complexity of the problem, I may decide it is not worth fixing.

Aside from this there are the following known incompatibilities:

• Any package invoking font-lock-ensure in the treemacs buffer. This will reset the faces of treemacs’ buttons (once) and is a known emacs bug.
• The only known example of this is an older version of swiper.
• Rainbow mode activated in treemacs will likewise cause this behaviour. Make sure not to include rainbow-mode as part of special-mode-hook, since this is the mode treemacs-mode is derived from.
• Using winum-mode with a scope other than frame-local means that potentially multiple treemacs windows can be part of the same window numbering scheme, resulting in a conflict since by default all treemacs windows are assigned treemacs-winum-number as their window number. To prevent this treemacs will only be assigned a custom number when the value of winum-scope is frame-local.

• Why am I seeing no file icons and only +/- for directories?

  Treemacs will permanently fall back on its simple TUI icons if it detects that the emacs instance it is run in cannot create images. You can test this by evaluating (create-image "" 'png). If this code returns an error like “Invalid image type ´png´” your emacs does not support images.

• Why is treemacs warning me about not being able to find some background colors and falling back to something else?

  Treemacs needs those colors to make sure that background colors of its icons correctly align with hl-line-mode. Png images’ backgrounds are not highlighted by hl-line-mode by default, treemacs manually corrects this. To that end it needs two colors: the current theme’s default background, and its hl-line background color. If treemacs cannot find hl-lines’s background color it falls back to the default background color. If it cannot even find the default background it will fall back to #2d2d31. The warnings serve to inform you of that fallback.

  If your theme does not define a required color you can set it yourself before treemacs loads like this:

  (set-face-attribute 'hl-line nil :background "#333333")
      

  If you just want to disable the warnings you can do so by defining the varialbe treemacs-no-load-time-warnings. Its exact value is irrelevant, all that matters is that it exists at all. Since the warnings are issues when treemacs is first being loaded the variable must be defined before treemacs is initialized. This is best achieved by adding the line (defvar treemacs-no-load-time-warnings t) to treemacs use-package’s :init block.

If you want to delve into the treemacs’ code base, check out the wiki for some general pointers.

• emacs >= 24.4
• f.el
• s.el
• dash
• cl-lib
• ace-window
• pfuture
• hydra
• (optionally) evil
• (optionally) projectile
• (optionally) winum