Preface

This plugin takes the advantage of new APIs in Vim 8 (and NeoVim) to enable you to run shell commands in the background and read the output in the quickfix window in realtime:

• Easy to use, start your background command by :AsyncRun (just like old ! cmd).
• The command is running in the background, no need to wait for the entire process to finish.
• Output is displayed in the quickfix window, errors are matched with errorformat.
• You can explore the error output immediately or keep working in vim while executing.
• Ring the bell or play a sound to notify your job is finished while you're focusing on editing.
• Customizable runners and command modifiers bring you the dark power of asyncrun.
• Fast and lightweight, just a single self-contained asyncrun.vim source file.
• Provide corresponding user experience in vim, neovim, gvim, and macvim.

If that doesn't excite you, then perhaps this GIF screen capture below will change your mind.

【README in Chinese | 中文文档】

News

• 2021/12/15 new extra runners to run command in a tmux, or floaterm window.
• 2020/02/18 asynctasks uses asyncrun to introduce vscode's task system to vim.
• 2020/01/21 run command in internal terminal with -mode=term see here.
• 2020/04/17 AsyncRun now supports command range, try: :%AsyncRun cat.

Install

Install with vim-plug:

Plug 'skywind3000/asyncrun.vim'

Example

Remember to open vim's quickfix window by :copen (or setting g:asyncrun_open) before invoking AsyncRun, otherwise, you will not see any output.

Contents

<!-- TOC -->

• Preface
• News
• Install
• Example
• Contents
  • Tutorials
  • Manual
    • AsyncRun - Run shell command
    • AsyncStop - Stop the running job
    • Function (API)
    • Settings
    • Variables
    • Autocmd
    • Project Root
    • Running Modes
    • Internal Terminal
    • Terminal Name
    • Quickfix window
    • Range support
  • Advanced Topics
    • Extra Runners
    • Customize Runner
    • Command Modifier
    • Requirements
    • Cooperate with vim-fugitive:
  • Language Tips
  • More Topics
  • Cooperate with other Plugins
• History
• Credits

<!-- /TOC -->

Tutorials

Async run gcc to compile current file

:AsyncRun gcc "$(VIM_FILEPATH)" -o "$(VIM_FILEDIR)/$(VIM_FILENOEXT)"
:AsyncRun g++ -O3 "$(VIM_FILEPATH)" -o "$(VIM_FILEDIR)/$(VIM_FILENOEXT)" -lpthread 

This command will run gcc in the background and output to the quickfix window in real time. Macro '$(VIM_FILEPATH)' stands for filename with full path and '$(VIM_FILENOEXT)' represents filename without extension.

Async run make

:AsyncRun make
:AsyncRun make -f makefile

Remember to open the quickfix window by :copen before using the AsyncRun command, if you don't open it, you will not see any output.

Grep key word

:AsyncRun! grep -R -n word . 
:AsyncRun! grep -R -n <cword> . 

when ! is included, auto-scroll in quickfix will be disabled. <cword> represents current word under cursor.

Compile go project

:AsyncRun go build "$(VIM_FILEDIR)"

Macro '$(VIM_FILEDIR)' stands for the current file dir.

Lookup man page

:AsyncRun! man -S 3:2:1 <cword>

Git push

:AsyncRun git push origin master

Git push from project root

:AsyncRun -cwd=<root> git push origin master

Use -cwd=? to specify the working directory, macro <root> or $(VIM_ROOT) represents current Project Root.

Setup <F7> to compile file

:noremap <F7> :AsyncRun gcc "$(VIM_FILEPATH)" -o "$(VIM_FILEDIR)/$(VIM_FILENAME)" <cr> 

File name may contain spaces, therefore, it's safe to quote them.

Run a python script

:AsyncRun -cwd=$(VIM_FILEDIR) python "$(VIM_FILEPATH)"

New option -raw will display the raw output (without matching to errorformat). Remember to put let $PYTHONUNBUFFERED=1 in your .vimrc to disable python stdout buffering, see here.

Run a python script in a new terminal

:AsyncRun -cwd=$(VIM_FILEDIR) -mode=term -pos=TAB  python "$(VIM_FILEPATH)"

This will run python in the internal-terminal (vim 8.2 or nvim-0.4.0 is required) in a new tabpage.

A good assistant to asyncrun

asynctasks.vim a plugin built upon asyncrun, an easy way to use asyncrun. It allows you to manage your building, testing, and deploying tasks in a global or project local configuration, and run them by their names.

Manual

There are two vim commands: :AsyncRun and :AsyncStop to control async jobs.

AsyncRun - Run shell command

:AsyncRun[!] [options] {cmd} ...

Run shell command in the background and output to quickfix. when ! is included, auto-scroll in quickfix will be disabled. Parameters are split by space, if a parameter contains space, it should be quoted or escaped as backslash + space (Unix only).

Macro variables in the parameters will be expanded 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_PATHNOEXT) - Current file name with full path but without extension
$(VIM_CWD)       - Current directory
$(VIM_RELDIR)    - File path relativize to current directory
$(VIM_RELNAME)   - File name relativize to current directory 
$(VIM_ROOT)      - Project root 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
$(VIM_SVRNAME)   - Value of v:servername for +clientserver usage
$(VIM_PRONAME)   - Name of current project root directory
$(VIM_DIRNAME)   - Name of current directory

Environment variables with same name, like $VIM_FILENAME, are also initialized. Thus your child process can access them with getenv(xxx) at any time.

Some macros variables have their short names starting with '<' :

<cwd>   - Current directory
<cword> - Current word under cursor
<cfile> - Current file name under cursor
<root>  - Project root directory

They are also acceptable. So, you can use both $(VIM_ROOT) or its alias <root> to represent Project Root of the current file. Macro variables can be quoted with "..." in the command string when file name contains spaces (like normal shell command escaping), but they should not be quoted in the -cwd=? option.

There can be some options before your [cmd]:

| Option | Default | Description | |:-|:-:|-| | -mode=? | "async" | specify how to run the command as -mode=?, available modes are "async" (default), "bang" (with ! command) and "terminal" (in internal terminal), see running modes for details. | | -cwd=? | unset | initial directory (use current directory if unset), for example use -cwd=<root> to run commands in project root directory, or -cwd=$(VIM_FILEDIR) to run commands in current buffer's parent directory. | | -save=? | 0 | use -save=1 to save current file, -save=2 to save all modified files before executing. | | -program=? | unset | set to make to use &makeprg, grep to use &grepprt and wsl to execute commands in WSL (windows 10), see command modifiers. | | -post=? | unset | vimscript to exec after job finished, spaces must be escaped to '\ ' | | -auto=? | unset | event name to trigger QuickFixCmdPre/QuickFixCmdPost [name] autocmd. | | -raw | unset | use raw output if present, and &errorformat will be ignored. | | -strip | unset | remove the heading/trailing messages if it is present (omit command and "[Finished in ...]" message). | | -errorformat=? | unset | errorformat for error matching, if it is unprovided, use current &errorformat value. Beware that % needs to be escaped into \%. | | -silent | unset | provide -silent to prevent open quickfix window (will override g:asyncrun_open temporarily) | | -scroll=? | unset | set to 0 to prevent quickfix auto-scrolling | | -once | unset | provide to buffer all output and flush when job is finished, useful when there are multi-line patterns in your errorformat | | -encoding=? | unset | specify command encoding independently (overshadow g:asyncrun_encs) | | -pos=? | "bottom" | When using internal terminal with -mode=term, -pos is used to specify where to split the terminal window, it can be one of "tab", "curwin", "top", "bottom", "left", "right" and "external". And you can customize new runners and pass runner's name to -pos option. | | -rows=num | 0 | When using a horizontal split terminal, this value repre