Repository files navigation

Leverage the power of Vim's compiler plugins without being bound bysynchronicity. Kick off builds and test suites using one of severalasynchronous adapters (including tmux, screen, iTerm, Windows, and a headlessmode), and when the job completes, errors will be loaded and parsedautomatically.

If that doesn't excite you, then perhapsthis video will change yourmind.

Install using your favorite package manager, or use Vim's built-in packagesupport:

mkdir -p ~/.vim/pack/tpope/startcd ~/.vim/pack/tpope/startgit clone https://tpope.io/vim/dispatch.gitvim -u NONE -c "helptags dispatch/doc" -c q

The core of Vim's compiler system is:make, a command similar to:grepthat runs a build tool and parses the resulting errors. The default buildtool is of coursemake, but you can switch it (and the associated errorparser) with:compiler. There are lots of built-in compilers, and they domore than just compile things. Plus you can make your own.

We'll start by looking at dispatch.vim's:make wrapper:Make, and thenmove on to higher abstractions.

Kick off quick tasks with:Make. What happens next depends on which adaptertakes charge.

• If you're in tmux, a small split will be opened at the bottom.
• On Windows, a minimized cmd.exe window is spawned.
• Otherwise, you get a plain old:make invocation.

When the task completes, the window closes, the errors are loaded and parsed,and the quickfix window automatically opens. At no point will your focus bestolen.

Use:Make! for longer running tasks, like "run the entire test suite".

• If you're in tmux or GNU screen, a new window is created in the background.
• Windows still spawns a minimized cmd.exe window.
• Otherwise, you get a headless invocation. You can't see it, but it'srunning in the background.

You won't be interrupted with a quickfix window for a background build.Instead, open it at your leisure with:Copen.

You can also use:Copen on a build that's still running to retrieve andparse any errors that have already happened.

As hinted earlier, it's easy to switch compilers.

:compiler rubyunit:make test/models/user_test.rb

Wait, that's still twice as many commands as it needs to be. Plus, itrequires you to make the leap fromtestrb (the executable) torubyunit(the compiler plugin). The:Dispatch command looks for a compiler for anexecutable and sets it up automatically.

:Dispatch testrb test/models/user_test.rb

If no compiler plugin is found,:Dispatch simply captures all output.

:Dispatch bundle install

As with:make, you can use% expansions for the current filename.

:Dispatch rspec %

The:Dispatch command switches the compiler back afterwards, so you can picka primary compiler for:Make, and use:Dispatch for secondary concerns.

With no arguments,:Dispatch looks for ab:dispatch variable. Youcan set it interactively, or in an autocommand:

autocmd FileType java let b:dispatch = 'javac %'

If nob:dispatch is found, it falls back to:Make.

:Dispatch makes a great map. By default dispatch.vim provides `<CR> for:Dispatch<CR>. You can find all default maps under:h dispatch-maps.

Use:FocusDispatch (or just:Focus) to temporarily, globally override thedefault dispatch:

:Focus rake spec:models

Now every bare call to:Dispatch will call:Dispatch rake spec:models.You'll be getting a lot of mileage out of that:Dispatch map.

Use:Focus! to reset back to the default.

Sometimes you just want to kick off a process without any output capturing orerror parsing. That's what:Start is for:

:Start lein repl

Unlike:Make, the new window will be in focus, since the idea is that youwant to interact with it. Use:Start! to launch it in the background.

Using dispatch.vim from a plugin is a simple matter of checking for and using:Make and:Start if they're available instead of:make and:!. Yourfavorite plugin already supports it, assuming your favorite plugin israils.vim.

How can I have:Dispatch! or:Make! open the quickfix window oncompletion?

Use:Dispatch or:Make. The entire point of the! is to run in thebackground without interrupting you.

But that blocks Vim.

Then the adapter in use doesn't support foreground builds. Adjust your setup.

Like dispatch.vim? Follow the repository onGitHub and vote for it onvim.org. And ifyou're feeling especially charitable, followtpope onTwitter andGitHub.

Copyright © Tim Pope. Distributed under the same terms as Vim itself.See:help license.