#+TITLE: Treemacs layer #+TAGS: file tree|layer [[file:img/treemacs.png]] * Table of Contents :TOC_5_gh:noexport: - [[#description][Description]] - [[#features][Features:]] - [[#install][Install]] - [[#configuration][Configuration]] - [[#follow-mode][Follow mode]] - [[#file-watch][File watch]] - [[#git-mode][Git mode]] - [[#flattening-of-directories][Flattening of directories]] - [[#locking-width][Locking width]] - [[#key-bindings][Key bindings]] - [[#global][Global]] - [[#inside-treemacs][Inside Treemacs]] - [[#ace-mode-to-open-files][Ace mode to open files]] - [[#set-ace-mode-as-default-action][Set ace mode as default action]] - [[#use-digits-in-ace-mode][Use digits in ace mode]] * Description This layer sets up a file navigation and project explorer side-window via [[https://github.com/Alexander-Miller/treemacs][Treemacs]]. ** Features: A detailed overview of the features of Treemacs is available in [[https://github.com/Alexander-Miller/treemacs#detailed-feature-list][the Treemacs readme]]. In short, Treemacs offers: - Simple and powerful navigation and ability to detail exactly how and where a file should be opened. - Good looking icons. - Display of multiple file trees organized as projects residing in a workspace. - Ability to show tags contained in files. Tags are provided by [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html][Imenu]], so nearly every filetype is supported. - Mouse interface for single and double left clicks in line with modern GUI standards (clicking on an icon will also display the file's tags). - Location awareness: commands like ~find-file~ or ~magit-status~ will use the location of the node at point (with =$HOME= as fallback). - Optional fontifying of files based on their git status. - Optional collapsing of /single-dir-child/ directories into one. - Doing both asynchronously for an imperceptible performance cost. - Optional =follow-mode= to automatically focus the currently selected file or tag. - Optional =filewatch-mode= to automatically refresh the view after (and only after) changes to the shown filesystem. * Install To use this layer, add =treemacs= to =dotspacemacs-configuration-layers= in your =dotspacemacs= file. * Configuration ** Follow mode To have Treemacs automatically sync with your current: - Buffer's file, set the layer variable =treemacs-use-follow-mode= to =t=. - Tag, set the layer variable =treemacs-use-follow-mode= to =tag=. #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( (treemacs :variables treemacs-use-follow-mode 'tag))) #+END_SRC Default is =t=. ** File watch To automatically refresh the Treemacs buffer when there is a change in the part of the file system shown by treemacs set the layer variable =treemacs-use-filewatch-mode= to non-nil. #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( (treemacs :variables treemacs-use-filewatch-mode t))) #+END_SRC Default is =t=. ** Git mode To enable Treemacs to check for the git status information of files and directories and highlight them accordingly, set the layer variable =treemacs-use-git-mode= to =simple=, =extended=, or =deferred=. See the [[https://github.com/Alexander-Miller/treemacs#git-mode][Treemacs documentation]] for a more detailed explanation. #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( (treemacs :variables treemacs-use-git-mode 'deferred))) #+END_SRC Default is =nil=. ** Flattening of directories *This feature requires Python to be installed*. Treemacs tries to flatten empty directory names into one name. It is possible to control how deep Treemacs will search for empty directories by settings the layer variable =treemacs-collapse-dirs= to a positive number. #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( (treemacs :variables treemacs-collapse-dirs 3))) #+END_SRC Default is 3 (or 0 when Python is not installed). ** Locking width To have the width of the treemacs window locked by default, so that it is not manually resizable, set the variable =treemacs-lock-width= to non-nil. It will still be resizable through Treemacs commands and key bindings. #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-configuration-layers '( (treemacs :variables treemacs-lock-width t))) #+END_SRC Default is =nil=. * Key bindings ** Global | Key binding | Description | |-------------+------------------------------------------------------------------------------------------------------------------------------------------------| | ~M-0~ | Selected the treemacs window. Actually selects window #10, which is always assigned to treemacs. | | ~SPC 0~ | Open treemacs in the current directory. When not visiting a file use $HOME as fallback. With a prefix arg manually select the root instead. | | ~SPC f B~ | Find and select a bookmark. If it cannot be found rebuild view with the bookmark's location as root. Also open the bookmark with a prefix arg. | | ~SPC f t~ | Hide/show existing treemacs buffer. Create one for the current directory if no buffer exists. | | ~SPC f T~ | Manually focus the treemacs view on the currently selected file. Not needed when =treemacs-follow-mode= is enabled. | | ~SPC f M-t~ | Manually focus the treemacs view on the currently selected file and tag. | | ~SPC p t~ | Hide/show existing treemacs buffer. Add the current project to treemacs if not already added. | ** Inside Treemacs Treemacs will use either ~j/k~ or ~n/p~ to go to the next/previous line, depending on whether vim/hybrid editing style is used. Likewise refresh is only bound to g when emacs editing style is used, since under vim g is a prefix for many other commands. | Key binding | Description | |-------------+------------------------------------------------------------------------------------------------------------------| | ~?~ | Summon the helpful hydra to show you the treemacs keymap. | | ~M-j/M-n~ | Select next node at the same depth as currently selected node, if possible. | | ~j/n~ | Goto next line. | | ~k/p~ | Goto previous line. | | ~M-J/N~ | Go to the next line in ~next-window~. | | ~M-K/P~ | Go to the previous line in ~next-window~.. | | ~M-j/M-n~ | Select next node at the same depth as currently selected node, if possible. | | ~M-k/M-p~ | Select previous node at the same depth as currently selected node, if possible. | | ~C-c C-p a~ | Select a new project to add to the treemacs workspace. | | ~C-c C-p p~ | Select a projectile project to add to the workspace. | | ~C-c C-p d~ | Remove project at point from the workspace. | | ~C-c C-p r~ | Rename project at point. | | ~th~ | Toggle the hiding and displaying of dotfiles. | | ~tw~ | Toggle whether the treemacs buffer should have a fixed width. | | ~tf~ | Toggle treemacs-follow-mode. | | ~ta~ | treemacs-filewatch-mode. | | ~w~ | Set a new value for the width of the treemacs window. | | ~TAB~ | Do what I mean (as defined in ~treemacs-TAB-actions-config~). Prefers expanding nodes by default. | | ~RET~ | Do what I mean (as defined in ~treemacs-RET-actions-config~). Prefers visiting nodes by default. | | ~mouse1~ | Move point to clicked line | | ~2x mouse1~ | Do what I mean (as defined in ~treemacs-doubleclick-actions-config~). Behaves like ~RET~ by default. | | ~g/r/gr~ | Refresh and rebuild the treemacs buffer. | | ~d~ | Delete node at point. A delete action must always be confirmed. Directories are deleted recursively. | | ~cf~ | Create a file. | | ~cd~ | Create a directory. | | ~R~ | Rename the currently selected node. Reload buffers visiting renamed files or files in renamed directories. | | ~u~ | Select parent of selected node, if possible. | | ~q~ | Hide/show an existing treemacs buffer. | | ~Q~ | Kill the treemacs buffer. | | ~ov~ | Open current file or tag by vertically splitting ~next-window~. | | ~oh~ | Open current file or tag by horizontally splitting ~next-window~. | | ~oo~ | Open current file or tag, performing no split and using ~next-window~ directly. | | ~oaa~ | Open current file or tag, using ace-window to decide which window to open the file in. | | ~oah~ | Open current file or tag by horizontally splitting a window selected by ace-window. | | ~oav~ | Open current file or tag by vertically splitting a window selected by ace-window. | | ~ox~ | Open current file according to its mime type in an external application. Linux, Windows and macOS are supported. | | ~ta~ | Toggle ~treemacs-filewatch-mode~. | | ~tf~ | Toggle ~treemacs-follow-mode~. | | ~th~ | Toggle the hiding and displaying of dotfiles. | | ~tw~ | Toggle whether the treemacs buffer should have a fixed width. | | ~yr~ | Copy the absolute path of the nearest project node at point. | | ~yy~ | Copy the absolute path of the node at point. | *** Ace mode to open files It is possible to open the file under cursor in exact the window you want. By default you have to press ~o a a~ to run ace selection mode and choose the window with keys ~a s d f~. That behavior can be changed in two ways. **** Set ace mode as default action It is possible to set =ace mode= as default action for pressing RET on a file. To do this add following configuration to your dotfile. #+BEGIN_SRC emacs-lisp (treemacs-define-RET-action 'file-node-closed #'treemacs-visit-node-ace) (treemacs-define-RET-action 'file-node-open #'treemacs-visit-node-ace) #+END_SRC **** Use digits in ace mode Just add the following to use digits instead of ~a s d f~ in ace (window selection) mode. Please note that the following code changes ace mode globally. #+BEGIN_SRC emacs-lisp (setq aw-keys '(?1 ?2 ?3 ?4 ?5 ?6 ?7 ?8 ?9 ?0)) #+END_SRC