#Vimax

An ax for maximum tmux and vim control... or something

##Vimux Based Functionality

This plugin is largely based on Vimux and is enhanced to allow a finer grain of control over sending commands and text to multiple tmux panes and windows. Primarily, all functions and commands now accept a count or argument to specify a target tmux pane, placing an entire tmux session (or sessions) at your fingertips. Vimax also provides a GUI for listing and executing historical commands and listing available panes to help navigate.

##Usage

Vimax works by accepting an 'address' for functions which help to send commands to tmux. An address is a combination of session, window, and pane, all of which are optional. If no address is given, the last targeted address is used for that command, or, if no previous address is given, a prompt will ask for a specified pane. If just a pane is specified, then the current session and window are used, and so on. This will be clearer with the examples given below, but it essentially allows sending commands to tmux panes and windows with great ease.

####Mappings

Vimax provides easy mappings which accept up to three, one digit numbers to specify session, window and pane. For instance, lets say VimaxPromptCommand is mapped to <leader>vp. VimaxPromptCommand prompts for user input of any command and then executes it in the specified target address. Pressing 2<leader>vp will ask for a command that will be executed in pane 2 of the current window, and 132<leader>vp will select session 1, window 3 and pane 2. Just <leader>vp will use the last targeted address. Here is a full example mapping:

nmap <leader>va <Plug>VimaxList
nmap <leader>vc <Plug>VimaxClearAddressHistory
nmap <leader>vd <Plug>VimaxRunCommandInDir
nmap <leader>vg <Plug>VimaxGoToAddress
nmap <leader>vh <Plug>VimaxHistory
nmap <leader>vi <Plug>VimaxInspectAddress
nmap <leader>vj <Plug>VimaxScrollDownInspect
nmap <leader>vk <Plug>VimaxScrollUpInspect
nmap <leader>vl <Plug>VimaxRunLastCommand
nmap <leader>v<CR> <Plug>VimaxExitInspect
nmap <leader>vp <Plug>VimaxPromptCommand
nmap <leader>vq <Plug>VimaxCloseAddress
nmap <leader>vr <Plug>VimaxRunCommandAtGitRoot
nmap <leader>vss <Plug>VimaxMotionCurrentLine
nmap <leader>vs <Plug>VimaxMotion
vmap <leader>vs <Plug>VimaxMotion
nmap <leader>vx <Plug>VimaxInterruptAddress
nmap <leader>vz <Plug>VimaxZoomAddress

The <leader>va might be a bit of a stretch for VimaxList, with 'a' for addresses

####Commands

Vimax commands accept an address in the format session:window.pane. Commands are useful for specifying named windows, like repl.1 to select the 1 pane of a window named 'repl' in this session, or a window/pane out of the single digits, like 0:12.1. All vimax mappings are provided as commands and look like this:

:VimaxGoToAddress repl.1

followed by the return key. Commands which accept an argument take those arguments first and the address last. Like:

:VimaxRunCommand print("Hello,\ World") repl.1

Note that you need to escape the space here while the function

:call vimax#RunCommand('print("Hello, World")', 'repl.1')

works as expected with quoted values.

####Functions

You can also call vimax functions directly with either numbers or string values for addresses, like

:call vimax#GoToAddress(1.1)
:call vimax#GoToAddress('zsh.1')

This is useful if you want to hack something like support for your favorite test suite.

####Interactive Buffers

Vimax provides interactive buffers for listing windows and listing command line history. The interactive elements rely on fzf

VimaxList will provide a buffer with the list of panes available and allow fuzzy searching to select an address which will be used as the default in the next command. If mapped to <leader>va, then hit that key combo, start typing a few letters of the process you are targeting or a few numbers of the address and hit enter.

VimaxHistory will provide a buffer of recent command line history and allow fuzzy searching to select a command for execution. If mapped to <leader>vh then hit that combination, start typing something from the recent history, say 'npm run' and hit enter. VimaxHistory accepts a count and will execute the selected command at that address, so 2<leader>vh followed by npm run and enter will run the most recent command containing npm run in pane 2 of the current window. VimaxHistory also adds functionality for changing target addresses and for executing a command at an address while remaining in the gui menu. These are bound to ctrl-t and ctrl-e by default, but can be configured via a global variable. More on that below in 'Configuration'.

Pressing ctrl-t will bring up VimaxList and allow selecting an address in which the command will be executed. Here's an example: I press 2<leader>vh assuming I want to execute something from the history in pane 2. I then change my mind and want to execute in pane 3 instead, so I hit ctrl-t, select pane 3 from the gui list, and hit enter to return to the history selection menu.

Pressing ctrl-e will execute the command under the cursor after pulling up the VimaxList gui to select an address and return to the history menu after the command begins executing.

##Installation

Installing Vimax is easy with any plugin manager. For instance, with Vundle, just put

Bundle 'low-ghost/vimax'

in your vimrc, run :source ~/.vimrc and run :BundleInstall. With vim-plug, just

Plug 'low-ghost/vimax'

and run :PlugInstall.

####Optional Dependencies

Vimax has a few commands and mappings which provide an interactive buffer to help navigate panes and select commands from history. To get this full functionality, install fzf. To install fzf, follow the instructions listed on the fzf github page by cloning and running the install script:

git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

Then either put this in your vimrc:

set rtp+=~/.fzf

Or, if you're using vim-plug:

Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all'  }

And you're good to go (no fzf.vim required, though it might be up your ally)

##Configuration

Besides allowing (well requiring) custom mappings, Vimax allows several points of configuration through global variables. Here is a complete list and description of these variables:

g:VimaxFuzzyBuffer

description

dependency for interactive buffer and is either 'fzf', or none

default

fzf

g:VimaxHistoryBindings

description

Key bindings for History GUI buffer. To override defaults, you will have to put

let g:VimaxHistoryBindings = {
\ 'edit': 'w'
\ }

in your vimrc and the other defaults will merge in. run_at_address and edit will have matching alt bindings to allow picking a different address from the one invoked with history.

default

{
  'change_target': 'a',
  'run_at_address': 'r',
  'edit': 'e',
  'help': 'h',
}

g:VimaxHistoryFile

description

location of shell history file. Should be accessable with $HISTFILE, but inconcistencies in tmux/bash environments make this dificult. Change to $HOME.'/.zsh_history' or $HOME.'./.zhistory' for zsh.

default

$HOME.'/.bash_history'

g:VimaxLimitHistory

description

number of commands pulled from the history file. Can be pretty large with fzf without worry. If it seems slow, try limiting this number

default

1000

g:VimaxPromptString

description

string presented when prompting for a command

default

'Command? '

g:VimaxResetSequence

description

sequence of keys sent to Tmux to exit copy-mode

default

'q C-u'

g:VimaxLastCommandDict

description

command dictionary with Tmux addresses as keys, string commands as props. Available if you'd want to prefill values, but probably not that useful

default

{}

g:VimaxOrientation

description

vimax#RunCommandInDir creates a new pane in either a vertical or horizontal split, specified by setting g:VimaxOrientation to 'v' or 'h'

default

'h'

g:VimaxSize

description

size of vimax#RunCommandInDir pane in lines

default

10

g:VimaxLastAddress

description

Used as default address for next command. Can set manually if the need arises

default

None. If no address is present, Vimax will prompt for one

####Tmux Specific Config (Go Back to Vim and Pane Numbering)

Vimax adds functionality to return to the last vim address via a key combination. Here's a sample mapping to

bind C-o run "tmux showenv | grep VimaxLastVimAddress | sed -ne 's/VimaxLastVimAddress=\\([[:digit:]]\\).\\([[:digit:]]\\)/tmux select-window -t \\1; tmux select-pane -t \\2/p' | xargs -I % bash -c % bash"

There is probably a better way of doing all that (probably with grep -o and tmux execution of the final command). Let me know if you discover something.

You may also want:

set -g base-index 1
set-window-option -g pane-base-index 1

So that all indexes start at 1 and the address of the base window/pane is 1.1. Helpful in that it prevents frequently having to reach for the 0.

Put these in your ~/.tmux.conf file and type

<prefix>: source-file ~/.tmux.conf

to enable. All examples will assume this configuration.

<prefix>q might also be useful, it shows the pane numbers in the current window

#TODO

• docs
• example gif
• run in dir is actually useful. Recommend Dispatch to perform these kinds of actions
• finish and integrate sending keys by region/range
• fzf support based on global variable
• potential: additional bindings for list and history.
• Tmux specific actions like rename window, bring pane into current window, break from current window, close pane (with prompt)
• Multiline historical entries