colben/vim
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
vim/doc/asyncrun.txt
colben 6574151a51 first commit
2021-08-29 00:05:19 +08:00

432 lines
19 KiB
Plaintext
Raw Permalink Blame History

*asyncrun.txt* asyncrun.vim: Run Async Shell Commands in Vim 8.0 and Output to Quickfix Window
===============================================================================
Contents ~
1. Introduction |asyncrun-introduction|
2. Preface |asyncrun-43-preface|
3. News |asyncrun-44-news|
4. Install |asyncrun-45-install|
5. Example |asyncrun-46-example|
6. Tutorials |asyncrun-48-tutorials|
1. Async run gcc to compile current file |asyncrun-49-async-run-gcc-to-compile-current-file|
2. Async run make |asyncrun-50-async-run-make|
3. Grep key word |asyncrun-51-grep-key-word|
4. Compile go project |asyncrun-52-compile-go-project|
5. Lookup man page |asyncrun-53-lookup-man-page|
6. Git push |asyncrun-54-git-push|
7. Setup '<F7>' to compile file |F7|
7. Manual |asyncrun-56-manual|
1. AsyncRun - Run shell command |57-asyncrun-run-shell-command|
2. AsyncStop - Stop the running job |asyncrun-58-asyncstop-stop-running-job|
3. Settings: |asyncrun-59-settings|
4. Variables: |asyncrun-61-variables|
5. Requirements: |asyncrun-62-requirements|
6. Cooperate with vim-fugitive: |asyncrun-63-cooperate-with-vim-fugitive|
8. More |asyncrun-66-more|
9. Further |asyncrun-75-further|
10. History |asyncrun-77-history|
11. Credits |asyncrun-78-credits|
12. References |asyncrun-references|
===============================================================================
*asyncrun-introduction*
Introduction ~
Run Async Shell Commands in Vim 8.0 and Output to Quickfix Window
===============================================================================
*asyncrun-43-preface*
Preface ~
This plugin takes the advantage of new apis in Vim 8 (and NeoVim) to enable you
to run shell commands in background and read output in the quickfix window in
realtime:
- Easy to use, just start your background command by ':AsyncRun' (just like
old "!" cmd).
- Command is done in the background, no need to wait for the entire process
to finish.
- Output are 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 you job finished while you're
focusing on editing.
- Fast and lightweight, just a single self-contained 'asyncrun.vim' source
file.
- Provide corresponding user experience vim, neovim, gvim and macvim.
If that doesn't excite you, then perhaps this GIF screen capture below will
change your mind.
===============================================================================
*asyncrun-44-news*
News ~
- 2016/10/17 Glad to announce that 'asyncrun.vim' supports NeoVim now.
- 2016/10/15 'asyncrun.vim' can cooperate with 'vim-fugitive', see the bottom
of the README.
===============================================================================
*asyncrun-45-install*
Install ~
Copy 'asyncrun.vim' to your '~/.vim/plugin' or use Vundle to install it from
'skywind3000/asyncrun.vim' .
===============================================================================
*asyncrun-46-example*
Example ~
Image: [47]
===============================================================================
*asyncrun-48-tutorials*
Tutorials ~
-------------------------------------------------------------------------------
*asyncrun-49-async-run-gcc-to-compile-current-file*
Async run gcc to compile current file ~
>
:AsyncRun gcc % -o %<
:AsyncRun g++ -O3 "%" -o "%<" -lpthread
<
This command will run gcc in the background and output to the quickfix window
in realtime. Macro ''%'' stands for filename and ''%>'' represents filename
without extension.
-------------------------------------------------------------------------------
*asyncrun-50-async-run-make*
Async run make ~
>
:AsyncRun make
:AsyncRun make -f makefile
<
-------------------------------------------------------------------------------
*asyncrun-51-grep-key-word*
Grep key word ~
>
:AsyncRun! grep -R word .
:AsyncRun! grep -R <cword> .
<
when '!' is included, auto-scroll in quickfix will be disabled. '<cword>'
represents current word under cursor.
-------------------------------------------------------------------------------
*asyncrun-52-compile-go-project*
Compile go project ~
>
:AsyncRun go build "%:p:h"
<
Macro ''%:p:h'' stands for current file dir.
-------------------------------------------------------------------------------
*asyncrun-53-lookup-man-page*
Lookup man page ~
>
:AsyncRun! man -S 3:2:1 <cword>
<
-------------------------------------------------------------------------------
*asyncrun-54-git-push*
Git push ~
>
:AsyncRun git push origin master
<
-------------------------------------------------------------------------------
Setup '<*F7*>' to compile file
>
:noremap <F7> :AsyncRun gcc "%" -o "%<" <cr>
<
File name may contain spaces, therefore, it's safe to quote them.
===============================================================================
*asyncrun-56-manual*
Manual ~
There are two vim commands: ':AsyncRun' and ':AsyncStop' to control async jobs.
-------------------------------------------------------------------------------
*57-asyncrun-run-shell-command*
AsyncRun - Run shell command ~
>
:AsyncRun[!] [options] {cmd} ...
<
run shell command in background and output to quickfix. when '!' is included,
auto-scroll in quickfix will be disabled. Parameters are splited by space, if a
parameter contains space, it should be **quoted** or escaped as backslash +
space (unix only).
Parameters accept macros 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
$VIM_SVRNAME - Value of v:servername for +clientserver usage
<
These environment variables wrapped by '$(...)' (eg. '$(VIM_FILENAME)') will
also be expanded in the parameters.
There can be some options before your '[cmd]':
>
-mode=0/1/2 - start mode: 0(async, default), 1(:make), 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`, `grep` to use `&grepprg`
-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 string starts 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".
-------------------------------------------------------------------------------
*asyncrun-58-asyncstop-stop-running-job*
AsyncStop - Stop the running job ~
>
:AsyncStop[!]
<
stop the running job, when "!" is included, job will be stopped by signal KILL
-------------------------------------------------------------------------------
*asyncrun-59-settings*
Settings: ~
- g:asyncrun_exit - script will be executed after finished
- g:asyncrun_bell - non-zero to ring a bell after finished
- g:asyncrun_mode - 0:async(require vim 7.4.1829) 1:sync 2:shell
- g:asyncrun_encs - set shell encoding if it's different from '&encoding',
see here [60]
- g:asyncrun_trim - non-zero to trim the empty lines in the quickfix window.
-------------------------------------------------------------------------------
*asyncrun-61-variables*
Variables: ~
- g:asyncrun_code - exit code
- g:asyncrun_status - 'running', 'success' or 'failure'
-------------------------------------------------------------------------------
*asyncrun-62-requirements*
Requirements: ~
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-63-cooperate-with-vim-fugitive*
Cooperate with vim-fugitive: ~
asyncrun.vim can cooperate with 'vim-fugitive', see here [64].
Image: [65]
===============================================================================
*asyncrun-66-more*
More ~
- Additional examples (background ctags updating, pdf conversion, ...) [67]
- Notify user job finished by playing a sound [68]
- View progress in status line or vim airline [69]
- Best practice with quickfix windows [70]
- Scroll the quickfix window only if the cursor is on the last line [71]
- Cooperate with vim-fugitive [64]
- Replace old ':make' command with asyncrun [72]
- Quickfix encoding problem when using Chinese or Japanese [60]
- Example for updating and adding cscope files [73]
Don't forget to read the Frequently Asked Questions [74].
===============================================================================
*asyncrun-75-further*
Further ~
- Experiment: get netrw using asyncrun to save remote files [76]
===============================================================================
*asyncrun-77-history*
History ~
- 1.3.3 (2016-10-28): prevent job who reads stdin 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
===============================================================================
*asyncrun-78-credits*
Credits ~
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
===============================================================================
*asyncrun-references*
References ~
[1] https://github.com/skywind3000/asyncrun.vim#start-of-content
[2] https://github.com/
[3] https://github.com/personal
[4] https://github.com/open-source
[5] https://github.com/business
[6] https://github.com/explore
[7] https://github.com/join?source=header-repo
[8] https://github.com/login?return_to=%2Fskywind3000%2Fasyncrun.vim
[9] https://github.com/pricing
[10] https://github.com/blog
[11] https://help.github.com
[12] https://github.com/search
[13] https://github.com/skywind3000/asyncrun.vim/watchers
[14] https://github.com/skywind3000/asyncrun.vim/stargazers
[15] https://github.com/skywind3000/asyncrun.vim/network
[16] https://github.com/skywind3000/asyncrun.vim
[17] https://github.com/skywind3000/asyncrun.vim/issues
[18] https://github.com/skywind3000/asyncrun.vim/pulls
[19] https://github.com/skywind3000/asyncrun.vim/projects
[20] https://github.com/skywind3000/asyncrun.vim/wiki
[21] https://github.com/skywind3000/asyncrun.vim/pulse
[22] https://github.com/skywind3000/asyncrun.vim/graphs
[23] https://github.com/skywind3000/asyncrun.vim/commits/master
[24] https://github.com/skywind3000/asyncrun.vim/branches
[25] https://github.com/skywind3000/asyncrun.vim/releases
[26] https://github.com/skywind3000/asyncrun.vim/graphs/contributors
[27] https://github.com/skywind3000/asyncrun.vim/blob/master/LICENSE
[28] https://github.com/skywind3000/asyncrun.vim/search?l=vim
[29] https://help.github.com/articles/which-remote-url-should-i-use
[30] https://github.com/skywind3000/asyncrun.vim/archive/master.zip
[31] https://github.com/skywind3000/asyncrun.vim/find/master
[32] https://github.com/skywind3000/asyncrun.vim/tree/master
[33] https://github.com/skywind3000/asyncrun.vim/commit/1edc42699bcb8a1b17398c2590a27636e327531d
[34] https://camo.githubusercontent.com/a08cc422099cb8fd2a030bc7e6da7732e483e336/68747470733a2f2f322e67726176617461722e636f6d2f6176617461722f33313761636661306235663764643563623831363331303365326266623366363f643d68747470732533412532462532466173736574732d63646e2e6769746875622e636f6d253246696d6167657325324667726176617461727325324667726176617461722d757365722d3432302e706e6726723d7826733d313430
[35] https://github.com/skywind3000/asyncrun.vim/tree/1edc42699bcb8a1b17398c2590a27636e327531d
[36] https://assets-cdn.github.com/images/spinners/octocat-spinner-32.gif
[37] https://github.com/skywind3000/asyncrun.vim/tree/master/doc
[38] https://github.com/skywind3000/asyncrun.vim/commit/7b906e89f42b811176007a52a8affdfd11c76a93
[39] https://github.com/skywind3000/asyncrun.vim/tree/master/plugin
[40] https://github.com/skywind3000/asyncrun.vim/commit/c9bb3b9a1909a7e3bcc53817cefa94460cd4a85e
[41] https://github.com/skywind3000/asyncrun.vim/commit/e4f207983822abb58df9f3577cf0b3fbacdf0231
[42] https://github.com/skywind3000/asyncrun.vim/blob/master/README.md
[43] https://github.com/skywind3000/asyncrun.vim#preface
[44] https://github.com/skywind3000/asyncrun.vim#news
[45] https://github.com/skywind3000/asyncrun.vim#install
[46] https://github.com/skywind3000/asyncrun.vim#example
[47] https://raw.githubusercontent.com/skywind3000/asyncrun.vim/master/doc/screenshot.gif
[48] https://github.com/skywind3000/asyncrun.vim#tutorials
[49] https://github.com/skywind3000/asyncrun.vim#async-run-gcc-to-compile-current-file
[50] https://github.com/skywind3000/asyncrun.vim#async-run-make
[51] https://github.com/skywind3000/asyncrun.vim#grep-key-word
[52] https://github.com/skywind3000/asyncrun.vim#compile-go-project
[53] https://github.com/skywind3000/asyncrun.vim#lookup-man-page
[54] https://github.com/skywind3000/asyncrun.vim#git-push
[55] https://github.com/skywind3000/asyncrun.vim#setup-f7-to-compile-file
[56] https://github.com/skywind3000/asyncrun.vim#manual
[57] https://github.com/skywind3000/asyncrun.vim#asyncrun---run-shell-command
[58] https://github.com/skywind3000/asyncrun.vim#asyncstop---stop-the-running-job
[59] https://github.com/skywind3000/asyncrun.vim#settings
[60] https://github.com/skywind3000/asyncrun.vim/wiki/Quickfix-encoding-problem-when-using-Chinese-or-Japanese
[61] https://github.com/skywind3000/asyncrun.vim#variables
[62] https://github.com/skywind3000/asyncrun.vim#requirements
[63] https://github.com/skywind3000/asyncrun.vim#cooperate-with-vim-fugitive
[64] https://github.com/skywind3000/asyncrun.vim/wiki/Cooperate-with-vim-fugitive
[65] https://raw.githubusercontent.com/skywind3000/asyncrun.vim/master/doc/cooperate_with_fugitive.gif
[66] https://github.com/skywind3000/asyncrun.vim#more
[67] https://github.com/skywind3000/asyncrun.vim/wiki/Additional-Examples
[68] https://github.com/skywind3000/asyncrun.vim/wiki/Playing-Sound
[69] https://github.com/skywind3000/asyncrun.vim/wiki/Display-Progress-in-Status-Line-or-Airline
[70] https://github.com/skywind3000/asyncrun.vim/wiki/Quickfix-Best-Practice
[71] https://github.com/skywind3000/asyncrun.vim/wiki/Scroll-the-quickfix-window-only-if-cursor-is-on-the-last-line
[72] https://github.com/skywind3000/asyncrun.vim/wiki/Replace-old-make-command-with-AsyncRun
[73] https://github.com/skywind3000/asyncrun.vim/wiki/Example-for-updating-and-adding-cscope
[74] https://github.com/skywind3000/asyncrun.vim/wiki/FAQ
[75] https://github.com/skywind3000/asyncrun.vim#further
[76] https://github.com/skywind3000/asyncrun.vim/wiki/Get-netrw-using-asyncrun-to-save-remote-files
[77] https://github.com/skywind3000/asyncrun.vim#history
[78] https://github.com/skywind3000/asyncrun.vim#credits
[79] https://github.com/contact
[80] https://developer.github.com
[81] https://training.github.com
[82] https://shop.github.com
[83] https://github.com/about
[84] https://github.com
[85] https://github.com/site/terms
[86] https://github.com/site/privacy
[87] https://github.com/security
[88] https://status.github.com/
vim: ft=help
Reference in New Issue View Git Blame Copy Permalink