spacemacs/layers/+tools/ranger/README.org

#+TITLE: Ranger layer

#+TAGS: layer|tool

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#configuration][Configuration]]
  - [[#customizing][Customizing]]
  - [[#parent-options][Parent options]]
  - [[#preview-options][Preview options]]
- [[#key-bindings][Key bindings]]

* Description
This layer brings Ranger features to spacemacs from the =ranger= package.

To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =ranger= to the existing =dotspacemacs-configuration-layers= list in this
file.

To use ranger/deer by default set ~ranger-override-dired~ to ~ranger/deer~ like
shown in the example below (setting this via customize as explained by the
original [[https://github.com/ralesi/ranger.el#installation][ranger installation instructions]] will not work). To default with
preview enabled when entering ranger set ~ranger-show-preview~ to ~t~. The following
example code shows how you can set both variables at once via the
~dotspacemacs-configuration-layers~ of your dotfiles as follows:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '(ranger :variables
                         ranger-override-dired 'ranger
                         ranger-show-preview t))
#+END_SRC

** Features:
- use ranger to display dired with ranger like preview and stacked parent windows.

* Configuration
Most parameters can be toggled on and off and stay within the current emacs
session. Any settings that are desired on startup should be set below.

** Customizing
Toggle the use of =-= to enter deer or ranger with =ranger-enter-with-minus=.
The possible values are:
- ='deer= (default)
- ='ranger=
- =nil= (restores the default behavior of =-=)

#+BEGIN_SRC elisp
  (setq ranger-enter-with-minus 'deer)
#+END_SRC

When disabling the mode you can choose to kill the buffers that were opened
while browsing the directories.

#+BEGIN_SRC elisp
  (setq ranger-cleanup-on-disable t)
#+END_SRC

Or you can choose to kill the buffer just after you move to another entry in the
dired buffer.

#+BEGIN_SRC elisp
  (setq ranger-cleanup-eagerly t)
#+END_SRC

You can choose to show dotfiles at ranger startup, toggled by =zh=

#+BEGIN_SRC elisp
  (setq ranger-show-hidden t)
#+END_SRC

Define custom function used to output header of primary ranger window. Must
return a string that is placed in the header-line.

#+BEGIN_SRC elisp
  (setq ranger-header-func 'ranger-header-line)
#+END_SRC

Define custom function used to output header of parent and preview windows. Must
return a string that is placed in the header-line.

#+BEGIN_SRC elisp
  (setq ranger-parent-header-func 'ranger-parent-header-line)
#+END_SRC

** Parent options
You can set the number of folders to nest to the left, adjusted by =z-= and =z+=

#+BEGIN_SRC elisp
  (setq ranger-parent-depth 2)
#+END_SRC

You can set the size of the parent windows as a fraction of the frame size

#+BEGIN_SRC elisp
  (setq ranger-width-parents 0.12)
#+END_SRC

When increasing number of nested parent folders, set max width as fraction of
frame size to prevent filling up entire frame with parents.

#+BEGIN_SRC elisp
  (setq ranger-max-parent-width 0.12)
#+END_SRC

** Preview options
You can choose to show previews literally, or through find-file, toggled by =zi=

#+BEGIN_SRC elisp
  (setq ranger-show-literal t)
#+END_SRC

You can set the size of the preview windows as a fraction of the frame size

#+BEGIN_SRC elisp
  (setq ranger-width-preview 0.55)
#+END_SRC

You probably don't want to open certain files like videos when using preview. To
ignore certain files when moving over them you can customize the following to
your liking:

#+BEGIN_SRC elisp
  (setq ranger-ignored-extensions '("mkv" "iso" "mp4"))
#+END_SRC

To set the max files size (in MB), set the following parameter:

#+BEGIN_SRC elisp
  (setq ranger-max-preview-size 10)
#+END_SRC

* Key bindings

| Key binding     | Description                                          |
|-----------------+------------------------------------------------------|
| ~SPC a t r r~   | launch ranger                                        |
| ~SPC a t r d~   | deer (minimal ranger window in current directory)    |
| ~C-p~           | (ranger) toggle ranger in dired buffer               |
| ~j~             | (ranger) navigate down                               |
| ~k~             | (ranger) navigate up                                 |
| ~yy~            | (ranger) copy                                        |
| ~pp~            | (ranger) paste                                       |
| ~R~             | (ranger) rename                                      |
| ~D~             | (ranger) delete                                      |
| ~C-j~           | (ranger) scroll preview window down                  |
| ~C-k~           | (ranger) scroll preview window up                    |
| ~f~             | (ranger) search for file names                       |
| ~i~             | (ranger) show preview of current file                |
| ~zi~            | (ranger) toggle showing literal / full-text previews |
| ~zh~            | (ranger) toggle showing dotfiles                     |
| ~o~             | (ranger) sort options                                |
| ~H~             | (ranger) search through history                      |
| ~h~             | (ranger) go up directory                             |
| ~l~             | (ranger) find file / enter directory                 |
| ~RET~           | (ranger) find file / enter directory                 |
| ~q~             | (ranger) quit                                        |
| ~;g~            | (ranger) revert buffer                               |
| ~z-~            | (ranger) reduce number of parents                    |
| ~z+~            | (ranger) increment number of parents                 |
| ~C-SPC~ / ~TAB~ | (ranger) mark current file                           |
| ~v~             | (ranger) toggle all marks                            |
| ~t~             | (ranger) toggle mark current file                    |
| ~S~             | (ranger) enter shell                                 |
| ~;C~            | (ranger) copy directory / copy and move directory    |
| ~;+~            | (ranger) create directory                            |