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 | 中文文档】

• 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 with vim-plug:

Plug 'skywind3000/asyncrun.vim'

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

• 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

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.

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

: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]:

For the full list of the options, please see the Command Specification.

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

Don't worry if you do have a shell command starting with '-', Just put a placeholder @ before your command to tell asyncrun explicitly: "stop parsing options now, the following string is all my command".

:AsyncStop[!]

stop the running job, when "!" is included, job will be stopped by signal KILL.

Function form is convenient for vimscript:

:call asyncrun#run(bang, opts, command)

parameters:

• bang: an empty string or a single bang character "!", same as bang sign in AsyncRun!.
• opts: a dictionary contains: mode, cwd, raw and errorformat etc.
• command: the shell command you want to execute.

• g:asyncrun_exit - script will be executed after finished.
• g:asyncrun_bell - non-zero to ring a bell after finished.
• g:asyncrun_mode - specify how to run your command, see here.
• g:asyncrun_encs - set shell encoding if it's different from &encoding, see encoding.
• g:asyncrun_trim - non-zero to trim the empty lines in the quickfix window.
• g:asyncrun_auto - event name to trigger QuickFixCmdPre/QuickFixCmdPost, see FAQ.
• g:asyncrun_open - above zero to open quickfix window at given height after command starts.
• g:asyncrun_save - non-zero to save current(1) or all(2) modified buffer(s) before executing.
• g:asyncrun_timer - how many messages should be inserted into quickfix every 100ms interval.
• g:asyncrun_wrapper - enable to setup a command prefix.
• g:asyncrun_stdin - non-zero to enable stdin (useful for cmake on windows).
• g:asyncrun_qfid - use quickfix id to prevent interleaving output of concurrent plugins appending to the quickfix list.

For more information of above options, please visit option details .

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

autocmd User AsyncRunPre - triggered before executing
autocmd User AsyncRunStart - triggered after starting successfully
autocmd User AsyncRunStop - triggered when job finished

Note, AsyncRunPre is always likely to be invoked, but AsyncRunStart and AsyncRunStop will only be invoked if the job starts successfully.

When the previous job is still running or vim job slot is full, AsyncRun may fail. In this circumstance, AsyncRunPre will be invoked but AsyncRunStart and AsyncRunStop will have no chance to trigger.

Vim is lack of project management, as files usually belong to projects, you can do nothing to the project if you don't have any information about where the project locates. Inspired by CtrlP, this feature (new in version 1.3.12) is very useful when you've something to do with the whole project.

Macro <root> or $(VIM_ROOT) in the command line or in the -cwd option will be expanded as the Project Root Directory of the current file:

:AsyncRun make
:AsyncRun -cwd=<root> make

The first make will run in the vim's current directory (which :pwd returns), while the second one will run in the project root directory of current file. This feature is very useful when you have something (make / grep) to do with the whole project.

The project root is the nearest ancestor directory of the current file which contains one of these directories or files: .svn, .git, .hg, .root or .project. If none of the parent directories contains these root markers, the directory of the current file is used as the project root. The root markers can also be configurated, see Project Root.

The default behavior is to run async command and output to quickfix window. However there is a -mode=? option can allow you specify how to run your command:

For more information, please see here.

AsyncRun is capable to run commands in Vim/NeoVim's internal terminal with the -mode=term option. You can specify how to open the terminal window by -pos=?, available positions are:

• -pos=tab: open the terminal in a new tab.
• -pos=TAB: open the terminal in a new tab on the left side.
• -pos=curwin: open the terminal in the current window.
• -pos=top: open the terminal above the current window.
• -pos=bottom: open the terminal below the current window.
• -pos=left: open the terminal on the left side.
• -pos=right: open the terminal on the right side.
• -pos=hide: don't open a window, run in background.
• -pos=external: use an external terminal (Windows & Gnome only).

Examples:

:AsyncRun -mode=term -pos=tab python "$(VIM_FILEPATH)"
:AsyncRun -mode=term -pos=TAB -close -cwd=<root> lazygit
:AsyncRun -mode=term -pos=bottom -rows=10 python "$(VIM_FILEPATH)"
:AsyncRun -mode=term -pos=right -cols=80 python "$(VIM_FILEPATH)"
:AsyncRun -mode=term -pos=curwin python "$(VIM_FILEPATH)"
:AsyncRun -mode=term -pos=curwin -hidden python "$(VIM_FILEPATH)"

Internal terminal related options:

The -pos field accepts an uppercase TAB, to create a tab on the left of the current tab. When using internal terminal in a split window, AsyncRun will firstly reuse a finished previous terminal window if it exists, if not, a new terminal window will be created in given position. Tab based terminal can also be reusable if -reuse is provided.

There can be many commands running in the internal terminal, you can specify a name for each of them and receive it in g:asyncrun_name:

:AsyncRun -mode=term -pos=hide -name=123 -post=echo\ g:asyncrun_name ls -la

When this process finished, script defined in -post will be executed and your command name will display by echo. Another variable g:asyncrun_code stores exit code.

AsyncRun displays its output in quickfix window, so if you don't use :copen {height} to open quickfix window, you won't see any output. For convenience there is an option g:asyncrun_open for you:

:let g:asyncrun_open = 8

Setting g:asyncrun_open to 8 will open quickfix window automatically at 8 lines height after command starts.

AsyncRun can take a range of lines in the current buffer as command's stdin after version 1.3.27. You can try:

:%AsyncRun cat

the whole buffer will be the input of command cat. you will see the content of your current buffer will be output to the quickfix window.

:10,20AsyncRun python

text between line 10-20 will be taken as the stdin of python. code in that range will be executed by python and the output will display in the quickfix window.

:'<,'>AsyncRun -raw perl

The visual selection (line-wise) will be taken as stdin.

AsyncRun provides enough flexibility and possibility to customize various details of how to run a command.

Besides the default quickfix and internal terminal mechanism, the user-defined runners allow you to run commands in any way you want. eg. in a new gnome-terminal window/tab, a floaterm window, or a side-by-side tmux split.

By default, AsyncRun is shipped with some popular runners:

e.g.

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

Screenshot for gnome runner:

When using gnome, konsole, or xfce runner in GVim, you get exactly the same experience like starting a command-line program from IDEs.

When you use toggleterm2 and use the packer.nvim management plugin, you can set shortcut keys to specify the open window, such as:

	use({
		"skywind3000/asyncrun.vim",
		as = "asyncrun",
		config = function()
			require("asyncrun.toggleterm2").setup({
				mapping = "<leader>tt",
				start_in_insert = false,
				clear_env = false,
				go_back = true,
			})
		end,
	})

All runners are customizable, you can modify or define your own runners, see the next section "customize runner".

User-defined runners allow you to specify how the command will run by creating a new runner. It can be useful when you want your commands run in a tmux split or a new gnome-terminal window:

function! MyRunner(opts)
 echo "command to run is: " . a:opts.cmd
endfunction
let g:asyncrun_runner = get(g:, 'asyncrun_runner', {})
let g:asyncrun_runner.test = function('MyRunner')

Then try:

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

When -mode is term and -pos can used to represent runner name.

Runner function has only one argument: opts, it contains the options extracted from :AsyncRun command line, and opts.cmd stores current command.

Another way to create a runner is to simply create a .vim file in the autoload/asyncrun/runner/ folder of your run-time-path (see the examples).

For more information, please visit project wiki: customize runner.

Command modifiers can be used to change your command before running:

let g:asyncrun_program = get(g:, 'asyncrun_program', {})
let g:asyncrun_program.nice = { opts -> 'nice -5' . opts.cmd }

When you are using:

:AsyncRun -program=nice ls -la

The command ls -la will be changed into nice -5 ls -la.

The -program=msys, -program=wsl are both implemented as a new command modifier it changes command ls into:

c:\windows\sysnative\wsl.exe ls

And replace any thing like $(WSL_FILENAME) and $(WSL_FILEPATH) in your command.

Vim 7.4.1829 is minimal version to support async mode. If you are use older versions, g:asyncrun_mode will fall back from 0/async to 1/sync. NeoVim 0.1.4 or later is also supported.

Recommend to use Vim 8.0 or later.

asyncrun.vim can cooperate with vim-fugitive, see here.

• Better way for C/C++ developing with AsyncRun

• Command Specification
• The project root directory of the current file
• Additional examples (background ctags updating, pdf conversion, ...)
• Notify user job finished by playing a sound
• View progress in status line or vim airline
• Best practice with quickfix window
• Scroll the quickfix window only if the cursor is on the last line
• Replace old ':make' command with asyncrun
• Quickfix encoding problem when using Chinese or Japanese
• Example for updating and adding cscope files
• Specify how to run your command
• Customize Runners

Don't forget to read the Frequently Asked Questions.

See: Cooperate with famous plugins

• 2.9.1 (2021年12月15日): extra runners to run command in a tmux, or floaterm window.
• 2.6.2 (2020年03月08日): change runner's argument from string to dict.
• 2.6.0 (2020年03月07日): -post can be used in terminal mode.
• 2.5.5 (2020年03月07日): "-mode=term -pos=tab" obeys "-focus=0" now.
• 2.5.3 (2020年03月02日): new -silent option to prevent open quickfix, add command modifier.
• 2.5.0 (2020年02月29日): refactor, remove useless codes, new command modifier g:asyncrun_program.
• 2.4.8 (2020年02月21日): run with :execute if command is starting with colon.
• 2.4.7 (2020年02月21日): new customizable runners by g:asyncrun_runner, see customize runner.
• 2.4.0 (2020年02月10日): fixed internal terminal issue in msys.
• 2.3.0 (2020年02月10日): new mode aliases, minor issue fix.
• 2.2.9 (2020年02月10日): new terminal mode options: -safe=1, -listed=0 and -reuse.
• 2.2.6 (2020年02月06日): new: parameter -hidden when using -mode=term to set bufhidden to hidden.
• 2.2.5 (2020年02月05日): more safe to start a terminal.
• 2.2.4 (2020年02月05日): exit when starting terminal failed in current window with -pos=curwin.
• 2.2.3 (2020年02月05日): new -program=wsl to run command in wsl (windows 10 only).
• 2.2.2 (2020年02月05日): new -pos=curwin to open terminal in current window.
• 2.2.1 (2020年01月20日): set noreletivenumber for terminal window.
• 2.2.0 (2020年01月18日): new -focus=0 option for -mode=term to prevent focus change.
• 2.1.9 (2020年01月12日): polish -mode=term, omit number and signcolunm in terminal.
• 2.1.8 (2020年01月11日): new options errorformat in asyncrun#run(...).
• 2.1.4 (2020年01月09日): correct command encoding on windows and fixed minor issues.
• 2.1.0 (2020年01月09日): new mode -mode=term to run command in a reusable terminal window.
• 2.0.8 (2019年04月28日): handle tcd (introduced in 8.1.1218). use grepformat when -program=grep.
• 2.0.7 (2019年01月27日): restore g:asyncrun_stdin because rg will break if stdin is pipe.
• 2.0.6 (2019年01月26日): more adaptive to handle stdin and remove 'g:asyncrun_stdin'
• 2.0.5 (2019年01月14日): enable stdin by default on windows (fix cmake stdin warning on windows).
• 2.0.4 (2019年01月13日): new option g:asyncrun_stdin, set to 1 to enable stdin .
• 2.0.3 (2019年01月04日): new macro $VIM_PATHNOEXT (by @PietroPate)
• 2.0.2 (2018年12月25日): new -strip and -append option to control quickfix (by @bennyyip)
• 2.0.1 (2018年04月29日): new option g:asyncrun_save to save files.
• 2.0.0 (2018年04月27日): improve neovim compatability, handle tcd command in neovim.
• 1.3.27 (2018年04月17日): AsyncRun now supports range, try: :%AsyncRun cat
• 1.3.26 (2018年04月16日): new option g:asyncrun_wrapper to enable setup a command prefix
• 1.3.25 (2018年04月16日): handle makeprg/grepprg correctly, accept % and $* macros. close #96 #84 and #35
• 1.3.24 (2018年04月13日): remove trailing ^M on windows.
• 1.3.23 (2018年04月03日): back compatible to vim 7.3, can fall back to mode 1 in old vim.
• 1.3.22 (2018年03月11日): new option g:asyncrun_open to open quickfix window automatically at given height.
• 1.3.21 (2018年03月02日): fixed: float point reltime issues
• 1.3.20 (2018年02月08日): fixed: Incorrect background job status (@antoinemadec)
• 1.3.19 (2017年12月13日): new option g:asyncrun_skip to skip specific autocmd.
• 1.3.18 (2017年12月12日): fixed: windo breaks commands (especially in neovim).
• 1.3.17 (2017年08月06日): fixed: process hang when mode is 5.
• 1.3.16 (2017年08月05日): fixed: g:asyncrun_mode issue (Joel Taylor)
• 1.3.15 (2017年07月30日): fixed: remove trailing new line in neovim.
• 1.3.14 (2017年07月27日): improve asyncrun#get_root(), allow user indicate the rootmarkers
• 1.3.13 (2017年07月12日): new option (-raw) to use raw output (not match with the errorformat).
• 1.3.12 (2017年06月25日): new macro <root> or $(VIM_ROOT) to indicate project root directory.
• 1.3.11 (2017年05月19日): new option (-save=2) to save all modified files.
• 1.3.10 (2017年05月04日): remove trailing ^M in NeoVim 2.0 on windows
• 1.3.9 (2016年12月23日): minor bugs fixed, improve performance and compatibility.
• 1.3.8 (2016年11月17日): new autocmd AsyncRunPre/AsyncRunStart/AsyncRunStop, fixed cmd line window conflict.
• 1.3.7 (2016年11月13日): new option 'g:asyncrun_timer' to prevent gui freeze by massive output.
• 1.3.6 (2016年11月08日): improve performance in quickfix_toggle, fixed small issue in bell ringing.
• 1.3.5 (2016年11月02日): new option "g:asyncrun_auto" to trigger QuickFixCmdPre/QuickFixCmdPost.
• 1.3.4 (2016年10月28日): new option "g:asyncrun_local" to use local value of errorformat rather the global value.
• 1.3.3 (2016年10月21日): prevent job who reads stdin from getting hanging, fixed an issue in fast exiting jobs.
• 1.3.2 (2016年10月19日): new "-post" option to run a vimscript after the job finished
• 1.3.1 (2016年10月18日): fixed few issues of arguments passing in different modes
• 1.3.0 (2016年10月17日): add support to neovim, better CJK characters handling.
• 1.2.0 (2016年10月16日): refactor, correct arguments parsing, cmd options and &makeprg supports
• 1.1.1 (2016年10月13日): use the vim native &shell and &shellcmdflag config to execute commands.
• 1.1.0 (2016年10月12日): quickfix window scroll only if cursor is on the last line
• 1.0.3 (2016年10月10日): reduce quickfix output latency.
• 1.0.2 (2016年10月09日): fixed an issue in replacing macros in parameters.
• 1.0.1 (2016年10月07日): Add a convenient way to toggle quickfix window (asyncrun#quickfix_toggle)
• 1.0.0 (2016年09月21日): can fall back to sync mode to compatible older vim versions.
• 0.0.3 (2016年09月15日): new arguments now accept environment variables wrapped by $(...)
• 0.0.2 (2016年09月12日): some improvements and more documents for a tiny tutorial.
• 0.0.1 (2016年09月08日): improve arguments parsing
• 0.0.0 (2016年08月24日): initial version

Trying best to provide the most simply and convenience experience in the asynchronous-jobs.

Author: skywind3000 Please vote it if you like it: http://www.vim.org/scripts/script.php?script_id=5431