sponsor Vim development Vim logo go to HTTPS page Vim Book Ad

asyncrun : Run Async Shell Commands in Vim 8.0 and Output to Quickfix in Realtime

 script karma  Rating 239/74, Downloaded by 703    Comments, bugs, improvements  Vim wiki

created by
Wei Lin
script type
Maintainer: skywind3000 (at) gmail.com
Homepage: https://github.com/skywind3000/asyncrun.vim

Run shell commands in background and output to quickfix:
    :AsyncRun[!] [options] {cmd} ...

    when "!" is included, auto-scroll in quickfix will be disabled
    parameters are splited by space, if a parameter contains space,
    it should be escaped as backslash + space (just like ex commands)

Parameters will be expanded if they start with '%', '#' or '<' :
    %:p     - File name of current buffer with full path
    %:t     - File name of current buffer without path
    %:p:h   - File path of current buffer without file name
    %:e     - File extension of current buffer
    %:t:r   - File name of current buffer without path and extension
    %       - File name relativize to current directory
    %:h:.   - File path relativize to current directory
    <cwd>   - Current directory
    <cword> - Current word under cursor
    <cfile> - Current file name under cursor

Environment variables are set before executing:
    $VIM_FILEPATH  - File name of current buffer with full path
    $VIM_FILENAME  - File name of current buffer without path
    $VIM_FILEDIR   - Full path of current buffer without the file name
    $VIM_FILEEXT   - File extension of current buffer
    $VIM_FILENOEXT - File name of current buffer without path and extension
    $VIM_CWD       - Current directory
    $VIM_RELDIR    - File path relativize to current directory
    $VIM_RELNAME   - File name relativize to current directory
    $VIM_CWORD     - Current word under cursor
    $VIM_CFILE     - Current filename under cursor
    $VIM_GUI       - Is running under gui ?
    $VIM_VERSION   - Value of v:version
    $VIM_COLUMNS   - How many columns in vim's screen
    $VIM_LINES     - How many lines in vim's screen

    parameters also accept these environment variables wrapped by
    "$(...)", and "$(VIM_FILEDIR)" will be expanded as file directory

There can be some options before [cmd]:
    -mode=0/1/2  - start mode: 0(async,default), 1(makeprg), 2(!)
    -cwd=?       - initial directory, (use current directory if unset)
    -save=0/1    - non-zero to save unsaved files before executing
    -program=?   - set to 'make' to use '&makeprg'
    -post=?   - vimscript to exec after this job finished, spaces **must** be escaped to '\ '

    All options must start with a minus and position **before** `[cmd]`.
    Since no shell command starts with a minus. So they can be
    distinguished from shell command easily without any ambiguity.

Stop the running job by signal TERM:

    when "!" is included, job will be stopped by signal KILL

    g:asyncrun_exit - script will be executed after finished
    g:asyncrun_bell - non-zero to ring a bell after finished (notify you job finished)
    g:asyncrun_mode - 0:async(if support) 1:sync 2:shell
    g:asyncrun_encs - shell program output encoding

    g:asyncrun_code - exit code
    g:asyncrun_status - 'running', 'success' or 'failure'

    minimal vim version is 7.4.1829 to support async jobs.
    neovim 0.1.4 or later is supported too.
    recommand to use vim 8.0 or above.

    AsyncRun uses quickfix window to show job outputs, in order to see the outputs in realtime,
    you need open quickfix window at first by using :copen (see :help copen). And there is a
    function 'asyncrun#quickfix_toggle(size)' for you to open/close it rapidly (see tutorial 9).

Tutorial 0: async run gcc / make to build current file
    :AsyncRun gcc % -o %<
    :AsyncRun g++ -O3 "%" -o "%<" -lpthread
    :AsyncRun make -f Mymakefile

Tutorial 1: async grep key word
    :AsyncRun! grep -R word .
    :AsyncRun! grep -R <cword> .

Tutorial 2: look up man page
    :AsyncRun! man -S 3:2:1 <cword>

Tutorial 3: build go project
    :AsyncRun go build "%:p:h"

Tutorial 4: use <F7> to compile current file
    :noremap <F7> :AsyncRun gcc "%" -o "%<" <cr>

Tutorial 5: open quickfix window (see the output)
    :botright copen 8

Tutorial 6: async git push
    :AsyncRun git push origin master

Tutorial 7: compile markdown to pdf
    :AsyncRun pandoc --output "$(VIM_FILENOEXT).pdf" "%:p" <CR>

Tutorial 8: update tags in background while editing (super useful for large projects):
    :AsyncRun ctags -R --fields=+S .
    :AsyncRun ctags -R -f $(VIM_FILEDIR)/ctags.out --fields=+iaS $(VIM_FILEDIR)

Tutorial 9: a help function to toggle quickfix window in an efficient way (F9 to toggle):
    :noremap <F9> :call asyncrun#quickfix_toggle(8)<cr>

Please vote it if you like it.
install details
Copy asyncrun.vim to your ~/.vim/plugin or use Vundle to install it from skywind3000/asyncrun.vim .

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
asyncrun.vim 1.3.11 2017-05-19 7.4 Wei Lin New option (-save=2) to save all modified buffers before executing.
asyncrun.vim 1.3.10 2017-05-04 7.4 Wei Lin remove trailing ^M in NeoVim 2.0 on Windows
asyncrun.vim 1.3.9 2016-12-23 7.4 Wei Lin Minor bugs fixed, compatibility and performance improvement.
asyncrun.vim 1.3.8 2016-11-17 7.4 Wei Lin 1. fixed conflict between caddexpr and command line window.
2. add autocmd AsyncRunPre, AsyncRunStart and AsyncRunStop.
asyncrun.vim 1.3.7 2016-11-13 7.4 Wei Lin 1. fixed issues in channel reading and arguments parsing
2. flow control to prevent gui freeze by massive output
asyncrun.vim 1.3.6 2016-11-07 7.4 Wei Lin improve performance by add some noautocmd, fixed small issue in bell ringing. improve event hooking
asyncrun.vim 1.3.5 2016-11-02 7.4 Wei Lin new option "g:asyncrun_auto" and "-auto=?" to trigger QuickFixCmdPre and QuickFixCmdPost. and can cooperate with errormaker.vim now
asyncrun.vim 1.3.3 2016-10-27 7.4 Wei Lin 1. new option "g:asyncrun_local" to use local value of errorformat rather the global value.
2. prevent job who reads from stdin getting hanging by setting in_io to null.
3. fixed an issue in fast exiting programs
asyncrun.vim 1.3.2 2016-10-19 7.4 Wei Lin 1. fixed few issues of arguments passing in different modes
2. new "-post" option to run a vimscript after the job finished
asyncrun.vim 1.3.0 2016-10-17 7.4 Wei Lin improve CJK encoding conversion in quickfix window for background commands
asyncrun.vim 0.0.0 2016-08-24 7.4 Wei Lin Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
SourceForge.net Logo