*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|


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.

Cached file lists are never invalidated automatically, so to have probe
reflect new/deleted files clear the current cache by pressing <c-r> or <F5>
from within a probe window or with the :ProbeClearCache command.


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_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: