*probe.txt* For Vim version 7.3 *probe* CONTENTS *probe-contents* 1. Introduction |probe-intro| 2. Installation |probe-installation| 3. Usage |probe-usage| 4. Command Mappings |probe-command-mappings| 5. Prompt Mappings |probe-prompt-mappings| 6. Commands |probe-commands| 7. Acknowledgements |probe-acknowledgements| 8. License |probe-license| 9. Changelog |probe-changelog| INTRODUCTION *probe-intro* A pure-VimL fuzzy finder inspired by kien's ctrlp.vim and wincent's Command-T. INSTALLATION *probe-installation* 1. Install Tim Pope's pathogen plugin (https://github.com/tpope/vim-pathogen). 2. 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. 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 finder Adding 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 <C-p> Next match <C-n> Open selected match <Enter> Open in split <C-s> Open in vsplit <C-v> Open in new tab <C-t> Cancel <C-c> or <Esc>, if available Refresh cache <C-r> or <F5> Toggle persistence <C-y> Beginning of line <C-a> End of line <C-e> Delete to end of line <C-k> Delete to start of line <C-u> Delete previous word <C-w> Cursor right <C-f> or <Right> Cursor left <C-b> or <Left> Delete <Del> or <C-d> History backward <C-o> History forward <C-i> 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_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. CHANGELOG *probe-changelog* Still in alpha. The interface might still undergo significant changes. vim:tw=78:ts=8:ft=help:norl: