asynctasks.vim - modern task system
The generic way to handle building/running/testing/deploying tasks by imitating vscode's task system.
- Get Started
- Advanced Topics
- Task Examples
- Command Line Tool
- Frequently Asked Questions
This readme is also available in:
As vim 8.0 released in 2017, we have got many wonderful plugins like: LSP, DAP and asynchronous linters. Even things like vimspector which could only been imagined in emacs in the past, now become reality in vim.
However, vim is still lack of an elegent task system to speed up your inner software development cycle (edit, compile, test). A lot of people are still dealing with those building, testing and deploying tasks in such a primitive or flaky way. Therefor, I decide to create this plugin and introduce vscode's task like machanisms to vim.
Vscode creates a
.vscode folder in your project root directory and use a
.vscode/tasks.json file to define project specific tasks. Similar,
asynctasks.vim uses a
.tasks file in your project folders for local tasks and use
~/.vim/tasks.ini to define global tasks for generic projects.
This is very simple, but most good designs always start from a very simple concept. You will benefit a lot from the productivity and possibility of this task system.
Plug 'skywind3000/asynctasks.vim' Plug 'skywind3000/asyncrun.vim'
It requires asyncrun.vim 2.4.0 or above. Don't forget to setup:
let g:asyncrun_open = 6
And quickfix window can be opened automatically, otherwise you can't see the task output unless using
Build and run a single file
It's convenient for me to build and run a single file directly without creating a new project for that if I want to try some small and new ideas. In this circumstance, we can use
:AsyncTaskEdit command to edit the
.tasks configuration file in your current project root directory:
[file-build] # macros in the "$(...)" form will be substituted, # shell command, use quotation for filenames containing spaces command=gcc -O2 "$(VIM_FILEPATH)" -o "$(VIM_FILEDIR)/$(VIM_FILENOEXT)" # working directory cwd=$(VIM_FILEDIR) [file-run] command="$(VIM_FILEDIR)/$(VIM_FILENOEXT)" cwd=$(VIM_FILEDIR) # output mode: run in a terminal output=terminal
There are two tasks
file-run defined in this
.tasks file. Then from the directory where this
.tasks reside and its child directories, you can use:
:AsyncTask file-build :AsyncTask file-run
To build and run the current file:
This is the result of
:AsyncTask file-build, the command output displays in the quickfix window and errors are matched with
errorformat. You can navigate the command output in the quickfix window or use
:cprev to jump between errors.
There are many macros can be used in the command field and will be expanded and replaced when task starts. Having a fast, low-friction Edit/Build/Test cycle is one of the best and easiest ways to increase developer productivity, so we will map them to F5 and F9:
noremap <silent><f5> :AsyncTask file-run<cr> noremap <silent><f9> :AsyncTask file-build<cr>
Put the code above in your
vimrc and you can have F9 to compile current file and F5 to run it. And you may ask, this is for C/C++ only, what if you want to run a python script, should you create a new task
file-run-python ? Totally unnecessary, commands can match with file types:
command followed by a colon accepts file type list separated by comma. If the current file type cannot be matched, the default command will be used. The
-save=2 represents to save all modified buffers before running the task.
At this point, you can have your
F5 to run all type of files. And plugins like quickrun can be obsoleted immediately, they can't do better than this. Then we continue to polish
file-build to support more file types:
[file-build] command:c,cpp=gcc -O2 -Wall "$(VIM_FILEPATH)" -o "$(VIM_PATHNOEXT)" -lstdc++ -lm -msse3 command:go=go build -o "$(VIM_PATHNOEXT)" "$(VIM_FILEPATH)" command:make=make -f "$(VIM_FILEPATH)" output=quickfix cwd=$(VIM_FILEDIR) save=2
Again, F9 can be used to compile many file types, same keybind, different command. This two tasks can be defined in local
.tasks and work for the project scope or in the
~/.vim/tasks.ini and work for all project. Much more elegant than using the old
&makeprg or calling
neomake with a lot
else in your
Tasks for running compilers or grep may set
output=quickfix (default), because the output can use errorformat to match errors in the quickfix window, while tasks for running your file/project may set
When you set
terminal, you can further specify what type of terminal do you want to use exactly, like: a simulated terminal in quickfix window (without matching the errorformat)? the triditional
! command in vim? the internal terminal ? an external terminal window ? or in a tmux split window ?? The detail will be discussed later.
Build and run a project
If you want to do something with a project, you must figure out where the project locates.
asynctasks.vim and its backend
asyncrun.vim choose a widely used method called
root markers to indentify the project root directory. The project root is one of the nearest parent directory containing these markers:
let g:asyncrun_rootmarks = ['.git', '.svn', '.root', '.project', '.hg']
If none of the parent directories contains these root markers, the directory of the current file is used as the project root.
There is a corner case: if current buffer is not a normal file buffer (eg. a tool window) or is an unnamed new buffer, vim's current working directory (which
:pwd returns) will be used as the project root.
Once we got the project location, the macro
$(VIM_ROOT), or its alias
<root>, can be used to represent the project root:
What if your current project is not in any
subversion repository ? How to find out where is my project root ? The solution is very simple, just put an empty
.root file in your project root, it has been defined in
Tasks related to projects can be defined by using this:
[project-build] command=make # set the working directory to the project root. cwd=$(VIM_ROOT) [project-run] command=make run # <root> is an alias to `$(VIM_ROOT)`, a little easier to type. cwd=<root> output=terminal
We assign F6 and F7 for them:
noremap <silent><f6> :AsyncTask project-run<cr> noremap <silent><f7> :AsyncTask project-build<cr>
Now, F7 can be used to build your project and F6 can be used run your project. You may ask again, this is for
gnu-make only, but there are a lot of build tools like cmake, ninja and bazel, should you define new tasks as
project-build-ninja and assign different keymaps for them ?
No, you don't have to. The easiest way is to put previous
project-run in your
~/.vim/tasks.ini as the default and global tasks, you can use them directly for generic projects using
For other type of projects, for example, I am using
msbuild in my project
A. And I can define a new
project-build task in the local
.tasks file residing in project
[project-build] command=vcvars32 > nul && msbuild build/StreamNet.vcxproj /property:Configuration=Debug /nologo /verbosity:quiet cwd=<root> errorformat=%f(%l):%m [project-run] command=build/Debug/StreamNet.exe cwd=<root> output=terminal
.tasks configuration file are read top to bottom and the most recent tasks found take precedence. and local tasks always have higher priority than the global tasks.
Task defined in
.tasks will always override the task with the same name in
~/.vim/tasks.ini. So, in project
A, our two old friends
project-run have been replaced with the local methods.
Firstly, the new
project-build task will call
vcvars32.bat to setup environment variables, then, use a
&& to concatenate
errorformat is initialized to
%f(%l):%m for matching
Visual C++ errors in this task.
We can still use
F7 to build this project and
F6 to run it. We don't have to change our habit if we are working in a different type of project. Unified workflow can be used in different type of projects. This is the power of local/global tasks combination.
:AsyncTaskEdit to edit local tasks, and
:AsyncTaskEdit! to edit global tasks.
Query available tasks
What tasks do you have in current project ? Where are they defined ? Has one global task been overrided by a local one ? We use
:AsyncTaskList command to answer these questions:
It will display task name, command and where it has been defined.
Bonus: tasks starting with a dot "." will be hidden (eg. ".file-test-temp1"), use
:AsyncTaskList! to see them all.
Macro variable substitution
asynctasks.vim supports macro variable substitution in
cwd fileds, available macros are:
$(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_FILETYPE) # File type (value of &ft in vim) $(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 (which :pwd returns). $(VIM_RELDIR) # File path relativize to current directory. $(VIM_RELNAME) # File name relativize to current directory. $(VIM_ROOT) # Project root directory. $(VIM_CWORD) # Word under cursor. $(VIM_CFILE) # File name under cursor. $(VIM_CLINE) # Cursor line number in current buffer $(VIM_GUI) # has('gui_runnin')? $(VIM_VERSION) # Value of v:version. $(VIM_COLUMNS) # Current screen width. $(VIM_LINES) # Current screen height. $(VIM_SVRNAME) # Value of v:servername. $(VIM_PRONAME) # Name of current project root directory $(VIM_DIRNAME) # Name of current directory $(VIM_INIFILE) # Full path name of current ini (.tasks) file. $(VIM_INIHOME) # Where the ini file locates.
They will be expanded and replaced in the
cwd fields. System environment variables with same names are also initialized as the same value. If one of your task has many complex shell commands, you can put the commands in a shell script and execute it in the task:
[project-build] command=build/my-build-task.sh cwd=<root>
In this case, you don't have to pass any argument to
my-build-task.sh, because the shell script can read environment variable
$VIM_FILENAME to access current file name. By utilizing system environment variables with external script file, you can describe many complex tasks in your project. And of course, much more powerful than defining some keymaps for
! command in your
There is a
:AsyncTaskMacro command for you to display macro help:
From left to right, is the macro name, what does it stand for and current value. You don't have to check the documentation when you are editing your task configuration.
Task running modes
There is an
output field in each task's configuration, it can be one of:
quickfix: default mode, output to the quickfix window and match with
terminal: run in a terminal.
Nothing to talk about
output=quickfix, and if you set
terminal your can further specify the terminal type by setting:
let g:asynctasks_term_pos = 'xxx'
to specify what terminal do you want to use, available options are:
||Simulation||Default, simulate a terminal in quickfix window (output will not match the errorformat)|
||-||Use the old
||internal terminal||open a new internal terminal in a new tab|
||internal terminal||open a reusable internal terminal above current window|
||internal terminal||open a reusable internal terminal under current window|
||internal terminal||open a reusable internal terminal on the left|
||internal terminal||open a reusable internal terminal on the right|
||external terminal||use a new system terminal to run your task|
You can set a
pos field in a task to override global
g:asynctasks_term_pos value in the given task.
Almost all the possible methods are here, choose your favorite one.
terminal, and if you set:
let g:asynctasks_term_pos = 'bottom'
:AsyncTask file-run will open an internal terminal under your current window:
If the previous terminal session has finished, the window will be resused. When you set
g:asynctasks_term_pos to one of
right, these two options below can allow you change the terminal size:
let g:asynctasks_term_rows = 10 " set height for the horizontal terminal split let g:asynctasks_term_cols = 80 " set width for vertical terminal split
If a terminal split window is too small for you, you can setup:
let g:asynctasks_term_pos = 'tab'
A whole tab can be used to display the internal terminal:
Almost all the vim screen are occupied, is it big enough to fit your need ? This is my most favorite one.
quickfix can also be used to run your task, but it is not capable to handle user input, and if your program will interact with user, you may choose a real terminal.
- tab terminal can also be reusable if you set
- you can prevent focus changing if you set
0(split terminals only).
(When you are using internal terminal,
asynctasks.vim encourage you to setup
ALT+HJKL to jump around windows and
ALT+q to exit to terminal normal mode).
Run in an external terminal
Many desktop developer using Visual Studio on Windows prefer to run their programs in a new cmd window, we can use
external for this:
let g:asynctasks_term_pos = 'external'
Then, every task with
output=terminal will open a new
Familiar feeling like you are working in Visual Studio.
asynctasks.vim provide you all the possible ways to run a command in vim with no compromise. Choose one you like.
Continue hacking in
Ask for user input
Some tasks, eg finding strings in current project, may need to ask user to input some keywords before start.
command field contains macros in
$(?...) form, when you run
:AsyncTask xxx, you are required to input something in the vim:
[task1] command=echo hello $(?your name), you are a $(gender). output=terminal
:AsyncTask task1 happens, you can input values in the prompt area:
There are two variable you need to provide, input them one by one, press
ESC to give up and
ENTER to confirm. The task will start when you finished:
As you see,
$(?your name) has been substituted with the value you just provided.
Real example used by myself:
[grep] command=rg -n --no-heading --color never "$(?keyword)" "<root>" -tcpp -tc -tpy -tvim -tgo -tasm cwd=$(VIM_ROOT) errorformat=%f:%l:%m
Here is my global
grep task. Each time I use
:AsyncTask grep in any of my project, it prompts me to input
keyword before searching, I can use
<C-r><C-w> to pickup word under cursor or input something new.
If I need other filetypes to search in certain project, I can redifine a new
grep with different parameters for this project.
But most of time, a global
grep task is enough, rg supports
.ignore files for different files, I can use them to prevent searching in unnecessary files. Check rg documentation for
Task with different profiles
One task can have many different
[task1:release] command=gcc -O2 "$(VIM_FILEPATH)" -o "$(VIM_PATHNOEXT)" cwd=$(VIM_FILEDIR) [task1:debug] command=gcc -g "$(VIM_FILEPATH)" -o "$(VIM_PATHNOEXT)" cwd=$(VIM_FILEDIR)
Here we have
task1 with two different profiles
debug. The default profile is
debug, change it to
let g:asynctasks_profile = 'release'
:AsyncTask task1 will run
tasks1 with profile
Different system with different commands
This plugin can select command for given system:
[task1] command=echo default command/win32=echo win32 default command/linux=echo linux default command:c,cpp/win32=echo c/c++ for win32 command:c,cpp/linux=echo c/c++ for linux
system can be used as filter. Default command (the first one) will be chosen if mismatch.
Change this option to specify your system:
let g:asynctasks_system = 'macos'
Then command ending with
/macos will be selected.
Data source for fuzzy finders
You can get task details by:
let current_tasks = asynctasks#list("")
It returns a list of items, each item represents a task. And it can be used as the data source for fuzzy finders like
For customizing additional runners, see customize runners.
Don't like the
.tasks file name ? Rename it as you want:
let g:asynctasks_config_name = '.asynctask' let g:asynctasks_config_name = '.git/tasks.ini'
Don't like the global
tasks.ini file name in your
~/.vim ? Change it to:
let g:asynctasks_rtp_config = "asynctasks.ini"
A list of additional global task configuration files, you can indicate other global configurations:
let g:asynctasks_extra_config = [ \ '~/github/my_dotfiles/my_tasks.ini', \ '~/.config/tasks/local_tasks.ini', \ ]
Then, these two additional globla configurations will be loaded after reading
What terminal do you want to run your task. see Task running modes.
Internal terminal width when using vertical split.
Internal terminal height when using horizontal split.
Set to zero to keep focus when using an internal terminal in a new split.
1 to reuse internal terminal when open it in a new tab.
If it is set to
1, the internal terminal buffers will set
There are many examples about: cmake, grep, ninja, wsl and more:
Command Line Tool
This plugin provides you an
asyncrun.py script (in the
bin folder) when you want to run tasks right in your shell:
To use it, copy the files from
~/bin, or simpily add
bin folder to your
Then, in any child directories of your project, just type:
You don't have to jump back to your project root manually, because
profile-build has a
Example: if you have a
project-search task in your
[project-search] command=rg -n --no-heading "$(?keyword)" "<root>" -tc -tcpp -tpy -tvim cwd=<root> errorformat=%f:%l:%m
It will ask you input a
keyword and then perform a project-wide search for you:
~/github/project1/src/core$ asynctask project-search # press <ENTER> Input argument (keyword): printf # press <ENTER> /home/skywind/github/project1/test/hello.cpp:5: printf("Hello, World !!\n"); /home/skywind/github/project1/test/demo.cpp:7: printf("Hello, Demo !!\n");
Again, you don't have to go back to the project top directory, the task will run project-wide.
$ asynctask file-build hello.c # provide a file name and run task $ asynctask project-build ../project2 # provide a directory and run task $ asynctask -profile=release project-build # build with "release" profile
Interactive mode with
asynctask can allow interactive mode and you can select task with fzf.
Frequently Asked Questions