Customize Runner

AsyncRun allows you to define new runners to specify how to run your command. It can be useful when you want your commands run in a tmux split, a new gnome-terminal window, or a floaterm window.

Create a New Runner

A runner is a function with one argument opts as a dictionary, from which stores the command string, working directory, and other parameters passed with :AsyncRun command. All the runners are required to register in g:asyncrun_runner so that AsyncRun can recognize them.

function! s:my_runner(opts)
    echo "run: " . a:opts.cmd
endfunction

let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.test = function('s:my_runner')

Than use:

:AsyncRun -mode=term -pos=test ls -la $(VIM_FILEDIR)

When -mode=term and -pos=test are provided, runner test will be called. In this example, runner function s:my_runner does nothing but display the command in the bottom of your vim.

Get Information

There is a opts argument in the runner function, which contains necessary information:

Field	Description	Example
cmd	Command string (macros have already been expanded here)	ls -la
cwd	Working directory (will be an empty string if not provided)	/home/yourname/github
mode	Running mode	async, terminal/term, or vim
pos	Runner name or terminal position	TAB, gnome, tmux, ...
option	Runner option passed by :AsyncRun -option=xxx ...	...
close	Close terminal after job finished	-close=1
post	A vim script needs to be executed after finished	-post=echo\ "done" ls -la
program	Command modifier	-program=grep

If -cwd=xxx is provided after :AsyncRun command, AsyncRun will temporarily change the current working directory to the target position when calling runner function. So, you can either pick the value in a:opts.cwd or use the return value from getcwd() .

Real Example: tmux

It is very easy to make the command run in a tmux pane with vimux:

function! s:run_tmux(opts)
    " asyncrun has temporarily changed working directory for you
    " getcwd() in the runner function is the target directory defined in `-cwd=xxx`  
    let cwd = getcwd()   
    call VimuxRunCommand('cd ' . shellescape(cwd) . '; ' . a:opts.cmd)
endfunction

let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.tmux = function('s:run_tmux')

And you are able to use:

:AsyncRun -mode=term -pos=tmux ls -la

screenshot:

You can specify pane position (vertical or horizontal) and size, just check vimux's doc.