Note: This plugin works on Unix-based systems, but probably doesn't work on Windows.
The plugin exposes the command
:WritableSearch, which takes a search query
and performs a grep (or ack, or a different search command -- see the
Compatibility section), with that query. For example:
The results are opened in a new tab (by default), and are very similar to what you would get from performing the search on the command-line. The difference is that you can now edit this buffer and, upon writing, the original files will be updated with the changes.
This gives you a very simple and straightforward search-and-replace process. However, read this document to the end for some important gotchas.
If you change the filenames in the header blocks, those files will be renamed (with some manual confirmation that you can turn off if you're feeling adventurous). For example, if the header says:
and you change that to:
Then the file
foo/bar.txt will be renamed to
foo/renamed.txt. If this is
not possible, you'll get an error.
If you change the line numbers displayed in the headers, the virtual "window" that this search result is pointing to will reposition itself to those line numbers. For example, if the header says:
and you change that to:
Then the lines displayed will now be the ones from 10 to 22.
:Rerun defined in the search buffer can be used to perform the
last search again, with additional flags. For example:
:WritableSearch function_call\( :Rerun -C1
If you call the
:WritableSearch command with no arguments, it will take the
word under the cursor and search for that. If you call it while having marked
something in visual mode (with
:'<,'>WritableSearch), it will use the
current visual selection as the search query.
If you've already run any form of grep with the results loaded in the quickfix window, you can easily create a WritableSearch buffer with the contents of the quickfix list by running the
If you do this often, you might want to create a buffer-local mapping for quickfix buffers by editing the file
ftplugin/qf.vim and creating the mapping like so:
nnoremap <buffer> <leader>ws :WritableSearchFromQuickfix
Notice that each piece of code has been indented with a single extra space. This has been done to make parsing the results possible and you should never put anything in column 1 yourself.
You should never delete a result item yourself, or add new ones. The parser will get confused and error out.
By default, the plugin attempts to find the "best" search mechanism that can
work. It tries to use
git-grep if you're in a git directory,
the plugin is available, and so on. It falls back to
egrep as the final
This is encoded in the variable
g:writable_search_backends, which holds a
list of all the types of searches that will be attempted. See its documentation
for details, but here's a short summary of the possible items, in their default
git-grep, only in a git repository.
ack.vim, relying on the ack.vim plugin. This simply takes the
g:ackprgvariable and tries to re-use it. It may not work correctly depending on what you've set it to. It only works if the
g:ackprgvariable is detected.
ack, using the perl ack tool, only works if the tool is installed.
egrep, the last resort. Slow, but should always be present on a *nix system
So, if you want to use only
ack.vim and fall back to
egrep if the
program is not installed, you would put this in your
let g:writable_search_backends = ['ack.vim', 'egrep']
The plugin could also use
ag (or it could use
right now, there are some problems with it when dealing with matches at the
ends of files. It's recommended to stick to
If you want to plug in your own, potentially complicated search expression, and have the plugin make it writable for you, you can put the results in a buffer and invoke the parsing function directly:
This will try to parse the contents of the buffer and turn them into a writable_search buffer. However, the format must be the same as the output of grep with the options "-n/--line-number" and "-H/--with-filename". This looks like this:
<filename>-<line>-<text...> <filename>:<line>:<text with a match...> <filename>-<line>-<text...> -- <filename>:<line>:<text with a match...>
autoload/writable_search/proxy.vim-26-" to adjust next proxies. autoload/writable_search/proxy.vim:27:function! writable_search#proxy#UpdateSource(new_lines, adjustment) dict autoload/writable_search/proxy.vim-28- let new_lines = a:new_lines -- autoload/writable_search/parser.vim:1:function! writable_search#parser#Run() autoload/writable_search/parser.vim-2- let grouped_lines = s:PartitionLines(getbufline('%', 1, '$')) -- autoload/writable_search/parser.vim-25- for lines in a:grouped_lines autoload/writable_search/parser.vim:26: let current_proxy = writable_search#proxy#New(bufnr('%')) autoload/writable_search/parser.vim-27- let current_proxy.filename = s:FindFilename(lines)
The resulting writable_search buffer for this example would look like so:
autoload/writable_search/proxy.vim:26-28 " to adjust next proxies. function! writable_search#proxy#UpdateSource(new_lines, adjustment) dict let new_lines = a:new_lines autoload/writable_search/parser.vim:1-2 function! writable_search#parser#Run() let grouped_lines = s:PartitionLines(getbufline('%', 1, '$')) autoload/writable_search/parser.vim:25-27 for lines in a:grouped_lines let current_proxy = writable_search#proxy#New(bufnr('%')) let current_proxy.filename = s:FindFilename(lines)
Pull requests are welcome, but take a look at CONTRIBUTING.md first for some guidelines.