vim-makejob

Minimal, asynchronous quickfix commands for Vim 8.0
git clone git://git.danielmoch.com/vim-makejob.git
Log | Files | Refs | README | LICENSE

README.md (5739B)


      1 # Vim MakeJob
      2 
      3 This is a plugin for folks who think that Vim's quickfix feature is
      4 great, but who don't like how calls to `:make` and `:grep` freeze the
      5 editor. _MakeJob_ implements asynchronous versions of the builtin
      6 commands in just a couple hundred lines of Vimscript.
      7 
      8 ## Goals
      9 
     10 1. Implement a minimal solution for asynchronous `:make` and `:grep`.
     11    No unnecessary features.
     12 2. Let Vim be Vim. Use `makeprg` and `errorformat` to configure
     13    `:MakeJob` and the analogous grep options for `:GrepJob`. Use the
     14    Quickfix or Location List window to view findings.
     15 3. Complete feature parity with `:make` and `:grep` per the steps
     16    outlined in `:help quickfix`. `autowrite`, `QuickFixCmdPre` and
     17    `QuickFixCmdPost`, and the bang operator work as expected.
     18 
     19 ## Requirements
     20 
     21 Vim compiled with `+job`, `+channel`, and of course `+quickfix`.
     22 
     23 ## Installation
     24 
     25 ### Arch Linux
     26 
     27 Arch Linux users can install system-wide through the `vim-makejob`
     28 package in the AUR, or on a per-user basis using any of the methods
     29 below.
     30 
     31 ### Pathogen
     32 
     33 `cd ~/.vim/bundle`
     34 `git clone https://git.danielmoch.com/vim-makejob.git`
     35 
     36 ### Plug.vim
     37 
     38 `Plug 'https://git.danielmoch.com/vim-makejob.git'`
     39 
     40 Most other plugin managers will resemble one of these two.
     41 
     42 ## Usage
     43 
     44 ### The Short Version
     45 
     46 Vim has `:make` and `:grep`. Replace those calls with `:MakeJob` and
     47 `:GrepJob`. A buffer will open showing the command output, which will
     48 be parsed into the Quickfix or LocationList window when the job
     49 completes. Bask in your newfound freedom to do as you please in Vim
     50 while _MakeJob_ runs.
     51 
     52 If _MakeJob_ reports findings, use `:copen` to view the Quickfix window
     53 (in the case of `:MakeJob`), and likewise `:lopen` to open the LocationList
     54 for `:LmakeJob`. If the current buffer is showing the output of a
     55 running MakeJob, or if it spawned a running MakeJob, then `<C-c>` stops
     56 it. There's also `:MakeJobStop` to stop an arbitrary MakeJob (with
     57 command completion).
     58 
     59 Speaking of `:LmakeJob`, all of the LocationList complements to the
     60 Quickfix commands are there with _MakeJob_, bringing the full list of
     61 commands to:
     62 
     63 - `:MakeJob`
     64 - `:MakeJobStop`
     65 - `:LmakeJob`
     66 - `:GrepJob`
     67 - `:LgrepJob`
     68 - `:GrepaddJob`
     69 - `:LgrepaddJob`
     70 
     71 All of which work like their builtin counterparts. Those last two are
     72 admittedly a bit longer than we would probably like, but if you grep a
     73 lot you'll probably want to set a mapping for it anyway (see below).
     74 
     75 ### The Less Short Version
     76 
     77 Users of Syntastic may not be aware that Vim offers many of the same
     78 features out of the box. Here's a brief rundown.
     79 
     80 With no prior configuration, `:make` will run the `make` program with no
     81 arguments, and populate the Quickfix list with any errors the process
     82 encounters. It's possible to change that behavior in one of two ways.
     83 The hard way is to manually use `:set makeprg` to change the program
     84 something else, and _then_ use `:set errorformat` to configure the
     85 format of the errors to look for. This gets pretty hairy, and so
     86 we're all better off trying to avoid this in favor of the easy way:
     87 compiler plugins. Using a compiler plugin easy (ex: `:compiler javac`),
     88 they abstract away the work of remembering the `errorformat`, they're
     89 extendable, and many are already included in Vim. _MakeJob_ uses the
     90 same compiler plugins users of Vim will be familiar with.
     91 
     92 It's also possible to use the`after/ftplugin` folder to automatically
     93 configure compilers on a per-file-type basis. An example of that trick
     94 would be to add the following to `~/.vim/after/ftplugin/python.vim`:
     95 
     96 `compiler pylint`
     97 
     98 Add that and you're good to go for Python files (assuming you have a
     99 pylint compiler which hey, if you need one I've [got you
    100 covered](/vim-runtime)).
    101 
    102 Additionally, if you'd like _MakeJob_ to run a linter automatically when
    103 you write a file, then something like the following in your `.vimrc`
    104 will to the trick.
    105 
    106 `autocmd! BufWritePost * :LmakeJob! %<CR>`
    107 
    108 For more granular control, you can set this trigger on a per-file-type
    109 basis with something like the following:
    110 
    111 `autocmd! BufWritePost *.py :LmakeJob! %<CR>`
    112 
    113 Grep is a powerful way to search through a directory structure for a
    114 keyword. I use it all the time, which is why I've added the following
    115 mapping to my `.vimrc`:
    116 
    117 `nnoremap <Leader>g :GrepJob!<Space>`
    118 
    119 Finally, if you find the preview windows distracting or otherwise
    120 disruptive to your workflow, you can hide it with the following, global
    121 setting:
    122 
    123 `let g:makejob_hide_preview_window = 1`
    124 
    125 ## Gotchas
    126 
    127 1. If `grepprg` is set to `'internal'`, then Vim uses its own builtin grep
    128    command. This still works when you call `:GrepJob`, but not
    129    asynchronously.
    130 2. For simplicity, only one instance of a given executable can run at
    131    once. You can run `make` and `pylint`, but you can't run two
    132    instances of `make` simultaneously.
    133 
    134 ## Vim Documentation
    135 
    136 Part of the goal of _MakeJob_ is to minimize the size of the plugin by
    137 using features Vim already offers whenever possible. To that end, if
    138 any of what foregoing discussion doesn't make sense, then take a look at
    139 the help documentation in Vim. Of particular interest will probably
    140 be the following:
    141 
    142 1. `:h make`
    143 2. `:h makeprg`
    144 3. `:h errorformat`
    145 4. `:h compiler`
    146 5. `:h quickfix`
    147 
    148 ## Contributing
    149 
    150 Pull requests are welcome, preferably via emailed output of `git
    151 request-pull` sent to the maintainer (see
    152 [here](https://www.git-scm.com/docs/git-request-pull) for more
    153 information).  Bug reports should also be directed to the maintainer via
    154 [email](daniel@danielmoch.com).
    155 
    156 If you aren't hosting a fork anywhere online, you can also send patches
    157 using `git format-patch` (see
    158 [here](https://www.git-scm.com/docs/git-format-patch)).
    159 
    160 ## License
    161 
    162 MIT - See the [LICENSE](/vim-makejob/tree/LICENSE) file for more information