- Quick Feature Overview
- Quick Start
- Detailed Feature List
- Installation
- Configuration
- 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
andtreemacs-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
andtreemacs-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:
treemacs-follow
tries to be very specific about when it is run at all.- 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:
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. |
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. |
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:
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 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)))
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.
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. |
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. |
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 modetreemacs-mode
is derived from. - Using
winum-mode
with a scope other thanframe-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 assignedtreemacs-winum-number
as their window number. To prevent this treemacs will only be assigned a custom number when the value ofwinum-scope
isframe-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 itshl-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