*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