rswgnu/treemacs

Treemacs - a tree layout file explorer for Emacs

Content

• 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

Quick Feature Overview

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.

Quick Start

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

Detailed Feature List

Frame Locality

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.

Follow-mode

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.

Tag-follow-mode

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.

Filewatch-mode

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.

Session Persistence

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.

Terminal Compatibility

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.

Tag View

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.

Additional Packages

Next to treemacs itself you can optionally install:

treemacs-evil

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.

treemacs-projectile

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.

Installation

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)))

Configuration

Variables

Treemacs offers the following configuration options:

Variable	Default	Description
treemacs-indentation	2	The number of spaces each level is indented in the tree.
treemacs-indentation-string	” ”	The string that is used to create indentation.
treemacs-width	35	Width of the treemacs window.
treemacs-show-hidden-files	t	Dotfiles will be shown if this is set to t and be hidden otherwise.
treemacs-header-function	treemacs–create-header	The function which is used to create the header string for treemacs buffers. Default options are treemacs--create-header and treemacs--create-header-projectile. Any function that takes the current root path and returns the header string may be used.
treemacs-git-integration	based on (executable-find “git”)	When t use different faces for files’ different git states.
treemacs-follow-after-init	nil	When t follow the currently selected file after initializing the treemacs buffer, regardless of treemacs-follow-mode setting.
treemacs-change-root-without-asking	nil	When t don’t ask to change the root when calling treemacs-find-file.
treemacs-never-persist	nil	When t treemacs will never persist its state.
treemacs-sorting	alphabetic-asc	Indicates how treemacs will sort its files and directories. Files will still always be shown after directories. Valid values are alphabetic-asc, alphabetic-desc, size-asc, size-desc, mod-time-asc, mod-time-desc.
treemacs-ignored-file-predicates	(treemacs–std-ignore-file-predicate)	List of predicates to test for files ignored by Emacs. Ignored files will never be shown in the treemacs buffer (unlike dotfiles) whose presence is controlled by treemacs-show-hidden-files). Each predicate is a function that takes a file’s name and absolute path as its arguments and returns t if the file should be ignored and nil otherwise. A file whose name returns t for any function in this list counts as ignored. By default this list contains treemacs--std-ignore-file-predicate which filters out ‘.’, ‘..’, Emacs’ lock files as well as flycheck’s temp files, and therefore should not be directly overwritten, but added to and removed from instead.
treemacs-pre-file-insert-predicates	nil	List of predicates to test for files not to be rendered. Unlike treemacs-ignored-file-predicates this runs when files’ git status information is available.
treemacs-file-event-delay	5000	How long (in milliseconds) to collect file events before refreshing. When treemacs receives a file change notification it doesn’t immediately refresh and instead waits treemacs--file-event-delay milliseconds to collect further file change events. This is done so as to avoid refreshing multiple times in a short time. See also treemacs-filewatch-mode.
treemacs-goto-tag-strategy	refetch-index	Indicates how to move to a tag when its buffer is dead. The tags in the treemacs view store their position as markers pointing to a buffer. If that buffer is killed, or has never really been open, as treemacs kills buffer after fetching their tags if they did no exist before, the stored positions become stale, and treemacs needs to use a different method to move to that tag. This variable sets that method. Its possible values are: refetch-index: Call up the file’s imenu index again and use its information to jump. call-xref: Call xref-find-definitions to find the tag. issue-warning: Just issue a warning that the tag’s position pointer is invalid.
treemacs-default-actions	Open/close dirs & tag sections, treemacs-visit-node-no-split for files & tags	Defines the behaviour of treemacs-visit-node-default-action. Each alist element maps from a button state to the function that should be used for that state. The list of all possible button states is defined in treemacs-valid-button-states. Possible values are all treemacs-visit-node-* functions as well as treemacs-push-button for simple open/close actions. To keep the alist clean changes should not be made directly, but with treemacs-define-default-action.
treemacs-collapse-dirs	0	When > 0 treemacs will collapse directories into one when possible. A directory is collapsible when its content consists of nothing but another directory. The value determines how many directories can be collapsed at once, both as a performance cap and to prevent too long directory names in the treemacs view. To minimize this option’s impact on display performance the search for directories to collapse is done asynchronously in a python script and will thus only work when python installed. The script should work both on python2 and 3.
treemacs-silent-refresh	nil	When non-nil a completed refresh will not be announced with a message. This applies both to manual refreshing as well as automatic (due to e.g. treemacs-filewatch-mode).
treemacs-silent-filewatch	nil	When non-nil a refresh due to filewatch mode will cause no log message.
treemacs-is-never-other-window	nil	When non-nil treemacs will never be used as other-window. This can prevent other packages from opening other buffers in the treemacs window. It also means treemacs is never selected by calls to other-window.
treemacs-position	left	Position of treemacs buffer. Valid values are left, right.
treemacs-tag-follow-delay	1.5	Delay in seconds of inactivity for treemacs-tag-follow-mode to trigger.
treemacs-winum-number	10	Window number treemacs will always assume when winum.el is used. Set to nil to disable the static number assignment.
treemacs-no-png-images	nil	When non-nil treemacs will use TUI string icons even when running in a GUI.

Faces

Treemacs defines and uses the following faces:

Face	Inherits from	Description
treemacs-directory-face	font-lock-function-name-face	Face used for directories.
treemacs-directory-collapsed-face	treemacs-directory-face	Face used for collapsed part of directories.
treemacs-file-face	default	Face used for files.
treemacs-header-face	font-lock-constant-face (underlined & size 1.4)	Face used for the treemacs header.
treemacs-term-node-face	font-lock-string-face	Face for directory node symbols used by treemacs when it runs in a terminal.
treemacs-git-*-face	various font lock faces	Faces used by treemacs for various git states.

Evil compatibility

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.

Custom header function

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)

Custom Icons

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.

Directory Icons

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:

Variable	Value in GUI	Value in TUI
treemacs-icop-open	treemacs-icon-open-png	treemacs-icon-open-text
treemacs-icon-closed	treemacs-icon-closed-png	treemacs-icon-closed-text

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

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:

Variable	Value in GUI	Value in TUI
treemacs-icop-tag-node-open	treemacs-icop-tag-node-open-png	treemacs-icop-tag-node-open-txt
treemacs-icon-tag-node-closed	treemacs-icon-tag-node-closed-png	treemacs-icon-tag-node-closed-txt
treemacs-icon-tag-leaf	treemacs-icon-tag-leaf-png	treemacs-icon-tag-leaf-txt

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)))

File Icons

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"))

Icons according to auto-mode-alist

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))))

GUI vs TUI

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

Indent guide

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)

Keymap

Unbound functions

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.

Action	Description
treemacs	Open treemacs with current buffer’s directory as root. If the current buffer is not visiting any files use $HOME as fallback. If a prefix argument is given manually select the root directory.
treemacs-projectile	Open treemacs for the current projectile project. If not in a project do nothing. If a prefix argument is given select the project from among projectile-known-projects.
treemacs-toggle	If a treemacs buffer exists and is visible hide it. If a treemacs buffer exists, but is not visible bring it to the foreground and select it. If no treemacs buffer exists call treemacs.
treemacs-toggle-projectile	If a treemacs buffer exists and is visible hide it. If a treemacs buffer exists, but is not visible bring it to the foreground and select it. If no treemacs buffer exists call treemacs-projectile.
treemacs-find-file	Find and move point to PATH (or the current file) in the treemacs buffer. Expand folders if needed.
treemacs-find-tag	Find and move point to the tag at point in the treemacs view. Expand folders if or as to change root if needed. Create treemacs buffer if none exists.
treemacs-select-window	Select the treemacs window if it is visible. Call treemacs-toggle if it is not.
treemacs-delete-other-windows	Same as delete-other-windows, but will not delete the treemacs window.
treemacs-push-button-select-sort	Same as treemacs-push-button, but the sorting function is chosen manually. The sort setting is active for only a single push, its effect will be undone on the next refresh.

Default keymap

By default Treemacs’s keymap looks as follows:

Key	Action	Description
?	treemacs-helpful-hydra	Summon the helpful hydra to show you the treemacs keymap.
j/n	treemacs-next-line	Goto next line.
k/p	treemacs-previous-line	Goto previous line.
h	treemacs-uproot	Switch treemacs’ root directory to current root’s parent, if possible.
l	treemacs-change-root	Use currently selected directory as new root. Do nothing for files.
M-j/M-n	treemacs-next-neighbour	Select next node at the same depth as currently selected node, if possible.
M-k/M-p	treemacs-previous-neighbour	Select previous node at the same depth as currently selected node, if possible.
th	treemacs-toggle-show-dotfiles	Toggle the hiding and displaying of dotfiles.
tw	treemacs-toggle-fixed-width	Toggle whether the treemacs window should have a fixed width. See also treemacs-width.
tf	treemacs-follow-mode	Toggle treemacs-follow-mode (see above).
ta	treemacs-filewatch-mode	Toggle treemacs-filewatch-mode (see above).
w	treemacs-reset-width	Reset the width of the treemacs window to treemacs-width. If a prefix argument is provided read a new value for treemacs-width first.
TAB	treemacs-push-button	Push the button in the current line. For directories, files and tag sections expand/close the button. For tags go to the tag definition via treemacs-visit-node-no-split.
mouse1	treemacs-click-mouse1	Do the same as treemacs-push-button when mouse1-clicking on an line.
g/r/gr	treemacs-refresh	Refresh and rebuild the treemacs buffer.
d	treemacs-delete	Delete node at point. A delete action must always be confirmed. Directories are deleted recursively.
cf	treemacs-create-file	Create a file.
cd	treemacs-create-dir	Create a directory.
R	treemacs-rename	Rename the currently selected node. Reload buffers visiting renamed files or files in renamed directories.
u	treemacs-goto-parent-node	Select parent of selected node, if possible.
q	treemacs-toggle	Hide/show an existing treemacs window.
Q	treemacs-kill-buffer	Kill the treemacs buffer.
RET	treemacs-visit-node-default-action	Run the action defined in treemacs-default-actions for the current button.
ov	treemacs-visit-node-vertical-split	Open current file or tag by vertically splitting next-window. Stay in current window with a prefix argument.
oh	treemacs-visit-node-horizontal-split	Open current file or tag by horizontally splitting next-window. Stay in current window with a prefix argument.
oo/RET	treemacs-visit-node-no-split	Open current file or tag, performing no split and using next-window directly. Stay in current window with a prefix argument.
oaa	treemacs-visit-node-ace	Open current file or tag, using ace-window to decide which window to open the file in. Stay in current window with a prefix argument.
oah	treemacs-visit-node-ace-horizontal-split	Open current file or tag by horizontally splitting a window selected by ace-window. Stay in current window with a prefix argument.
oav	treemacs-visit-node-ace-vertical-split	Open current file or tag by vertically splitting a window selected by ace-window. Stay in current window with a prefix argument.
ox	treemacs-visit-node-in-external-application	Open current file according to its mime type in an external application. Linux, Windows and Mac are supported.
yy	treemacs-yank-path-at-point	Copy the absolute path of the node at point.
yr	treemacs-yank-root	Copy the absolute path of the current treemacs root.
s	treemacs-resort	Set a new value for treemacs-sorting. With a single or double prefix arg temporarily resort the current directory/the entire buffer.

Compatibility

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.

FAQ

• 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.

Working With The Code Base

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

Dependencies

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