Mercurial > public > dotfiles
diff vim/vimfiles/bundle/ctrlp.vim/doc/ctrlp.txt @ 7:86e0ac713642
Re-added the latest ctrlp.vim plugin.
The ctrlp.vim commit was e61e7d5b801ade5fcefeab3aca75c1f37d54bdf1.
| author | Brian Neal <bgneal@gmail.com> |
|---|---|
| date | Sun, 29 Apr 2012 16:20:31 -0500 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/vim/vimfiles/bundle/ctrlp.vim/doc/ctrlp.txt Sun Apr 29 16:20:31 2012 -0500 @@ -0,0 +1,1113 @@ +*ctrlp.txt* Fuzzy file, buffer, mru and tag finder. v1.7.6 +*CtrlP* *ControlP* *'ctrlp'* *'ctrl-p'* +=============================================================================== +# # +# :::::::: ::::::::::: ::::::::: ::: ::::::::: # +# :+: :+: :+: :+: :+: :+: :+: :+: # +# +:+ +:+ +:+ +:+ +:+ +:+ +:+ # +# +#+ +#+ +#++:++#: +#+ +#++:++#+ # +# +#+ +#+ +#+ +#+ +#+ +#+ # +# #+# #+# #+# #+# #+# #+# #+# # +# ######## ### ### ### ########## ### # +# # +=============================================================================== +CONTENTS *ctrlp-contents* + + 1. Intro........................................|ctrlp-intro| + 2. Options......................................|ctrlp-options| + 3. Commands.....................................|ctrlp-commands| + 4. Mappings.....................................|ctrlp-mappings| + 5. Input Formats................................|ctrlp-input-formats| + 6. Extensions...................................|ctrlp-extensions| + +=============================================================================== +INTRO *ctrlp-intro* + +Full path fuzzy file, buffer, mru and tag finder with an intuitive interface. +Written in pure Vimscript for MacVim and Vim version 7.0+. Has full support for +Vim’s |regexp| as search pattern, built-in MRU files monitoring, project’s root +finder, and more. + +To enable optional extensions (tag, dir, rtscript...), see |ctrlp-extensions|. + +=============================================================================== +OPTIONS *ctrlp-options* + +Overview:~ + + |loaded_ctrlp| Disable the plugin. + |ctrlp_map| Default mapping. + |ctrlp_cmd| Default command used for the default mapping. + |ctrlp_by_filename| Default to filename mode or not. + |ctrlp_regexp| Default to regexp mode or not. + |ctrlp_match_window_bottom| Where to show the match window. + |ctrlp_match_window_reversed| Sort order in the match window. + |ctrlp_max_height| Max height of the match window. + |ctrlp_switch_buffer| Jump to an open buffer if already opened. + |ctrlp_reuse_window| Reuse special windows (help, quickfix, etc). + |ctrlp_working_path_mode| How to set CtrlP’s local working directory. + |ctrlp_root_markers| Additional, high priority root markers. + |ctrlp_use_caching| Use per-session caching or not. + |ctrlp_clear_cache_on_exit| Keep cache after exiting Vim or not. + |ctrlp_cache_dir| Location of the cache directory. + |ctrlp_dotfiles| Ignore dotfiles and dotdirs or not. + |ctrlp_custom_ignore| Hide stuff when using |globpath()|. + |ctrlp_max_files| Number of files to scan initially. + |ctrlp_max_depth| Directory depth to recurse into when scanning. + |ctrlp_user_command| Use an external scanner. + |ctrlp_max_history| Number of entries saved in the prompt history. + |ctrlp_open_new_file| How to open a file created by <c-y>. + |ctrlp_open_multiple_files| How to open files selected by <c-z>. + |ctrlp_arg_map| Intercept <c-y> and <c-o> or not. + |ctrlp_follow_symlinks| Follow symbolic links or not. + |ctrlp_lazy_update| Only update when typing has stopped. + |ctrlp_default_input| Seed the prompt with an initial string. + |ctrlp_use_migemo| Use Migemo patterns for Japanese filenames. + |ctrlp_prompt_mappings| Change the mappings in the prompt. + + MRU mode: + |ctrlp_mruf_max| Max MRU entries to remember. + |ctrlp_mruf_exclude| Files that shouldn’t be remembered. + |ctrlp_mruf_include| Files to be remembered. + |ctrlp_mruf_relative| Show only MRU files in the working directory. + |ctrlp_mruf_default_order| Disable sorting. + |ctrlp_mruf_case_sensitive| MRU files are case sensitive or not. + + Advanced options: + |ctrlp_status_func| Change CtrlP’s two statuslines. + |ctrlp_buffer_func| Call custom functions in the CtrlP buffer. + |ctrlp_match_func| Replace the built-in matching algorithm. + +------------------------------------------------------------------------------- +Detailed descriptions and default values:~ + + *'g:ctrlp_map'* +Use this option to change the mapping to invoke CtrlP in |Normal| mode: > + let g:ctrlp_map = '<c-p>' +< + + *'g:ctrlp_cmd'* +Set the default opening command to use when pressing the above mapping: > + let g:ctrlp_cmd = 'CtrlP' +< + + *'g:loaded_ctrlp'* +Use this to disable the plugin completely: > + let g:loaded_ctrlp = 1 +< + + *'g:ctrlp_by_filename'* +Set this to 1 to set searching by filename (as opposed to full path) as the +default: > + let g:ctrlp_by_filename = 0 +< +Can be toggled on/off by pressing <c-d> inside the prompt. + + *'g:ctrlp_regexp'* +Set this to 1 to set regexp search as the default: > + let g:ctrlp_regexp = 0 +< +Can be toggled on/off by pressing <c-r> inside the prompt. + + *'g:ctrlp_match_window_bottom'* +Set this to 0 to show the match window at the top of the screen: > + let g:ctrlp_match_window_bottom = 1 +< + + *'g:ctrlp_match_window_reversed'* +Change the listing order of the files in the match window. The default setting +(1) is from bottom to top: > + let g:ctrlp_match_window_reversed = 1 +< + + *'g:ctrlp_max_height'* +Set the maximum height of the match window: > + let g:ctrlp_max_height = 10 +< + + *'g:ctrlp_switch_buffer'* +When opening a file with <cr> or <c-t>, if the file’s already opened somewhere +CtrlP will try to jump to it instead of opening a new instance: > + let g:ctrlp_switch_buffer = 2 +< + 1 - only jump to the buffer if it’s opened in the current tab. + 2 - jump tab as well if the buffer’s opened in another tab. + 0 - disable this feature. + + *'g:ctrlp_reuse_window'* +When opening a file with <cr>, CtrlP avoids opening it in windows created by +plugins, help and quickfix. Use this to setup some exceptions: > + let g:ctrlp_reuse_window = 'netrw' +< +Acceptable values are partial name, filetype or buftype of the special buffers. +Use regexp to specify the pattern. +Example: > + let g:ctrlp_reuse_window = 'netrw\|help\|quickfix' +< + + *'g:ctrlp_working_path_mode'* +When starting up, CtrlP sets its local working directory according to this +variable: > + let g:ctrlp_working_path_mode = 2 +< + 1 - the parent directory of the current file. + 2 - the nearest ancestor that contains one of these directories or files: + .git/ .hg/ .svn/ .bzr/ _darcs/ + 0 - don’t manage working directory. +Note: you can use b:ctrlp_working_path_mode (a |b:var|) to set this option on a +per buffer basis. + + *'g:ctrlp_root_markers'* +Use this to set your own root markers in addition to the default ones (.git/, +.hg/, .svn/, .bzr/, and _darcs/). Your markers will take precedence: > + let g:ctrlp_root_markers = [''] +< + + *'g:ctrlp_use_caching'* +Set this to 0 to disable per-session caching. When disabled, caching will still +be enabled for directories that have more than 4000 files: > + let g:ctrlp_use_caching = 1 +< +Note: you can quickly purge the cache by pressing <F5> while inside CtrlP. + + *'g:ctrlp_clear_cache_on_exit'* +Set this to 0 to enable cross-session caching by not deleting the cache files +upon exiting Vim: > + let g:ctrlp_clear_cache_on_exit = 1 +< + + *'g:ctrlp_cache_dir'* +Set the directory to store the cache files: > + let g:ctrlp_cache_dir = $HOME.'/.cache/ctrlp' +< + + *'g:ctrlp_dotfiles'* +Set this to 0 if you don’t want CtrlP to scan for dotfiles and dotdirs: > + let g:ctrlp_dotfiles = 1 +< +You can use |'wildignore'| to exclude anything from the search. +Examples: > + " Excluding version control directories + set wildignore+=*/.git/*,*/.hg/*,*/.svn/* " Linux/MacOSX + set wildignore+=.git\*,.hg\*,.svn\* " Windows +< +Note #1: the `*/` in front of each directory glob is required. + +Note #2: |wildignore| influences the result of |expand()|, |globpath()| and +|glob()| which many plugins use to find stuff on the system (e.g. VCS related +plugins look for .git/, .hg/,... some other plugins look for external *.exe +tools on Windows). So be a little mindful of what you put in your |wildignore|. + + *'g:ctrlp_custom_ignore'* +In addition to |'wildignore'|, use this for files and directories you want only +CtrlP to not show. Use regexp to specify the patterns: > + let g:ctrlp_custom_ignore = '' +< +Examples: > + let g:ctrlp_custom_ignore = '\.git$\|\.hg$\|\.svn$' + let g:ctrlp_custom_ignore = { + \ 'dir': '\.git$\|\.hg$\|\.svn$', + \ 'file': '\.exe$\|\.so$\|\.dll$', + \ 'link': 'SOME_BAD_SYMBOLIC_LINKS', + \ } +< +Note: ignoring only works when |globpath()| is used to scan for files. + + *'g:ctrlp_max_files'* +The maximum number of files to scan, set to 0 for no limit: > + let g:ctrlp_max_files = 10000 +< + + *'g:ctrlp_max_depth'* +The maximum depth of a directory tree to recurse into: > + let g:ctrlp_max_depth = 40 +< +Note: the larger these values, the more memory Vim uses. + + *'g:ctrlp_user_command'* +Specify an external tool to use for listing files instead of using Vim’s +|globpath()|. Use %s in place of the target directory: > + let g:ctrlp_user_command = '' +< +Examples: > + let g:ctrlp_user_command = 'find %s -type f' " MacOSX/Linux + let g:ctrlp_user_command = 'dir %s /-n /b /s /a-d' " Windows +< +You can also use 'grep', 'findstr' or something else to filter the results. +Examples: > + let g:ctrlp_user_command = 'find %s -type f | grep (?!tmp/.*)' + let g:ctrlp_user_command = 'dir %s /-n /b /s /a-d | findstr .*\.py$' +< +Use a version control listing command when inside a repository, this is faster +when scanning large projects: > + let g:ctrlp_user_command = [root_marker, listing_command, fallback_command] + let g:ctrlp_user_command = { + \ 'types': { + \ 1: [root_marker_1, listing_command_1], + \ n: [root_marker_n, listing_command_n], + \ }, + \ 'fallback': fallback_command + \ } +< +Examples: > + let g:ctrlp_user_command = ['.git/', 'cd %s && git ls-files'] + let g:ctrlp_user_command = ['.hg/', 'hg --cwd %s locate -I .'] + let g:ctrlp_user_command = { + \ 'types': { + \ 1: ['.git/', 'cd %s && git ls-files'], + \ 2: ['.hg/', 'hg --cwd %s locate -I .'], + \ }, + \ 'fallback': 'find %s -type f' + \ } +< +If the fallback_command is empty or not defined, |globpath()| will then be used +when searching outside a repo. + + *'g:ctrlp_max_history'* +The maximum number of input strings you want CtrlP to remember. The default +value mirrors Vim’s global |'history'| option: > + let g:ctrlp_max_history = &history +< +Set to 0 to disable prompt’s history. Browse the history with <c-n> and <c-p>. + + *'g:ctrlp_open_new_file'* +Use this option to specify how the newly created file is to be opened when +pressing <c-y>: + t - in a new tab + h - in a new horizontal split + v - in a new vertical split + r - in the current window +> + let g:ctrlp_open_new_file = 'v' +< + + *'g:ctrlp_open_multiple_files'* +If non-zero, this will enable opening multiple files with <c-z> and <c-o>: > + let g:ctrlp_open_multiple_files = 'v' +< +Example: > + let g:ctrlp_open_multiple_files = '2vr' +< +For the number: + - If given, it’ll be used as the maximum number of windows or tabs to create + when opening the files (the rest will be opened as hidden buffers). + - If not given, <c-o> will open all files, each in a new window or new tab. +For the letters: + t - each file in a new tab. + h - each file in a new horizontal split. + v - each file in a new vertical split. + Reuse the current window: + tr, + hr, + vr - open the first file in the current window, then the remaining files in + new splits or new tabs just like with t, h, v. + + *'g:ctrlp_arg_map'* +When this is set to 1, the <c-o> and <c-y> mappings will accept one extra key +as an argument to override their default behavior: > + let g:ctrlp_arg_map = 0 +< +Pressing <c-o> or <c-y> will then prompt for a keypress. The key can be: + t - open in tab(s) + h - open in horizontal split(s) + v - open in vertical split(s) + r - open in current window (for <c-y> only) + <esc>, <c-c>, <c-g> - cancel and go back to the prompt. + <cr> - use the default behavior specified with |g:ctrlp_open_new_file| and + |g:ctrlp_open_multiple_files|. + + *'g:ctrlp_follow_symlinks'* +Set this to 1 to follow symbolic links when listing files: > + let g:ctrlp_follow_symlinks = 0 +< +When enabled, looped internal symlinks will be ignored to avoid duplicates. + + *'g:ctrlp_lazy_update'* +Set this to 1 to enable the lazy-update feature: only update the match window +after typing’s been stopped for a certain amount of time: > + let g:ctrlp_lazy_update = 0 +< +If is 1, update after 250ms. If bigger than 1, the number will be used as the +delay time in milliseconds. + + *'g:ctrlp_default_input'* +Set this to 1 to enable seeding the prompt with the current file’s relative +path: > + let g:ctrlp_default_input = 0 +< + + *'g:ctrlp_use_migemo'* +Set this to 1 to use Migemo Pattern for Japanese filenames. Migemo Search only +works in regexp mode. To split the pattern, separate words with space: > + let g:ctrlp_use_migemo = 0 +< + + *'g:ctrlp_prompt_mappings'* +Use this to customize the mappings inside CtrlP’s prompt to your liking. You +only need to keep the lines that you’ve changed the values (inside []): > + let g:ctrlp_prompt_mappings = { + \ 'PrtBS()': ['<bs>', '<c-]>'], + \ 'PrtDelete()': ['<del>'], + \ 'PrtDeleteWord()': ['<c-w>'], + \ 'PrtClear()': ['<c-u>'], + \ 'PrtSelectMove("j")': ['<c-j>', '<down>'], + \ 'PrtSelectMove("k")': ['<c-k>', '<up>'], + \ 'PrtSelectMove("t")': ['<Home>', '<kHome>'], + \ 'PrtSelectMove("b")': ['<End>', '<kEnd>'], + \ 'PrtSelectMove("u")': ['<PageUp>', '<kPageUp>'], + \ 'PrtSelectMove("d")': ['<PageDown>', '<kPageDown>'], + \ 'PrtHistory(-1)': ['<c-n>'], + \ 'PrtHistory(1)': ['<c-p>'], + \ 'AcceptSelection("e")': ['<cr>', '<2-LeftMouse>'], + \ 'AcceptSelection("h")': ['<c-x>', '<c-cr>', '<c-s>'], + \ 'AcceptSelection("t")': ['<c-t>'], + \ 'AcceptSelection("v")': ['<c-v>', '<RightMouse>'], + \ 'ToggleFocus()': ['<s-tab>'], + \ 'ToggleRegex()': ['<c-r>'], + \ 'ToggleByFname()': ['<c-d>'], + \ 'ToggleType(1)': ['<c-f>', '<c-up>'], + \ 'ToggleType(-1)': ['<c-b>', '<c-down>'], + \ 'PrtExpandDir()': ['<tab>'], + \ 'PrtInsert("c")': ['<MiddleMouse>', '<insert>'], + \ 'PrtInsert()': ['<c-\>'], + \ 'PrtCurStart()': ['<c-a>'], + \ 'PrtCurEnd()': ['<c-e>'], + \ 'PrtCurLeft()': ['<c-h>', '<left>', '<c-^>'], + \ 'PrtCurRight()': ['<c-l>', '<right>'], + \ 'PrtClearCache()': ['<F5>'], + \ 'PrtDeleteEnt()': ['<F7>'], + \ 'CreateNewFile()': ['<c-y>'], + \ 'MarkToOpen()': ['<c-z>'], + \ 'OpenMulti()': ['<c-o>'], + \ 'PrtExit()': ['<esc>', '<c-c>', '<c-g>'], + \ } +< +Note: In some terminals, it’s not possible to remap <c-h> without also changing +<bs> (|keycodes|). So if pressing <bs> moves the cursor to the left instead of +deleting a char for you, add this to your |.vimrc| to disable the plugin’s +default <c-h> mapping: > + let g:ctrlp_prompt_mappings = { 'PrtCurLeft()': ['<left>', '<c-^>'] } +< + +---------------------------------------- +MRU mode options:~ + + *'g:ctrlp_mruf_max'* +Specify the number of recently opened files you want CtrlP to remember: > + let g:ctrlp_mruf_max = 250 +< + + *'g:ctrlp_mruf_exclude'* +Files you don’t want CtrlP to remember. Use regexp to specify the patterns: > + let g:ctrlp_mruf_exclude = '' +< +Examples: > + let g:ctrlp_mruf_exclude = '/tmp/.*\|/temp/.*' " MacOSX/Linux + let g:ctrlp_mruf_exclude = '^C:\\dev\\tmp\\.*' " Windows +< + + *'g:ctrlp_mruf_include'* +And if you want CtrlP to only remember some files, specify them here: > + let g:ctrlp_mruf_include = '' +< +Example: > + let g:ctrlp_mruf_include = '\.py$\|\.rb$' +< + + *'g:ctrlp_mruf_relative'* +Set this to 1 to show only MRU files in the current working directory: > + let g:ctrlp_mruf_relative = 0 +< + + *'g:ctrlp_mruf_default_order'* +Set this to 1 to disable sorting when searching in MRU mode: > + let g:ctrlp_mruf_default_order = 0 +< + + *'g:ctrlp_mruf_case_sensitive'* +Match this with your file system case-sensitivity setting to avoid duplicate +MRU entries: > + let g:ctrlp_mruf_case_sensitive = 1 +< + +---------------------------------------- +Advanced options:~ + + *'g:ctrlp_status_func'* +Use this to customize the statuslines for the CtrlP window: > + let g:ctrlp_status_func = {} +< +Example: > + let g:ctrlp_status_func = { + \ 'main': 'Function_Name_1', + \ 'prog': 'Function_Name_2', + \ } +< +Structure of the functions: > + " Main statusline + function! Function_Name_1(focus, byfname, regex, prev, item, next, marked) + " Arguments: + " | + " +- a:focus : The focus of the prompt: "prt" or "win". + " | + " +- a:byfname : In filename mode or in full path mode: "file" or "path". + " | + " +- a:regex : In regex mode: 1 or 0. + " | + " +- a:prev : The previous search mode. + " | + " +- a:item : The current search mode. + " | + " +- a:next : The next search mode. + " | + " +- a:marked : The number of marked files, or a comma separated list of + " the filenames. + + return full_statusline + endfunction + + " Progress statusline + function! Function_Name_2(str) + " a:str : Either the number of files scanned so far, or a string indicating + " the current directory is being scanned with a user_command. + + return full_statusline + endfunction +< +See https://gist.github.com/1610859 for a working example. + + *'g:ctrlp_buffer_func'* +Specify the functions that will be called after entering and before exiting the +CtrlP buffer: > + let g:ctrlp_buffer_func = {} +< +Example: > + let g:ctrlp_buffer_func = { + \ 'enter': 'Function_Name_1', + \ 'exit': 'Function_Name_2', + \ } +< + + *'g:ctrlp_match_func'* +Set an external fuzzy matching function for CtrlP to use: > + let g:ctrlp_match_func = {} +< +Example: > + let g:ctrlp_match_func = { 'match': 'Function_Name' } +< +Structure of the function: > + function! Function_Name(items, str, limit, mmode, ispath, crfile, regex) + " Arguments: + " | + " +- a:items : The full list of items to search in. + " | + " +- a:str : The string entered by the user. + " | + " +- a:limit : The max height of the match window. Can be used to limit + " | the number of items to return. + " | + " +- a:mmode : The match mode. Can be one of these strings: + " | + "full-line": match the entire line. + " | + "filename-only": match only the filename. + " | + "first-non-tab": match until the first tab char. + " | + "until-last-tab": match until the last tab char. + " | + " +- a:ispath : Is 1 when searching in file, buffer, mru, dir, and rtscript + " | modes. Is 0 otherwise. + " | + " +- a:crfile : The file in the current window. Should be excluded from the + " | results when a:ispath == 1. + " | + " +- a:regex : In regex mode: 1 or 0. + + return list_of_matched_items + endfunction +< + +=============================================================================== +COMMANDS *ctrlp-commands* + + *:CtrlP* +:CtrlP [starting-directory] + Open CtrlP in find file mode. + + If no argument is given, the value of |g:ctrlp_working_path_mode| will be + used to determine the starting directory. + You can use <tab> to auto-complete the [starting-directory] when typing it. + + *:CtrlPBuffer* +:CtrlPBuffer + Open CtrlP in find buffer mode. + + *:CtrlPMRU* +:CtrlPMRU + Open CtrlP in find Most-Recently-Used file mode. + + *:CtrlPLastMode* +:CtrlPLastMode + Open CtrlP in the last mode used. + + *:CtrlPRoot* +:CtrlPRoot + This acts like |:CtrlP| with |g:ctrlp_working_path_mode| = 2 (ignores its + current value). + + *:CtrlPClearCache* +:CtrlPClearCache + Flush the cache for the current working directory. The same as pressing <F5> + inside CtrlP. + To enable or disable caching, use the |g:ctrlp_use_caching| option. + + *:CtrlPClearAllCaches* +:CtrlPClearAllCaches + Delete all the cache files saved in |g:ctrlp_cache_dir|. + +------------------------------------------------------------------------------- +For commands provided by bundled extensions, see |ctrlp-extensions|. + +=============================================================================== +MAPPINGS *ctrlp-mappings* + + *'ctrlp-<c-p>'* +<c-p> + Default |Normal| mode mapping to open the CtrlP prompt in find file mode. + +Once inside the prompt:~ + + <c-d> + Toggle between full-path search and filename only search. + Note: in filename mode, the prompt’s base is '>d>' instead of '>>>' + + <c-r> *'ctrlp-fullregexp'* + Toggle between the string mode and full regexp mode. + Note: in full regexp mode, the prompt’s base is 'r>>' instead of '>>>' + + See also |input-formats| (guide) and |g:ctrlp_regexp_search| (option). + + <c-f>, 'forward' + <c-up> + Scroll to the 'next' search mode in the sequence. + + <c-b>, 'backward' + <c-down> + Scroll to the 'previous' search mode in the sequence. + + <tab> + Auto-complete directory names under the current working directory inside + the prompt. + + <s-tab> + Toggle the focus between the match window and the prompt. + + <c-j>, + <down> + Move selection down. + + <c-k>, + <up> + Move selection up. + + <c-a> + Move the cursor to the 'start' of the prompt. + + <c-e> + Move the cursor to the 'end' of the prompt. + + <c-h>, + <left>, + <c-^> + Move the cursor one character to the 'left'. + + <c-l>, + <right> + Move the cursor one character to the 'right'. + + <c-]>, + <bs> + Delete the preceding character. + + <del> + Delete the current character. + + <c-w> + Delete a preceding inner word. + + <c-u> + Clear the input field. + + <cr> + Open selected file in the active window if possible. + + <c-t> + Open selected file in a new 'tab' after the last tabpage. + + <c-v> + Open selected file in a 'vertical' split. + + <c-x>, + <c-cr>, + <c-s> + Open selected file in a 'horizontal' split. + + <c-y> + Create a new file and its parent directories. + + <c-n> + Next string in the prompt’s history. + + <c-p> + Previous string in the prompt’s history. + + <c-z> + - Mark/unmark a file to be opened with <c-o>. + - Or mark/unmark a file to create a new file in its directory using <c-y>. + + <c-o> + Open files marked by <c-z>. + + <F5> + - Refresh the match window and purge the cache for the current directory. + - Or remove deleted files from the MRU list. + + <F7> + - Wipe the MRU list. + - Or delete MRU entries marked by <c-z>. + + <insert> + Insert the word under the cursor (in the current buffer) into the prompt. + + <esc>, + <c-c>, + <c-g> + Exit CtrlP. + Note: <c-c> can also be used to stop the scan if it’s taking too long. + +Choose your own mappings with |g:ctrlp_prompt_mappings|. + +When inside the match window (press <s-tab> to switch):~ + + a-z + 0-9 + ~^-=;`',.+!@#$%&_(){}[] + Cycle through the lines with the first letter (of paths or filenames) that + matches that key. + +=============================================================================== +INPUT FORMATS *ctrlp-input-formats* + +Formats for inputting in the prompt:~ + +a) Simple string. + + E.g. 'abc' is understood internally as 'a[^a]\{-}b[^b]\{-}c' + +b) When in regexp mode, the input string’s treated as a Vim’s regexp |pattern| + without any modification. + + E.g. 'abc\d*efg' will be read as 'abc\d*efg'. + + See |ctrlp-fullregexp| (keymap) and |g:ctrlp_regexp_search| (option) for + how to enable regexp mode. + +c) End the string with a colon ':' followed by a Vim command to execute that + command after opening the file. If you need to use ':' literally, escape it + with a backslash: '\:'. When opening multiple files, the command will be + executed on each opening file. + + E.g. 'abc:45' will open the selected file and jump to line 45. + + 'abc:/any\:string' will open the selected file and jump to the first + instance of 'any:string'. + + 'abc:+setf\ myfiletype|50' will open the selected file and set its + filetype to 'myfiletype', then jump to line 50. + + 'abc:diffthis' will open the selected files and run |:diffthis| on the + first 4 files (if marked). + + See also Vim’s |++opt| and |+cmd|. + +d) Type exactly two dots '..' at the start of the prompt and press enter to go + backward in the directory tree by 1 level. If the parent directory is + large, this might be slow. + +e) Similarly, submit '/' or '\' to find and go to the project’s root. If the + project is large, using a VCS listing command to look for files might help + speeding up the intial scan (see |g:ctrlp_user_command| for more details). + + Note: e) and d) only work in find file mode and directory mode. + +f) Type the name of a non-existent file and press <c-y> to create it. Mark a + file with <c-z> to create the new file in the same directory as the marked + file. + + E.g. 'parentdir/newfile.txt' will create a directory named 'parentdir' as + well as 'newfile.txt'. + + If 'some/old/dirs/oldfile.txt' is marked with <c-z>, then 'parentdir' + and 'newfile.txt' will be created in 'some/old/dirs'. The final path + will then be 'some/old/dirs/parentdir/newfile.txt'. + + Use '\' in place of '/' on Windows (if |'ssl'| is not set). + +g) Submit ? to open this help file. + +=============================================================================== +EXTENSIONS *ctrlp-extensions* + +Extensions are optional. To enable an extension, add its name to the variable +g:ctrlp_extensions: > + let g:ctrlp_extensions = ['tag', 'buffertag', 'quickfix', 'dir', 'rtscript', + \ 'undo', 'line', 'changes', 'mixed', 'bookmarkdir'] +< +The order of the items will be the order they appear on the statusline and when +using <c-f>, <c-b>. + +Available extensions:~ + + *:CtrlPTag* + * Tag mode:~ + - Name: 'tag' + - Command: ':CtrlPTag' + - Search for a tag within a generated central tags file, and jump to the + definition. Use the Vim’s option |'tags'| to specify the names and the + locations of the tags file(s). + E.g. set tags+=doc/tags + + *:CtrlPBufTag* + *:CtrlPBufTagAll* + * Buffer Tag mode:~ + - Name: 'buffertag' + - Commands: ':CtrlPBufTag [buffer]', + ':CtrlPBufTagAll'. + - Search for a tag within the current buffer or all listed buffers and jump + to the definition. Requires |exuberant_ctags| or compatible programs. + + *:CtrlPQuickfix* + * Quickfix mode:~ + - Name: 'quickfix' + - Command: ':CtrlPQuickfix' + - Search for an entry in the current quickfix errors and jump to it. + + *:CtrlPDir* + * Directory mode:~ + - Name: 'dir' + - Command: ':CtrlPDir [starting-directory]' + - Search for a directory and change the working directory to it. + - Mappings: + + <cr> change the local working directory for CtrlP and keep it open. + + <c-t> change the global working directory (exit). + + <c-v> change the local working directory for the current window (exit). + + <c-x> change the global working directory to CtrlP’s current local + working directory (exit). + + *:CtrlPRTS* + * Runtime script mode:~ + - Name: 'rtscript' + - Command: ':CtrlPRTS' + - Search for files (vimscripts, docs, snippets...) in runtimepath. + + *:CtrlPUndo* + * Undo mode:~ + - Name: 'undo' + - Command: ':CtrlPUndo' + - Browse undo history. + + *:CtrlPLine* + * Line mode:~ + - Name: 'line' + - Command: ':CtrlPLine' + - Search for a line in all listed buffers. + + *:CtrlPChange* + *:CtrlPChangeAll* + * Change list mode:~ + - Name: 'changes' + - Commands: ':CtrlPChange [buffer]', + ':CtrlPChangeAll'. + - Search for and jump to a recent change in the current buffer or in all + listed buffers. + + *:CtrlPMixed* + * Mixed mode:~ + - Name: 'mixed' + - Command: ':CtrlPMixed' + - Search in files, buffers and MRU files at the same time. + + *:CtrlPBookmarkDir* + *:CtrlPBookmarkDirAdd* + * BookmarkDir mode:~ + - Name: 'bookmarkdir' + - Commands: ':CtrlPBookmarkDir', + ':CtrlPBookmarkDirAdd [directory]'. + - Search for a bookmarked directory and change the working directory to it. + - Mappings: + + <cr> change the local working directory for CtrlP, keep it open and + switch to find file mode. + + <c-x> change the global working directory (exit). + + <c-v> change the local working directory for the current window (exit). + + <F7> + - Wipe bookmark list. + - Or delete entries marked by <c-z>. + +---------------------------------------- +Buffer Tag mode options:~ + + *'g:ctrlp_buftag_ctags_bin'* +If ctags isn’t in your $PATH, use this to set its location: > + let g:ctrlp_buftag_ctags_bin = '' +< + + *'g:ctrlp_buftag_systemenc'* +Match this with your OS’s encoding (not Vim’s). The default value mirrors Vim’s +global |'encoding'| option: > + let g:ctrlp_buftag_systemenc = &encoding +< + + *'g:ctrlp_buftag_types'* +Use this to set the arguments for ctags, jsctags... for a given filetype: > + let g:ctrlp_buftag_types = '' +< +Examples: > + let g:ctrlp_buftag_types = { + \ 'erlang' : '--language-force=erlang --erlang-types=drmf', + \ 'javascript' : { + \ 'bin': 'jsctags', + \ 'args': '-f -', + \ }, + \ } +< + +=============================================================================== +CUSTOMIZATION *ctrlp-customization* + +Highlighting:~ + * For the CtrlP buffer: + CtrlPNoEntries : the message when no match is found (Error) + CtrlPMatch : the matched pattern (Identifier) + CtrlPLinePre : the line prefix '>' in the match window + CtrlPPrtBase : the prompt’s base (Comment) + CtrlPPrtText : the prompt’s text (|hl-Normal|) + CtrlPPrtCursor : the prompt’s cursor when moving over the text (Constant) + + * In extensions: + CtrlPTabExtra : the part of each line that’s not matched against (Comment) + CtrlPBufName : the buffer name an entry belongs to (|hl-Directory|) + CtrlPTagKind : the kind of the tag in buffer-tag mode (|hl-Title|) + CtrlPqfLineCol : the line and column numbers in quickfix mode (Comment) + CtrlPUndoT : the elapsed time in undo mode (|hl-Directory|) + CtrlPUndoBr : the square brackets [] in undo mode (Comment) + CtrlPUndoNr : the undo number inside [] in undo mode (String) + CtrlPUndoSv : the point where the file was saved (Comment) + CtrlPUndoPo : the current position in the undo tree (|hl-Title|) + CtrlPBookmark : the name of the bookmark (Identifier) + +Statuslines:~ + * Highlight groups: + CtrlPMode1 : 'prt' or 'win', also for 'regex' (Character) + CtrlPMode2 : 'file' or 'path', also for the local working dir (|hl-LineNr|) + CtrlPStats : the scanning status (Function) + + For rebuilding the statuslines, see |g:ctrlp_status_func|. + +=============================================================================== +MISCELLANEOUS CONFIGS *ctrlp-miscellaneous-configs* + +* Use |wildignore| for |g:ctrlp_user_command|: +> + function! s:wig2cmd() + " Change wildignore into space or | separated groups + " e.g. .aux .out .toc .jpg .bmp .gif + " or .aux$\|.out$\|.toc$\|.jpg$\|.bmp$\|.gif$ + let pats = ['[*\/]*\([?_.0-9A-Za-z]\+\)\([*\/]*\)\(\\\@<!,\|$\)','\\\@<!,'] + let subs = has('win32') || has('win64') ? ['\1\3', ' '] : ['\1\2\3', '\\|'] + let expr = substitute(&wig, pats[0], subs[0], 'g') + let expr = substitute(expr, pats[1], subs[1], 'g') + let expr = substitute(expr, '\\,', ',', 'g') + + " Set the user_command option + let g:ctrlp_user_command = has('win32') || has('win64') + \ ? 'dir %s /-n /b /s /a-d | findstr /V /l "'.expr.'"' + \ : 'find %s -type f | grep -v "'.expr .'"' + endfunction + + call s:wig2cmd() +< +(submitted by Rich Alesi <github.com/ralesi>) + +* A standalone function to set the working directory to the project’s root, or + to the parent directory of the current file if a root can’t be found: +> + function! s:setcwd() + let cph = expand('%:p:h', 1) + if match(cph, '\v^<.+>://') >= 0 | retu | en + for mkr in ['.git/', '.hg/', '.svn/', '.bzr/', '_darcs/', '.vimprojects'] + let wd = call('find'.(mkr =~ '/$' ? 'dir' : 'file'), [mkr, cph.';']) + if wd != '' | let &acd = 0 | brea | en + endfo + exe 'lc!' fnameescape(wd == '' ? cph : substitute(wd, mkr.'$', '.', '')) + endfunction + + autocmd BufEnter * call s:setcwd() +< +(requires Vim 7.1.299+) + +=============================================================================== +CREDITS *ctrlp-credits* + +Developed by Kien Nguyen <github.com/kien>. + +Project’s homepage: http://kien.github.com/ctrlp.vim +Git repository: https://github.com/kien/ctrlp.vim +Mercurial repository: https://bitbucket.org/kien/ctrlp.vim + +------------------------------------------------------------------------------- +Thanks to everyone that has submitted ideas, bug reports or helped debugging on +gibhub, bitbucket, and through email. + +Special thanks:~ + + * Woojong Koh <github.com/wjkoh> + * Simon Ruderich + * Yasuhiro Matsumoto <github.com/mattn> + * Ken Earley <github.com/kenearley> + * Kyo Nagashima <github.com/hail2u> + * Zak Johnson <github.com/zakj> + * Diego Viola <github.com/diegoviola> + * Piet Delport <github.com/pjdelport> + * Thibault Duplessis <github.com/ornicar> + * Kent Sibilev <github.com/datanoise> + * Tacahiroy <github.com/tacahiroy> + * Luca Pette <github.com/lucapette> + +=============================================================================== +CHANGELOG *ctrlp-changelog* + + + New option: |g:ctrlp_mruf_default_order| + + New feature: Bookmarked directories extension. + + New commands: |:CtrlPBookmarkDir| + |:CtrlPBookmarkDirAdd| + +Before 2012/04/15~ + + + New option: |g:ctrlp_buffer_func|, callback functions for CtrlP buffer. + + Remove: g:ctrlp_mruf_last_entered, make it a default for MRU mode. + + New commands: |:CtrlPLastMode|, open CtrlP in the last mode used. + |:CtrlPMixed|, search in files, buffers and MRU files. + +Before 2012/03/31~ + + + New options: |g:ctrlp_default_input|, default input when entering CtrlP. + |g:ctrlp_match_func|, allow using a custom fuzzy matcher. + + Rename: + *ClearCtrlPCache* -> |CtrlPClearCache| + *ClearAllCtrlPCaches* -> |CtrlPClearAllCaches| + *ResetCtrlP* -> |CtrlPReload| + +Before 2012/03/02~ + + + Rename: + *g:ctrlp_regexp_search* -> |g:ctrlp_regexp|, + *g:ctrlp_dont_split* -> |g:ctrlp_reuse_window|, + *g:ctrlp_jump_to_buffer* -> |g:ctrlp_switch_buffer|. + + Rename and tweak: + *g:ctrlp_open_multi* -> |g:ctrlp_open_multiple_files|. + + Deprecate *g:ctrlp_highlight_match* + + Extend |g:ctrlp_user_command| to support multiple commands. + + New option: |g:ctrlp_mruf_last_entered| change MRU to Recently-Entered. + +Before 2012/01/15~ + + + New mapping: Switch <tab> and <s-tab>. <tab> is now used for completion + of directory names under the current working directory. + + New options: |g:ctrlp_arg_map| for <c-y>, <c-o> to accept an argument. + |g:ctrlp_status_func| custom statusline. + |g:ctrlp_mruf_relative| show only MRU files inside cwd. + + Extend g:ctrlp_open_multi with new optional values: tr, hr, vr. + + Extend |g:ctrlp_custom_ignore| to specifically filter dir, file and link. + +Before 2012/01/05~ + + + New feature: Buffer Tag extension. + + New commands: |:CtrlPBufTag|, |:CtrlPBufTagAll|. + + New options: |g:ctrlp_cmd|, + |g:ctrlp_custom_ignore| + +Before 2011/11/30~ + + + New features: Tag, Quickfix and Directory extensions. + + New commands: |:CtrlPTag|, |:CtrlPQuickfix|, |:CtrlPDir|. + + New options: |g:ctrlp_use_migemo|, + |g:ctrlp_lazy_update|, + |g:ctrlp_follow_symlinks| + +Before 2011/11/13~ + + + New special input: '/' and '\' find root (|ctrlp-input-formats| (e)) + + Remove ctrlp#SetWorkingPath(). + + Remove *g:ctrlp_mru_files* and make MRU mode permanent. + + Extend g:ctrlp_open_multi, add new ways to open files. + + New option: g:ctrlp_dont_split, + |g:ctrlp_mruf_case_sensitive| + +Before 2011/10/30~ + + + New feature: Support for custom extensions. + <F5> also removes non-existent files from MRU list. + + New option: g:ctrlp_jump_to_buffer + +Before 2011/10/12~ + + + New features: Open multiple files. + Pass Vim’s |++opt| and |+cmd| to the opening file + (|ctrlp-input-formats| (c)) + Auto-complete each dir for |:CtrlP| [starting-directory] + + New mappings: <c-z> mark/unmark a file to be opened with <c-o>. + <c-o> open all marked files. + + New option: g:ctrlp_open_multi + + Remove *g:ctrlp_persistent_input* *g:ctrlp_live_update* and <c-^>. + +Before 2011/09/29~ + + + New mappings: <c-n>, <c-p> next/prev string in the input history. + <c-y> create a new file and its parent dirs. + + New options: |g:ctrlp_open_new_file|, + |g:ctrlp_max_history| + + Added a new open-in-horizontal-split mapping: <c-x> + +Before 2011/09/19~ + + + New command: ResetCtrlP + + New options: |g:ctrlp_max_files|, + |g:ctrlp_max_depth|, + g:ctrlp_live_update + + New mapping: <c-^> + +Before 2011/09/12~ + + + Ability to cycle through matched lines in the match window. + + Extend the behavior of g:ctrlp_persistent_input + + Extend the behavior of |:CtrlP| + + New options: |g:ctrlp_dotfiles|, + |g:ctrlp_clear_cache_on_exit|, + g:ctrlp_highlight_match, + |g:ctrlp_user_command| + + New special input: '..' (|ctrlp-input-formats| (d)) + + New mapping: <F5>. + + New commands: |:CtrlPCurWD|, + |:CtrlPCurFile|, + |:CtrlPRoot| + + + New feature: Search in most recently used (MRU) files + + New mapping: <c-b>. + + Extended the behavior of <c-f>. + + New options: g:ctrlp_mru_files, + |g:ctrlp_mruf_max|, + |g:ctrlp_mruf_exclude|, + |g:ctrlp_mruf_include| + + New command: |:CtrlPMRU| + +First public release: 2011/09/06~ + +=============================================================================== +vim:ft=help:et:ts=2:sw=2:sts=2:norl