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]]
  - [[#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