probe.txt For Vim version 7.3 probe
CONTENTS probe-contents
INTRODUCTION probe-intro
A pure-VimL fuzzy finder inspired by kien's ctrlp.vim and wincent's Command-T.
INSTALLATION probe-installation
Clone or download to $HOME/.vim/bundle:
$ git clone https://github.com/torbiak/probe.git ~/.vim/bundle/probe
USAGE probe-usage
probe caches the filepaths under Vim's current working directory or a VCS repository and offers an incremental search of that cache. When the number of matching filepaths is small enough they are ordered by a simple ranking algorithm that favours characters matching immediately after a path separator or another matched character, or at the beginning or end of a filepath. Because of this ranking algorithm the best approach to finding files using probe is to enter the first few characters of some path components as you work your way towards your target.
Subsequence search mode:
If the query doesn't contain any spaces, probe finds filepaths containing
the query as a subsequence. Thus, "ulmwhat" is a reasonable query to search
for /usr/local/man/whatis. Parts of a query can be separated by slashes to
make them match within one path component, eg "u/l/m/what". Slashes can
also be used to specify a minimum depth: "////what".Substring search mode:
If the query contains spaces, filepaths containing each space-delimited
substring are matched. Thus, 'loc man what' is also a very specific query
for /usr/local/man/whatis.Subsequence mode typically results in good results in fewer keystrokes, but when searching for a filepath containing common characters the extra specificity of substring mode can be useful.
Cached file lists are never invalidated automatically, so to have probe
reflect new/deleted files clear the current cache by pressing
COMMAND MAPPINGS probe-command-mappings
If mappings to the probe file and buffer finder commands aren't already defined the following will be:
<Leader>f open the file finder
<Leader>b open the buffer finderAdding a command like the following to vimrc can customize one of these mappings: >
nnoremap <silent> <Leader>f :Probe<CR><
PROMPT MAPPINGS probe-prompt-mappings
Previous match
Open selected match
Beginning of line or
NOTE: If c-s doesn't work your terminal might be eating it for flow control purposes. Consider disabling flow control (eg. stty -ixoff -ixon).
See |g:probe_mappings| for information on customizing these mappings.
COMMANDS probe-commands
|:Probe| :Probe Alias for |:ProbeFindFileInRepo|
|:ProbeFindFile| :ProbeFindFile Open the file finder, starting in the current working directory.
|:ProbeFindFileInRepo| :ProbeFindFileInRepo Open the file finder, starting in the first ancestor directory that contains a VCS metadirectory, or the current working directory if no metadirectories are found.
|:ProbeFindBuffer| :ProbeFindBuffer Open the buffer finder.
|:ProbeClearCache| :ProbeClearCache Delete the cache associated with the current definition of the Probe command.
OPTIONS probe-options
|g:probe_ignore_files| g:probe_ignore_files List of vim regexes. Files matching any of them are ignored when scanning directory trees and thus are never searched. Default: (list) []
|g:probe_cache_dir| g:probe_cache_dir Directory to store cached filepath lists in. If set to the empty string caches aren't saved to the filesystem. Default: (string) $HOME/.probe_cache
|g:probe_max_file_cache_size| g:probe_max_file_cache_size Maximum number of files to scan. Default: (number) 100000
|g:probe_cache_repo_branches| g:probe_cache_repo_branches If true, maintain separate caches for different branches of a repository. Works for git and mercurial so far. Default: (boolean) 1
|g:probe_max_height| g:probe_max_height Maximum height of the match window. Default: (number) 10
|g:probe_persist| g:probe_persist Persist the probe window after accepting a file by default. Persistence can still be toggled using the binding for toggle_persistence. Default: (boolean) 0
|g:probe_reverse_sort| g:probe_reverse_sort Reverse the sorting of scored matches, causing the best match to be at the top of the window. Default: (boolean) 0
|g:probe_sort_on_mtime| g:probe_sort_on_mtime Sort matches by their modification times, if they are files. Default: (boolean) 1
|g:probe_window_location| g:probe_window_location Location of the match window. Possible values are |leftabove|, |rightbelow|, |topleft|, and |botright|, but |topleft| and |botright| seem like the most sensible options. Default: (string) "botright"
|g:probe_scoring_threshold| g:probe_scoring_threshold Number of matches the search must be narrowed down to before the ranking algorithm will be applied. Default: (number) 400
This can be increased to give better results with shorter queries, but
character-wise scoring is slow in VimL and responsiveness may suffer. If
probe is stuttering while the last few characters of queries are being
entered, try decreasing the threshold.
The number of matches will be highlighted in the statusline until it is
below the scoring threshold, as a warning that the query needs to be more
specific.|g:probe_use_wildignore| g:probe_use_wildignore Use 'wildignore' when scanning for files. Default: (boolean) 0
g:probe_ignore_files still functions normally when this option is set.|g:probe_use_gitignore| g:probe_use_gitignore When in a git repository, ignore any file excluded by .gitignore (or other relevent exclude files) when scanning for files. Default: (boolean) 0
g:probe_ignore_files and g:probe_use_wildignore still function normally
when this option is set.|g:probe_mappings| g:probe_mappings Dict used to customize mappings. If a mapping is given for some operation the default mapping will not be created. Default: (dict) {}
For example, to map select_next/select_prev to <c-j>/<c-k>, put the
following in vimrc: >
let g:probe_mappings = {'select_next': '<c-j>', 'select_prev': '<c-k>'}< To map multiple keys to an operation specify a list: >
let g:probe_mappings = {'select_next': ['<c-j>', '<c-n>']}<
Available operations:
select_next default: <c-n>
select next match in the match window
select_prev default: <c-p>
select previous match in the match window
accept default: <enter>
open the selected match in the current window
accept_split default: <c-s>
open the selected match in a horizontally split window
accept_vsplit default: <c-v>
open the selected match in a vertically split window
accept_tab default: <c-t>
open the selected match in a new tab
refresh_cache default: <c-r>, <f5>
delete the current cache and rescan for candidates
cancel default: <c-c>, <esc> (when available)
close probe
backspace default: <bs>
delete the previous characater
backspace_word default: <c-w>
delete the previous word
delete default: <c-d>
delete the character under the cursor
delete_to_start default: <c-u>
delete all characters between the cursor and the start of the line
delete_to_end default: <c-k>
delete all characters between the cursor the end of the line
cursor_start default: <c-a>
move the cursor to the start of the line
cursor_end default: <c-e>
move the cursor to the end of the line
cursor_left default: <c-b>
move the cursor back one character
cursor_right default: <c-f>
move the cursor forward one character
history_backward default: <c-o>
set query to older history entry
history_forward default: <c-i>
set query to newer history entry
toggle_persistence default: <c-y>
leave the probe window open after accepting a file. Useful for opening
a number of files that match the same query.ACKNOWLEDGEMENTS probe-acknowledgements
Mad props to wincent for Command-T. It's a great plugin and his code is super-clean. It was a huge help while I was figuring out how to structure things. Thanks to kien as well for his pure VimL fuzzy finder, ctrlp.vim, which gave me a bunch of ideas for how to make matching and scoring responsive without resorting to C.
Greetz fly out to Oscar and line6 for their help during design and testing, and to Ryan and Stephane for their continued feedback.
LICENSE probe-license
Copyright (c) 2012 Jordan Torbiak
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
vim:tw=78:ts=8:ft=help:norl: