Ranger

ranger is a console file manager with vi key bindings. It provides a minimalist and nice curses interface with a view on the directory hierarchy.

kakoune ships with a handy ranger command that opens a ranger instance in a tmux pane on the right. Selecting a file in this explorer loads its content in the kakoune on the left pane and let the ranger instance running.

This usage works well when only one kakoune client is running but becomes cumbersome when multiple kakoune clients are displayed in tmux panes forming a complex layout. The problem is well described in this vimcast post : Oil and vinegar - split windows and the project drawer

Workflow example

Here's an alternative way of using kakoune, ranger and tmux together:

• two kakoune clients connected to the same session are displayed side by side in tmux panes.
• you want to edit a file in the right one. Following the vinegar philosophy, ranger should cover the whole right pane while choosing the file.
• press <ctrl-z> to suspend the right kakoune client and get back to the shell.
• launch ranger with ranger --choosefiles=/tmp/ranger-files, this way when you select a file in ranger, it will write its path in /tmp/ranger-files and close ranger.
• unsuspend kakoune with fg
• use the edit command to edit the filename written in /tmp/ranger-files.

To ease this workflow, you may need helpers:

A shell alias to launch ranger with the correct option:

# use <space> in ranger to select multiple files
alias rr='ranger --choosefiles=/tmp/ranger-files'

A kakoune command to automatically edit the filenames previously chosen by ranger:

# /tmp/ranger-files is populated by ranger --choosefiles
def ranger -docstring 'Open files previously chosen by ranger' %{ %sh{
  while read f; do
    echo "edit $f;"
  done < '/tmp/ranger-files'
}}
map global user r :ranger<ret>

Also you may encounter jobs control issues by opening tmux panes with the kakoune new command. For instance you may have difficulties using <ctrl-z> in the newly created pane. To circumvent this problem, use your normal tmux shortcut to open this new pane and run a kakoune instance connected to the same session as the previous pane. This session workflow is described in this bin stub.

Callback command after kakoune process unsuspension

To reduce typing even more in this workflow, you can use the following kakoune command:

def suspend -params 1 %{ %sh{
  /usr/bin/kill -SIGTSTP $PPID
  echo "$1"
}}

You can use it this way in kakoune command line: :suspend ranger (and of course map it to a key for quick access like map global user z ':suspend ranger')

What it does, is the same as manually typing <ctrl-z> (the first line), getting you back on your shell. You then start ranger with rr and select the files you need. The magic happens when you type fg to return to the suspended kakoune. It will execute the kakoune command passed as an argument as :suspend (line 2), which is :ranger in our case. So here, it will automatically edit the files we have chosen.

Bonus: If you don't want to type rr yourself after each suspend and fg to come back, you can let xdotool do the job, with this alternative version:

def suspend -params 2 %{ %sh{
  nohup sh -c "sleep 0.2; xdotool type '$1'; xdotool key Return" > /dev/null 2>&1 &
  /usr/bin/kill -SIGTSTP $PPID
  echo "$2"
}}

map global user r ':suspend "ranger --choosefiles=/tmp/ranger-files &&fg;history -d $(history 1)" ranger<ret>'