spacemacs/layers/+filetree/treemacs/README.org

#+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]]
  - [[#scope-settings][Scope Settings]]
  - [[#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=.

** Scope Settings
By default treemacs buffers and their workspaces will be uniquely scoped within
the current frame. As an alternative it is possible to scope treemacs to the
currently active perspective, including the automatic creation of a workspace
for every perspective. The scope type is determined by setting the layer
variable =treemacs-use-scope-type= to either ='Frames= or ='Perspectives=.

Note that persective-based scoping will only take effect when =persp-mode= is
actually first used.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (treemacs :variables treemacs-use-persp-scope 'Perspectives)))
#+END_SRC

Default is ='Frames=.

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