*dispatch.txt* Asynchronous build and test dispatcher
Author: Tim Pope <http://tpo.pe/>
Repo: https://github.com/tpope/vim-dispatch
License: Same terms as Vim itself (see |license|)
INTRODUCTION *dispatch*
Leverage the power of Vim's compiler system without being constrained by
synchronicity.
COMMANDS *dispatch-commands*
*dispatch-:Make*
:Make [arguments] Using the current |:compiler| settings, dispatch a
build in the foreground. Adapter strategies vary, but
the goal is visibility without stealing focus. When
the build is complete, load the results into the
|quickfix| list and call |:cwindow|. This command is
preferred for shorter tasks like "build this file."
:Make! [arguments] Using the current compiler settings, dispatch a build
in the background. Use |:Copen| to load the results.
This command is preferred for longer tasks like "run
the entire test suite."
*dispatch-:Copen*
:Copen Load the latest build into the quickfix list and open
it with |:copen|. You may call this before the
process is finished.
:Copen! Load the latest build into the quickfix list using a
catch-all parser. This is useful when you can't tell
what went wrong.
*dispatch-:Dispatch*
:Dispatch[!] [options] {program} [arguments]
Find a compiler plugin that sets 'makeprg' to
{program} and use its 'errorformat' to dispatch a
|:Make| for the given {program} and [arguments]. If
no compiler plugin is found, the generic format
%+I%.%# is used.
:Dispatch picks a compiler by looking for either
CompilerSet makeprg={program}\ [arguments] or
CompilerSet makeprg={program} in compiler plugins.
To force a given {program} to use a given {compiler},
create ~/.vim/after/compiler/{compiler}.vim and add to
it a line like the following: >
" CompilerSet makeprg={program}
<
If you need more control, *g:dispatch_compilers* can
be set to a dictionary with commands for keys and
compiler plugins for values. Use an empty value to
skip the matched string and try again with the rest of
the command.
>
let g:dispatch_compilers = {
\ 'latex': 'tex',
\ 'bundle exec': ''}
<
You can optionally give one or more of the following
options before {program}:
-compiler=... force use of a compiler plugin
-dir=... run command in given directory
:Dispatch[!] [options] -- [arguments]
This is equivalent to |:Make| but accepts options.
*b:dispatch*
:Dispatch[!] [options] Invoke |:Dispatch| with the options, program, and
arguments found in b:dispatch. In the quickfix
window, this reruns the shown dispatch. When no other
default is found, equivalent to |:Make|.
*dispatch-:FocusDispatch*
:FocusDispatch [options] {program} [arguments]
Set a global default command for |:Dispatch| with no
arguments. Overrides |b:dispatch|.
:FocusDispatch! [options] {program} [arguments]
Set a window local default command for |:Dispatch|
with no arguments. Overrides |b:dispatch| and the
global default.
:FocusDispatch! Clear the global and window local defaults for
|:Dispatch|.
:FocusDispatch Show the task that would run when calling |:Dispatch|
with no arguments.
:0Dispatch[!] [options] Provide a range to |:Dispatch| skips any focused task
and forces |b:dispatch|.
*dispatch-:AbortDispatch*
:AbortDispatch Abort the most recent build.
:AbortDispatch {command}
Abort the most recent build of {command}.
*dispatch-:Start*
:Start [options] {command}
Start a process in a new, focused window. If
{command} and the directory for execution match a
previous :Start invocation, focus it instead, if
possible. Options:
-dir=... run command in given directory
-title=... short label for supported adapters
-wait=... when to display press enter prompt:
"always", "never", or "error"
:Start! [options] {command}
Start a process in a new, unfocused window. If
{command} and the current working directory match
previous :Start invocation, do nothing.
*b:start*
:Start[!] [options] With no arguments, |:Start| the options and command
given by |b:start|. If not set, falls back to
'shell'.
*dispatch-:Spawn*
:Spawn[!] [options] [command]
Like |:Start|, but always spawn a new process rather
than focusing an existing one. The default is always
to spawn a new 'shell'.
:0Spawn! [options]
Provide a range to |:Spawn| to spawn |b:dispatch|.
Handy for using an interactive debugger.
MAPS *dispatch-maps*
The following convenience maps are provided.
*m<CR>* |:Make|<CR>
*m<Space>* |:Make|<Space>
*m!* |:Make|!
*m?* Show 'makeprg'
*`<CR>* |:Dispatch|<CR>
*`<Space>* |:Dispatch|<Space>
*`!* |:Dispatch|!
*`?* |:FocusDispatch|<CR>
*'<CR>* |:Start|<CR>
*'<Space>* |:Start|<Space>
*'!* |:Start|!
*'?* Show |b:start|
*g'<CR>* |:Spawn|<CR>
*g'<Space>* |:Spawn|<Space>
*g'!* |:Spawn|!
*g'?* Show 'shell'
These can be disabled with
>
let g:dispatch_no_maps = 1
<
STRATEGIES *dispatch-strategies*
Strategies are listed in order of precedence. The first available one is
used. Some strategies only provide for a subset of tasks.
Disable :Make/:Dispatch or :Start/:Spawn using a given strategy by assigning
g:dispatch_no_strategyname_make or g:dispatch_no_strategyname_start,
respectively. For example, to prevent :Dispatch from ever using the Job
handler:
>
let g:dispatch_no_job_make = 1
<
Except for Tmux, which uses |VimResized|, all strategies require either |job|
support plus a file system with FIFOs (basically everything but Windows) or
|clientserver| support to do foreground makes.
Tmux ~
Foreground makes open in a small split at the bottom. The closure of the
pane triggers a |VimResized| event which loads the results into the quickfix
list.
The tmux strategy can be used from the GUI as well. Either start Vim from
inside of tmux or assign g:tmux_session. This will use a new window for
foreground makes rather than a split.
Job ~
Uses the |job| support in Vim 8 and Neovim to update the quickfix list in real
time.
GNU Screen ~
A new window is always used, since splits in GNU Screen are awkward.
Terminal ~
Uses the respective |:terminal| features of Vim and Neovim.
Windows ~
You can use either the standard cmd.exe or a cygwin shell. Both foreground
and background |:Make| invocations are started minimized to prevent focus
stealing.
iTerm ~
This strategy fires if you're in MacVim with at least one iTerm window open,
or if Vim is running in iTerm itself. Used only for |:Start|.
X11 ~
Uses g:dispatch_terminal_exec, "$TERMINAL -e", or "xterm -e". Used only for
|:Start|. Background invocations require wmctrl to be is installed (which is
used to switch the focus back to Vim).
Headless ~
Forks tasks into the background. It's working, you just can't see it. Don't
forget to check |:Copen|. The presence of this strategy means that |:Make!|
and |:Start!| will never block Vim.
Synchronous ~
When all else fails, a vanilla |:make| or |:!| is performed.
vim:tw=78:et:ft=help:norl: