Mercurial > public > dotfiles

comparison vim/vimfiles/bundle/ctrlp.vim/doc/ctrlp.txt @ 7:86e0ac713642

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
6:ff60fbc930de 7:86e0ac713642
1 *ctrlp.txt* Fuzzy file, buffer, mru and tag finder. v1.7.6
2 *CtrlP* *ControlP* *'ctrlp'* *'ctrl-p'*
3 ===============================================================================
4 # #
5 # :::::::: ::::::::::: ::::::::: ::: ::::::::: #
6 # :+: :+: :+: :+: :+: :+: :+: :+: #
7 # +:+ +:+ +:+ +:+ +:+ +:+ +:+ #
8 # +#+ +#+ +#++:++#: +#+ +#++:++#+ #
9 # +#+ +#+ +#+ +#+ +#+ +#+ #
10 # #+# #+# #+# #+# #+# #+# #+# #
11 # ######## ### ### ### ########## ### #
12 # #
13 ===============================================================================
14 CONTENTS *ctrlp-contents*
15
16 1. Intro........................................|ctrlp-intro|
17 2. Options......................................|ctrlp-options|
18 3. Commands.....................................|ctrlp-commands|
19 4. Mappings.....................................|ctrlp-mappings|
20 5. Input Formats................................|ctrlp-input-formats|
21 6. Extensions...................................|ctrlp-extensions|
22
23 ===============================================================================
24 INTRO *ctrlp-intro*
25
26 Full path fuzzy file, buffer, mru and tag finder with an intuitive interface.
27 Written in pure Vimscript for MacVim and Vim version 7.0+. Has full support for
28 Vim’s |regexp| as search pattern, built-in MRU files monitoring, project’s root
29 finder, and more.
30
31 To enable optional extensions (tag, dir, rtscript...), see |ctrlp-extensions|.
32
33 ===============================================================================
34 OPTIONS *ctrlp-options*
35
36 Overview:~
37
38 |loaded_ctrlp| Disable the plugin.
39 |ctrlp_map| Default mapping.
40 |ctrlp_cmd| Default command used for the default mapping.
41 |ctrlp_by_filename| Default to filename mode or not.
42 |ctrlp_regexp| Default to regexp mode or not.
43 |ctrlp_match_window_bottom| Where to show the match window.
44 |ctrlp_match_window_reversed| Sort order in the match window.
45 |ctrlp_max_height| Max height of the match window.
46 |ctrlp_switch_buffer| Jump to an open buffer if already opened.
47 |ctrlp_reuse_window| Reuse special windows (help, quickfix, etc).
48 |ctrlp_working_path_mode| How to set CtrlP’s local working directory.
49 |ctrlp_root_markers| Additional, high priority root markers.
50 |ctrlp_use_caching| Use per-session caching or not.
51 |ctrlp_clear_cache_on_exit| Keep cache after exiting Vim or not.
52 |ctrlp_cache_dir| Location of the cache directory.
53 |ctrlp_dotfiles| Ignore dotfiles and dotdirs or not.
54 |ctrlp_custom_ignore| Hide stuff when using |globpath()|.
55 |ctrlp_max_files| Number of files to scan initially.
56 |ctrlp_max_depth| Directory depth to recurse into when scanning.
57 |ctrlp_user_command| Use an external scanner.
58 |ctrlp_max_history| Number of entries saved in the prompt history.
59 |ctrlp_open_new_file| How to open a file created by <c-y>.
60 |ctrlp_open_multiple_files| How to open files selected by <c-z>.
61 |ctrlp_arg_map| Intercept <c-y> and <c-o> or not.
62 |ctrlp_follow_symlinks| Follow symbolic links or not.
63 |ctrlp_lazy_update| Only update when typing has stopped.
64 |ctrlp_default_input| Seed the prompt with an initial string.
65 |ctrlp_use_migemo| Use Migemo patterns for Japanese filenames.
66 |ctrlp_prompt_mappings| Change the mappings in the prompt.
67
68 MRU mode:
69 |ctrlp_mruf_max| Max MRU entries to remember.
70 |ctrlp_mruf_exclude| Files that shouldn’t be remembered.
71 |ctrlp_mruf_include| Files to be remembered.
72 |ctrlp_mruf_relative| Show only MRU files in the working directory.
73 |ctrlp_mruf_default_order| Disable sorting.
74 |ctrlp_mruf_case_sensitive| MRU files are case sensitive or not.
75
76 Advanced options:
77 |ctrlp_status_func| Change CtrlP’s two statuslines.
78 |ctrlp_buffer_func| Call custom functions in the CtrlP buffer.
79 |ctrlp_match_func| Replace the built-in matching algorithm.
80
81 -------------------------------------------------------------------------------
82 Detailed descriptions and default values:~
83
84 *'g:ctrlp_map'*
85 Use this option to change the mapping to invoke CtrlP in |Normal| mode: >
86 let g:ctrlp_map = '<c-p>'
87 <
88
89 *'g:ctrlp_cmd'*
90 Set the default opening command to use when pressing the above mapping: >
91 let g:ctrlp_cmd = 'CtrlP'
92 <
93
94 *'g:loaded_ctrlp'*
95 Use this to disable the plugin completely: >
96 let g:loaded_ctrlp = 1
97 <
98
99 *'g:ctrlp_by_filename'*
100 Set this to 1 to set searching by filename (as opposed to full path) as the
101 default: >
102 let g:ctrlp_by_filename = 0
103 <
104 Can be toggled on/off by pressing <c-d> inside the prompt.
105
106 *'g:ctrlp_regexp'*
107 Set this to 1 to set regexp search as the default: >
108 let g:ctrlp_regexp = 0
109 <
110 Can be toggled on/off by pressing <c-r> inside the prompt.
111
112 *'g:ctrlp_match_window_bottom'*
113 Set this to 0 to show the match window at the top of the screen: >
114 let g:ctrlp_match_window_bottom = 1
115 <
116
117 *'g:ctrlp_match_window_reversed'*
118 Change the listing order of the files in the match window. The default setting
119 (1) is from bottom to top: >
120 let g:ctrlp_match_window_reversed = 1
121 <
122
123 *'g:ctrlp_max_height'*
124 Set the maximum height of the match window: >
125 let g:ctrlp_max_height = 10
126 <
127
128 *'g:ctrlp_switch_buffer'*
129 When opening a file with <cr> or <c-t>, if the file’s already opened somewhere
130 CtrlP will try to jump to it instead of opening a new instance: >
131 let g:ctrlp_switch_buffer = 2
132 <
133 1 - only jump to the buffer if it’s opened in the current tab.
134 2 - jump tab as well if the buffer’s opened in another tab.
135 0 - disable this feature.
136
137 *'g:ctrlp_reuse_window'*
138 When opening a file with <cr>, CtrlP avoids opening it in windows created by
139 plugins, help and quickfix. Use this to setup some exceptions: >
140 let g:ctrlp_reuse_window = 'netrw'
141 <
142 Acceptable values are partial name, filetype or buftype of the special buffers.
143 Use regexp to specify the pattern.
144 Example: >
145 let g:ctrlp_reuse_window = 'netrw\|help\|quickfix'
146 <
147
148 *'g:ctrlp_working_path_mode'*
149 When starting up, CtrlP sets its local working directory according to this
150 variable: >
151 let g:ctrlp_working_path_mode = 2
152 <
153 1 - the parent directory of the current file.
154 2 - the nearest ancestor that contains one of these directories or files:
155 .git/ .hg/ .svn/ .bzr/ _darcs/
156 0 - don’t manage working directory.
157 Note: you can use b:ctrlp_working_path_mode (a |b:var|) to set this option on a
158 per buffer basis.
159
160 *'g:ctrlp_root_markers'*
161 Use this to set your own root markers in addition to the default ones (.git/,
162 .hg/, .svn/, .bzr/, and _darcs/). Your markers will take precedence: >
163 let g:ctrlp_root_markers = ['']
164 <
165
166 *'g:ctrlp_use_caching'*
167 Set this to 0 to disable per-session caching. When disabled, caching will still
168 be enabled for directories that have more than 4000 files: >
169 let g:ctrlp_use_caching = 1
170 <
171 Note: you can quickly purge the cache by pressing <F5> while inside CtrlP.
172
173 *'g:ctrlp_clear_cache_on_exit'*
174 Set this to 0 to enable cross-session caching by not deleting the cache files
175 upon exiting Vim: >
176 let g:ctrlp_clear_cache_on_exit = 1
177 <
178
179 *'g:ctrlp_cache_dir'*
180 Set the directory to store the cache files: >
181 let g:ctrlp_cache_dir = $HOME.'/.cache/ctrlp'
182 <
183
184 *'g:ctrlp_dotfiles'*
185 Set this to 0 if you don’t want CtrlP to scan for dotfiles and dotdirs: >
186 let g:ctrlp_dotfiles = 1
187 <
188 You can use |'wildignore'| to exclude anything from the search.
189 Examples: >
190 " Excluding version control directories
191 set wildignore+=*/.git/*,*/.hg/*,*/.svn/* " Linux/MacOSX
192 set wildignore+=.git\*,.hg\*,.svn\* " Windows
193 <
194 Note #1: the `*/` in front of each directory glob is required.
195
196 Note #2: |wildignore| influences the result of |expand()|, |globpath()| and
197 |glob()| which many plugins use to find stuff on the system (e.g. VCS related
198 plugins look for .git/, .hg/,... some other plugins look for external *.exe
199 tools on Windows). So be a little mindful of what you put in your |wildignore|.
200
201 *'g:ctrlp_custom_ignore'*
202 In addition to |'wildignore'|, use this for files and directories you want only
203 CtrlP to not show. Use regexp to specify the patterns: >
204 let g:ctrlp_custom_ignore = ''
205 <
206 Examples: >
207 let g:ctrlp_custom_ignore = '\.git$\|\.hg$\|\.svn$'
208 let g:ctrlp_custom_ignore = {
209 \ 'dir': '\.git$\|\.hg$\|\.svn$',
210 \ 'file': '\.exe$\|\.so$\|\.dll$',
211 \ 'link': 'SOME_BAD_SYMBOLIC_LINKS',
212 \ }
213 <
214 Note: ignoring only works when |globpath()| is used to scan for files.
215
216 *'g:ctrlp_max_files'*
217 The maximum number of files to scan, set to 0 for no limit: >
218 let g:ctrlp_max_files = 10000
219 <
220
221 *'g:ctrlp_max_depth'*
222 The maximum depth of a directory tree to recurse into: >
223 let g:ctrlp_max_depth = 40
224 <
225 Note: the larger these values, the more memory Vim uses.
226
227 *'g:ctrlp_user_command'*
228 Specify an external tool to use for listing files instead of using Vim’s
229 |globpath()|. Use %s in place of the target directory: >
230 let g:ctrlp_user_command = ''
231 <
232 Examples: >
233 let g:ctrlp_user_command = 'find %s -type f' " MacOSX/Linux
234 let g:ctrlp_user_command = 'dir %s /-n /b /s /a-d' " Windows
235 <
236 You can also use 'grep', 'findstr' or something else to filter the results.
237 Examples: >
238 let g:ctrlp_user_command = 'find %s -type f | grep (?!tmp/.*)'
239 let g:ctrlp_user_command = 'dir %s /-n /b /s /a-d | findstr .*\.py$'
240 <
241 Use a version control listing command when inside a repository, this is faster
242 when scanning large projects: >
243 let g:ctrlp_user_command = [root_marker, listing_command, fallback_command]
244 let g:ctrlp_user_command = {
245 \ 'types': {
246 \ 1: [root_marker_1, listing_command_1],
247 \ n: [root_marker_n, listing_command_n],
248 \ },
249 \ 'fallback': fallback_command
250 \ }
251 <
252 Examples: >
253 let g:ctrlp_user_command = ['.git/', 'cd %s && git ls-files']
254 let g:ctrlp_user_command = ['.hg/', 'hg --cwd %s locate -I .']
255 let g:ctrlp_user_command = {
256 \ 'types': {
257 \ 1: ['.git/', 'cd %s && git ls-files'],
258 \ 2: ['.hg/', 'hg --cwd %s locate -I .'],
259 \ },
260 \ 'fallback': 'find %s -type f'
261 \ }
262 <
263 If the fallback_command is empty or not defined, |globpath()| will then be used
264 when searching outside a repo.
265
266 *'g:ctrlp_max_history'*
267 The maximum number of input strings you want CtrlP to remember. The default
268 value mirrors Vim’s global |'history'| option: >
269 let g:ctrlp_max_history = &history
270 <
271 Set to 0 to disable prompt’s history. Browse the history with <c-n> and <c-p>.
272
273 *'g:ctrlp_open_new_file'*
274 Use this option to specify how the newly created file is to be opened when
275 pressing <c-y>:
276 t - in a new tab
277 h - in a new horizontal split
278 v - in a new vertical split
279 r - in the current window
280 >
281 let g:ctrlp_open_new_file = 'v'
282 <
283
284 *'g:ctrlp_open_multiple_files'*
285 If non-zero, this will enable opening multiple files with <c-z> and <c-o>: >
286 let g:ctrlp_open_multiple_files = 'v'
287 <
288 Example: >
289 let g:ctrlp_open_multiple_files = '2vr'
290 <
291 For the number:
292 - If given, it’ll be used as the maximum number of windows or tabs to create
293 when opening the files (the rest will be opened as hidden buffers).
294 - If not given, <c-o> will open all files, each in a new window or new tab.
295 For the letters:
296 t - each file in a new tab.
297 h - each file in a new horizontal split.
298 v - each file in a new vertical split.
299 Reuse the current window:
300 tr,
301 hr,
302 vr - open the first file in the current window, then the remaining files in
303 new splits or new tabs just like with t, h, v.
304
305 *'g:ctrlp_arg_map'*
306 When this is set to 1, the <c-o> and <c-y> mappings will accept one extra key
307 as an argument to override their default behavior: >
308 let g:ctrlp_arg_map = 0
309 <
310 Pressing <c-o> or <c-y> will then prompt for a keypress. The key can be:
311 t - open in tab(s)
312 h - open in horizontal split(s)
313 v - open in vertical split(s)
314 r - open in current window (for <c-y> only)
315 <esc>, <c-c>, <c-g> - cancel and go back to the prompt.
316 <cr> - use the default behavior specified with |g:ctrlp_open_new_file| and
317 |g:ctrlp_open_multiple_files|.
318
319 *'g:ctrlp_follow_symlinks'*
320 Set this to 1 to follow symbolic links when listing files: >
321 let g:ctrlp_follow_symlinks = 0
322 <
323 When enabled, looped internal symlinks will be ignored to avoid duplicates.
324
325 *'g:ctrlp_lazy_update'*
326 Set this to 1 to enable the lazy-update feature: only update the match window
327 after typing’s been stopped for a certain amount of time: >
328 let g:ctrlp_lazy_update = 0
329 <
330 If is 1, update after 250ms. If bigger than 1, the number will be used as the
331 delay time in milliseconds.
332
333 *'g:ctrlp_default_input'*
334 Set this to 1 to enable seeding the prompt with the current file’s relative
335 path: >
336 let g:ctrlp_default_input = 0
337 <
338
339 *'g:ctrlp_use_migemo'*
340 Set this to 1 to use Migemo Pattern for Japanese filenames. Migemo Search only
341 works in regexp mode. To split the pattern, separate words with space: >
342 let g:ctrlp_use_migemo = 0
343 <
344
345 *'g:ctrlp_prompt_mappings'*
346 Use this to customize the mappings inside CtrlP’s prompt to your liking. You
347 only need to keep the lines that you’ve changed the values (inside []): >
348 let g:ctrlp_prompt_mappings = {
349 \ 'PrtBS()': ['<bs>', '<c-]>'],
350 \ 'PrtDelete()': ['<del>'],
351 \ 'PrtDeleteWord()': ['<c-w>'],
352 \ 'PrtClear()': ['<c-u>'],
353 \ 'PrtSelectMove("j")': ['<c-j>', '<down>'],
354 \ 'PrtSelectMove("k")': ['<c-k>', '<up>'],
355 \ 'PrtSelectMove("t")': ['<Home>', '<kHome>'],
356 \ 'PrtSelectMove("b")': ['<End>', '<kEnd>'],
357 \ 'PrtSelectMove("u")': ['<PageUp>', '<kPageUp>'],
358 \ 'PrtSelectMove("d")': ['<PageDown>', '<kPageDown>'],
359 \ 'PrtHistory(-1)': ['<c-n>'],
360 \ 'PrtHistory(1)': ['<c-p>'],
361 \ 'AcceptSelection("e")': ['<cr>', '<2-LeftMouse>'],
362 \ 'AcceptSelection("h")': ['<c-x>', '<c-cr>', '<c-s>'],
363 \ 'AcceptSelection("t")': ['<c-t>'],
364 \ 'AcceptSelection("v")': ['<c-v>', '<RightMouse>'],
365 \ 'ToggleFocus()': ['<s-tab>'],
366 \ 'ToggleRegex()': ['<c-r>'],
367 \ 'ToggleByFname()': ['<c-d>'],
368 \ 'ToggleType(1)': ['<c-f>', '<c-up>'],
369 \ 'ToggleType(-1)': ['<c-b>', '<c-down>'],
370 \ 'PrtExpandDir()': ['<tab>'],
371 \ 'PrtInsert("c")': ['<MiddleMouse>', '<insert>'],
372 \ 'PrtInsert()': ['<c-\>'],
373 \ 'PrtCurStart()': ['<c-a>'],
374 \ 'PrtCurEnd()': ['<c-e>'],
375 \ 'PrtCurLeft()': ['<c-h>', '<left>', '<c-^>'],
376 \ 'PrtCurRight()': ['<c-l>', '<right>'],
377 \ 'PrtClearCache()': ['<F5>'],
378 \ 'PrtDeleteEnt()': ['<F7>'],
379 \ 'CreateNewFile()': ['<c-y>'],
380 \ 'MarkToOpen()': ['<c-z>'],
381 \ 'OpenMulti()': ['<c-o>'],
382 \ 'PrtExit()': ['<esc>', '<c-c>', '<c-g>'],
383 \ }
384 <
385 Note: In some terminals, it’s not possible to remap <c-h> without also changing
386 <bs> (|keycodes|). So if pressing <bs> moves the cursor to the left instead of
387 deleting a char for you, add this to your |.vimrc| to disable the plugin’s
388 default <c-h> mapping: >
389 let g:ctrlp_prompt_mappings = { 'PrtCurLeft()': ['<left>', '<c-^>'] }
390 <
391
392 ----------------------------------------
393 MRU mode options:~
394
395 *'g:ctrlp_mruf_max'*
396 Specify the number of recently opened files you want CtrlP to remember: >
397 let g:ctrlp_mruf_max = 250
398 <
399
400 *'g:ctrlp_mruf_exclude'*
401 Files you don’t want CtrlP to remember. Use regexp to specify the patterns: >
402 let g:ctrlp_mruf_exclude = ''
403 <
404 Examples: >
405 let g:ctrlp_mruf_exclude = '/tmp/.*\|/temp/.*' " MacOSX/Linux
406 let g:ctrlp_mruf_exclude = '^C:\\dev\\tmp\\.*' " Windows
407 <
408
409 *'g:ctrlp_mruf_include'*
410 And if you want CtrlP to only remember some files, specify them here: >
411 let g:ctrlp_mruf_include = ''
412 <
413 Example: >
414 let g:ctrlp_mruf_include = '\.py$\|\.rb$'
415 <
416
417 *'g:ctrlp_mruf_relative'*
418 Set this to 1 to show only MRU files in the current working directory: >
419 let g:ctrlp_mruf_relative = 0
420 <
421
422 *'g:ctrlp_mruf_default_order'*
423 Set this to 1 to disable sorting when searching in MRU mode: >
424 let g:ctrlp_mruf_default_order = 0
425 <
426
427 *'g:ctrlp_mruf_case_sensitive'*
428 Match this with your file system case-sensitivity setting to avoid duplicate
429 MRU entries: >
430 let g:ctrlp_mruf_case_sensitive = 1
431 <
432
433 ----------------------------------------
434 Advanced options:~
435
436 *'g:ctrlp_status_func'*
437 Use this to customize the statuslines for the CtrlP window: >
438 let g:ctrlp_status_func = {}
439 <
440 Example: >
441 let g:ctrlp_status_func = {
442 \ 'main': 'Function_Name_1',
443 \ 'prog': 'Function_Name_2',
444 \ }
445 <
446 Structure of the functions: >
447 " Main statusline
448 function! Function_Name_1(focus, byfname, regex, prev, item, next, marked)
449 " Arguments:
450 " |
451 " +- a:focus : The focus of the prompt: "prt" or "win".
452 " |
453 " +- a:byfname : In filename mode or in full path mode: "file" or "path".
454 " |
455 " +- a:regex : In regex mode: 1 or 0.
456 " |
457 " +- a:prev : The previous search mode.
458 " |
459 " +- a:item : The current search mode.
460 " |
461 " +- a:next : The next search mode.
462 " |
463 " +- a:marked : The number of marked files, or a comma separated list of
464 " the filenames.
465
466 return full_statusline
467 endfunction
468
469 " Progress statusline
470 function! Function_Name_2(str)
471 " a:str : Either the number of files scanned so far, or a string indicating
472 " the current directory is being scanned with a user_command.
473
474 return full_statusline
475 endfunction
476 <
477 See https://gist.github.com/1610859 for a working example.
478
479 *'g:ctrlp_buffer_func'*
480 Specify the functions that will be called after entering and before exiting the
481 CtrlP buffer: >
482 let g:ctrlp_buffer_func = {}
483 <
484 Example: >
485 let g:ctrlp_buffer_func = {
486 \ 'enter': 'Function_Name_1',
487 \ 'exit': 'Function_Name_2',
488 \ }
489 <
490
491 *'g:ctrlp_match_func'*
492 Set an external fuzzy matching function for CtrlP to use: >
493 let g:ctrlp_match_func = {}
494 <
495 Example: >
496 let g:ctrlp_match_func = { 'match': 'Function_Name' }
497 <
498 Structure of the function: >
499 function! Function_Name(items, str, limit, mmode, ispath, crfile, regex)
500 " Arguments:
501 " |
502 " +- a:items : The full list of items to search in.
503 " |
504 " +- a:str : The string entered by the user.
505 " |
506 " +- a:limit : The max height of the match window. Can be used to limit
507 " | the number of items to return.
508 " |
509 " +- a:mmode : The match mode. Can be one of these strings:
510 " | + "full-line": match the entire line.
511 " | + "filename-only": match only the filename.
512 " | + "first-non-tab": match until the first tab char.
513 " | + "until-last-tab": match until the last tab char.
514 " |
515 " +- a:ispath : Is 1 when searching in file, buffer, mru, dir, and rtscript
516 " | modes. Is 0 otherwise.
517 " |
518 " +- a:crfile : The file in the current window. Should be excluded from the
519 " | results when a:ispath == 1.
520 " |
521 " +- a:regex : In regex mode: 1 or 0.
522
523 return list_of_matched_items
524 endfunction
525 <
526
527 ===============================================================================
528 COMMANDS *ctrlp-commands*
529
530 *:CtrlP*
531 :CtrlP [starting-directory]
532 Open CtrlP in find file mode.
533
534 If no argument is given, the value of |g:ctrlp_working_path_mode| will be
535 used to determine the starting directory.
536 You can use <tab> to auto-complete the [starting-directory] when typing it.
537
538 *:CtrlPBuffer*
539 :CtrlPBuffer
540 Open CtrlP in find buffer mode.
541
542 *:CtrlPMRU*
543 :CtrlPMRU
544 Open CtrlP in find Most-Recently-Used file mode.
545
546 *:CtrlPLastMode*
547 :CtrlPLastMode
548 Open CtrlP in the last mode used.
549
550 *:CtrlPRoot*
551 :CtrlPRoot
552 This acts like |:CtrlP| with |g:ctrlp_working_path_mode| = 2 (ignores its
553 current value).
554
555 *:CtrlPClearCache*
556 :CtrlPClearCache
557 Flush the cache for the current working directory. The same as pressing <F5>
558 inside CtrlP.
559 To enable or disable caching, use the |g:ctrlp_use_caching| option.
560
561 *:CtrlPClearAllCaches*
562 :CtrlPClearAllCaches
563 Delete all the cache files saved in |g:ctrlp_cache_dir|.
564
565 -------------------------------------------------------------------------------
566 For commands provided by bundled extensions, see |ctrlp-extensions|.
567
568 ===============================================================================
569 MAPPINGS *ctrlp-mappings*
570
571 *'ctrlp-<c-p>'*
572 <c-p>
573 Default |Normal| mode mapping to open the CtrlP prompt in find file mode.
574
575 Once inside the prompt:~
576
577 <c-d>
578 Toggle between full-path search and filename only search.
579 Note: in filename mode, the prompt’s base is '>d>' instead of '>>>'
580
581 <c-r> *'ctrlp-fullregexp'*
582 Toggle between the string mode and full regexp mode.
583 Note: in full regexp mode, the prompt’s base is 'r>>' instead of '>>>'
584
585 See also |input-formats| (guide) and |g:ctrlp_regexp_search| (option).
586
587 <c-f>, 'forward'
588 <c-up>
589 Scroll to the 'next' search mode in the sequence.
590
591 <c-b>, 'backward'
592 <c-down>
593 Scroll to the 'previous' search mode in the sequence.
594
595 <tab>
596 Auto-complete directory names under the current working directory inside
597 the prompt.
598
599 <s-tab>
600 Toggle the focus between the match window and the prompt.
601
602 <c-j>,
603 <down>
604 Move selection down.
605
606 <c-k>,
607 <up>
608 Move selection up.
609
610 <c-a>
611 Move the cursor to the 'start' of the prompt.
612
613 <c-e>
614 Move the cursor to the 'end' of the prompt.
615
616 <c-h>,
617 <left>,
618 <c-^>
619 Move the cursor one character to the 'left'.
620
621 <c-l>,
622 <right>
623 Move the cursor one character to the 'right'.
624
625 <c-]>,
626 <bs>
627 Delete the preceding character.
628
629 <del>
630 Delete the current character.
631
632 <c-w>
633 Delete a preceding inner word.
634
635 <c-u>
636 Clear the input field.
637
638 <cr>
639 Open selected file in the active window if possible.
640
641 <c-t>
642 Open selected file in a new 'tab' after the last tabpage.
643
644 <c-v>
645 Open selected file in a 'vertical' split.
646
647 <c-x>,
648 <c-cr>,
649 <c-s>
650 Open selected file in a 'horizontal' split.
651
652 <c-y>
653 Create a new file and its parent directories.
654
655 <c-n>
656 Next string in the prompt’s history.
657
658 <c-p>
659 Previous string in the prompt’s history.
660
661 <c-z>
662 - Mark/unmark a file to be opened with <c-o>.
663 - Or mark/unmark a file to create a new file in its directory using <c-y>.
664
665 <c-o>
666 Open files marked by <c-z>.
667
668 <F5>
669 - Refresh the match window and purge the cache for the current directory.
670 - Or remove deleted files from the MRU list.
671
672 <F7>
673 - Wipe the MRU list.
674 - Or delete MRU entries marked by <c-z>.
675
676 <insert>
677 Insert the word under the cursor (in the current buffer) into the prompt.
678
679 <esc>,
680 <c-c>,
681 <c-g>
682 Exit CtrlP.
683 Note: <c-c> can also be used to stop the scan if it’s taking too long.
684
685 Choose your own mappings with |g:ctrlp_prompt_mappings|.
686
687 When inside the match window (press <s-tab> to switch):~
688
689 a-z
690 0-9
691 ~^-=;`',.+!@#$%&_(){}[]
692 Cycle through the lines with the first letter (of paths or filenames) that
693 matches that key.
694
695 ===============================================================================
696 INPUT FORMATS *ctrlp-input-formats*
697
698 Formats for inputting in the prompt:~
699
700 a) Simple string.
701
702 E.g. 'abc' is understood internally as 'a[^a]\{-}b[^b]\{-}c'
703
704 b) When in regexp mode, the input string’s treated as a Vim’s regexp |pattern|
705 without any modification.
706
707 E.g. 'abc\d*efg' will be read as 'abc\d*efg'.
708
709 See |ctrlp-fullregexp| (keymap) and |g:ctrlp_regexp_search| (option) for
710 how to enable regexp mode.
711
712 c) End the string with a colon ':' followed by a Vim command to execute that
713 command after opening the file. If you need to use ':' literally, escape it
714 with a backslash: '\:'. When opening multiple files, the command will be
715 executed on each opening file.
716
717 E.g. 'abc:45' will open the selected file and jump to line 45.
718
719 'abc:/any\:string' will open the selected file and jump to the first
720 instance of 'any:string'.
721
722 'abc:+setf\ myfiletype|50' will open the selected file and set its
723 filetype to 'myfiletype', then jump to line 50.
724
725 'abc:diffthis' will open the selected files and run |:diffthis| on the
726 first 4 files (if marked).
727
728 See also Vim’s |++opt| and |+cmd|.
729
730 d) Type exactly two dots '..' at the start of the prompt and press enter to go
731 backward in the directory tree by 1 level. If the parent directory is
732 large, this might be slow.
733
734 e) Similarly, submit '/' or '\' to find and go to the project’s root. If the
735 project is large, using a VCS listing command to look for files might help
736 speeding up the intial scan (see |g:ctrlp_user_command| for more details).
737
738 Note: e) and d) only work in find file mode and directory mode.
739
740 f) Type the name of a non-existent file and press <c-y> to create it. Mark a
741 file with <c-z> to create the new file in the same directory as the marked
742 file.
743
744 E.g. 'parentdir/newfile.txt' will create a directory named 'parentdir' as
745 well as 'newfile.txt'.
746
747 If 'some/old/dirs/oldfile.txt' is marked with <c-z>, then 'parentdir'
748 and 'newfile.txt' will be created in 'some/old/dirs'. The final path
749 will then be 'some/old/dirs/parentdir/newfile.txt'.
750
751 Use '\' in place of '/' on Windows (if |'ssl'| is not set).
752
753 g) Submit ? to open this help file.
754
755 ===============================================================================
756 EXTENSIONS *ctrlp-extensions*
757
758 Extensions are optional. To enable an extension, add its name to the variable
759 g:ctrlp_extensions: >
760 let g:ctrlp_extensions = ['tag', 'buffertag', 'quickfix', 'dir', 'rtscript',
761 \ 'undo', 'line', 'changes', 'mixed', 'bookmarkdir']
762 <
763 The order of the items will be the order they appear on the statusline and when
764 using <c-f>, <c-b>.
765
766 Available extensions:~
767
768 *:CtrlPTag*
769 * Tag mode:~
770 - Name: 'tag'
771 - Command: ':CtrlPTag'
772 - Search for a tag within a generated central tags file, and jump to the
773 definition. Use the Vim’s option |'tags'| to specify the names and the
774 locations of the tags file(s).
775 E.g. set tags+=doc/tags
776
777 *:CtrlPBufTag*
778 *:CtrlPBufTagAll*
779 * Buffer Tag mode:~
780 - Name: 'buffertag'
781 - Commands: ':CtrlPBufTag [buffer]',
782 ':CtrlPBufTagAll'.
783 - Search for a tag within the current buffer or all listed buffers and jump
784 to the definition. Requires |exuberant_ctags| or compatible programs.
785
786 *:CtrlPQuickfix*
787 * Quickfix mode:~
788 - Name: 'quickfix'
789 - Command: ':CtrlPQuickfix'
790 - Search for an entry in the current quickfix errors and jump to it.
791
792 *:CtrlPDir*
793 * Directory mode:~
794 - Name: 'dir'
795 - Command: ':CtrlPDir [starting-directory]'
796 - Search for a directory and change the working directory to it.
797 - Mappings:
798 + <cr> change the local working directory for CtrlP and keep it open.
799 + <c-t> change the global working directory (exit).
800 + <c-v> change the local working directory for the current window (exit).
801 + <c-x> change the global working directory to CtrlP’s current local
802 working directory (exit).
803
804 *:CtrlPRTS*
805 * Runtime script mode:~
806 - Name: 'rtscript'
807 - Command: ':CtrlPRTS'
808 - Search for files (vimscripts, docs, snippets...) in runtimepath.
809
810 *:CtrlPUndo*
811 * Undo mode:~
812 - Name: 'undo'
813 - Command: ':CtrlPUndo'
814 - Browse undo history.
815
816 *:CtrlPLine*
817 * Line mode:~
818 - Name: 'line'
819 - Command: ':CtrlPLine'
820 - Search for a line in all listed buffers.
821
822 *:CtrlPChange*
823 *:CtrlPChangeAll*
824 * Change list mode:~
825 - Name: 'changes'
826 - Commands: ':CtrlPChange [buffer]',
827 ':CtrlPChangeAll'.
828 - Search for and jump to a recent change in the current buffer or in all
829 listed buffers.
830
831 *:CtrlPMixed*
832 * Mixed mode:~
833 - Name: 'mixed'
834 - Command: ':CtrlPMixed'
835 - Search in files, buffers and MRU files at the same time.
836
837 *:CtrlPBookmarkDir*
838 *:CtrlPBookmarkDirAdd*
839 * BookmarkDir mode:~
840 - Name: 'bookmarkdir'
841 - Commands: ':CtrlPBookmarkDir',
842 ':CtrlPBookmarkDirAdd [directory]'.
843 - Search for a bookmarked directory and change the working directory to it.
844 - Mappings:
845 + <cr> change the local working directory for CtrlP, keep it open and
846 switch to find file mode.
847 + <c-x> change the global working directory (exit).
848 + <c-v> change the local working directory for the current window (exit).
849 + <F7>
850 - Wipe bookmark list.
851 - Or delete entries marked by <c-z>.
852
853 ----------------------------------------
854 Buffer Tag mode options:~
855
856 *'g:ctrlp_buftag_ctags_bin'*
857 If ctags isn’t in your $PATH, use this to set its location: >
858 let g:ctrlp_buftag_ctags_bin = ''
859 <
860
861 *'g:ctrlp_buftag_systemenc'*
862 Match this with your OS’s encoding (not Vim’s). The default value mirrors Vim’s
863 global |'encoding'| option: >
864 let g:ctrlp_buftag_systemenc = &encoding
865 <
866
867 *'g:ctrlp_buftag_types'*
868 Use this to set the arguments for ctags, jsctags... for a given filetype: >
869 let g:ctrlp_buftag_types = ''
870 <
871 Examples: >
872 let g:ctrlp_buftag_types = {
873 \ 'erlang' : '--language-force=erlang --erlang-types=drmf',
874 \ 'javascript' : {
875 \ 'bin': 'jsctags',
876 \ 'args': '-f -',
877 \ },
878 \ }
879 <
880
881 ===============================================================================
882 CUSTOMIZATION *ctrlp-customization*
883
884 Highlighting:~
885 * For the CtrlP buffer:
886 CtrlPNoEntries : the message when no match is found (Error)
887 CtrlPMatch : the matched pattern (Identifier)
888 CtrlPLinePre : the line prefix '>' in the match window
889 CtrlPPrtBase : the prompt’s base (Comment)
890 CtrlPPrtText : the prompt’s text (|hl-Normal|)
891 CtrlPPrtCursor : the prompt’s cursor when moving over the text (Constant)
892
893 * In extensions:
894 CtrlPTabExtra : the part of each line that’s not matched against (Comment)
895 CtrlPBufName : the buffer name an entry belongs to (|hl-Directory|)
896 CtrlPTagKind : the kind of the tag in buffer-tag mode (|hl-Title|)
897 CtrlPqfLineCol : the line and column numbers in quickfix mode (Comment)
898 CtrlPUndoT : the elapsed time in undo mode (|hl-Directory|)
899 CtrlPUndoBr : the square brackets [] in undo mode (Comment)
900 CtrlPUndoNr : the undo number inside [] in undo mode (String)
901 CtrlPUndoSv : the point where the file was saved (Comment)
902 CtrlPUndoPo : the current position in the undo tree (|hl-Title|)
903 CtrlPBookmark : the name of the bookmark (Identifier)
904
905 Statuslines:~
906 * Highlight groups:
907 CtrlPMode1 : 'prt' or 'win', also for 'regex' (Character)
908 CtrlPMode2 : 'file' or 'path', also for the local working dir (|hl-LineNr|)
909 CtrlPStats : the scanning status (Function)
910
911 For rebuilding the statuslines, see |g:ctrlp_status_func|.
912
913 ===============================================================================
914 MISCELLANEOUS CONFIGS *ctrlp-miscellaneous-configs*
915
916 * Use |wildignore| for |g:ctrlp_user_command|:
917 >
918 function! s:wig2cmd()
919 " Change wildignore into space or | separated groups
920 " e.g. .aux .out .toc .jpg .bmp .gif
921 " or .aux$\|.out$\|.toc$\|.jpg$\|.bmp$\|.gif$
922 let pats = ['[*\/]*\([?_.0-9A-Za-z]\+\)\([*\/]*\)\(\\\@<!,\|$\)','\\\@<!,']
923 let subs = has('win32') || has('win64') ? ['\1\3', ' '] : ['\1\2\3', '\\|']
924 let expr = substitute(&wig, pats[0], subs[0], 'g')
925 let expr = substitute(expr, pats[1], subs[1], 'g')
926 let expr = substitute(expr, '\\,', ',', 'g')
927
928 " Set the user_command option
929 let g:ctrlp_user_command = has('win32') || has('win64')
930 \ ? 'dir %s /-n /b /s /a-d | findstr /V /l "'.expr.'"'
931 \ : 'find %s -type f | grep -v "'.expr .'"'
932 endfunction
933
934 call s:wig2cmd()
935 <
936 (submitted by Rich Alesi <github.com/ralesi>)
937
938 * A standalone function to set the working directory to the project’s root, or
939 to the parent directory of the current file if a root can’t be found:
940 >
941 function! s:setcwd()
942 let cph = expand('%:p:h', 1)
943 if match(cph, '\v^<.+>://') >= 0 | retu | en
944 for mkr in ['.git/', '.hg/', '.svn/', '.bzr/', '_darcs/', '.vimprojects']
945 let wd = call('find'.(mkr =~ '/$' ? 'dir' : 'file'), [mkr, cph.';'])
946 if wd != '' | let &acd = 0 | brea | en
947 endfo
948 exe 'lc!' fnameescape(wd == '' ? cph : substitute(wd, mkr.'$', '.', ''))
949 endfunction
950
951 autocmd BufEnter * call s:setcwd()
952 <
953 (requires Vim 7.1.299+)
954
955 ===============================================================================
956 CREDITS *ctrlp-credits*
957
958 Developed by Kien Nguyen <github.com/kien>.
959
960 Project’s homepage: http://kien.github.com/ctrlp.vim
961 Git repository: https://github.com/kien/ctrlp.vim
962 Mercurial repository: https://bitbucket.org/kien/ctrlp.vim
963
964 -------------------------------------------------------------------------------
965 Thanks to everyone that has submitted ideas, bug reports or helped debugging on
966 gibhub, bitbucket, and through email.
967
968 Special thanks:~
969
970 * Woojong Koh <github.com/wjkoh>
971 * Simon Ruderich
972 * Yasuhiro Matsumoto <github.com/mattn>
973 * Ken Earley <github.com/kenearley>
974 * Kyo Nagashima <github.com/hail2u>
975 * Zak Johnson <github.com/zakj>
976 * Diego Viola <github.com/diegoviola>
977 * Piet Delport <github.com/pjdelport>
978 * Thibault Duplessis <github.com/ornicar>
979 * Kent Sibilev <github.com/datanoise>
980 * Tacahiroy <github.com/tacahiroy>
981 * Luca Pette <github.com/lucapette>
982
983 ===============================================================================
984 CHANGELOG *ctrlp-changelog*
985
986 + New option: |g:ctrlp_mruf_default_order|
987 + New feature: Bookmarked directories extension.
988 + New commands: |:CtrlPBookmarkDir|
989 |:CtrlPBookmarkDirAdd|
990
991 Before 2012/04/15~
992
993 + New option: |g:ctrlp_buffer_func|, callback functions for CtrlP buffer.
994 + Remove: g:ctrlp_mruf_last_entered, make it a default for MRU mode.
995 + New commands: |:CtrlPLastMode|, open CtrlP in the last mode used.
996 |:CtrlPMixed|, search in files, buffers and MRU files.
997
998 Before 2012/03/31~
999
1000 + New options: |g:ctrlp_default_input|, default input when entering CtrlP.
1001 |g:ctrlp_match_func|, allow using a custom fuzzy matcher.
1002 + Rename:
1003 *ClearCtrlPCache* -> |CtrlPClearCache|
1004 *ClearAllCtrlPCaches* -> |CtrlPClearAllCaches|
1005 *ResetCtrlP* -> |CtrlPReload|
1006
1007 Before 2012/03/02~
1008
1009 + Rename:
1010 *g:ctrlp_regexp_search* -> |g:ctrlp_regexp|,
1011 *g:ctrlp_dont_split* -> |g:ctrlp_reuse_window|,
1012 *g:ctrlp_jump_to_buffer* -> |g:ctrlp_switch_buffer|.
1013 + Rename and tweak:
1014 *g:ctrlp_open_multi* -> |g:ctrlp_open_multiple_files|.
1015 + Deprecate *g:ctrlp_highlight_match*
1016 + Extend |g:ctrlp_user_command| to support multiple commands.
1017 + New option: |g:ctrlp_mruf_last_entered| change MRU to Recently-Entered.
1018
1019 Before 2012/01/15~
1020
1021 + New mapping: Switch <tab> and <s-tab>. <tab> is now used for completion
1022 of directory names under the current working directory.
1023 + New options: |g:ctrlp_arg_map| for <c-y>, <c-o> to accept an argument.
1024 |g:ctrlp_status_func| custom statusline.
1025 |g:ctrlp_mruf_relative| show only MRU files inside cwd.
1026 + Extend g:ctrlp_open_multi with new optional values: tr, hr, vr.
1027 + Extend |g:ctrlp_custom_ignore| to specifically filter dir, file and link.
1028
1029 Before 2012/01/05~
1030
1031 + New feature: Buffer Tag extension.
1032 + New commands: |:CtrlPBufTag|, |:CtrlPBufTagAll|.
1033 + New options: |g:ctrlp_cmd|,
1034 |g:ctrlp_custom_ignore|
1035
1036 Before 2011/11/30~
1037
1038 + New features: Tag, Quickfix and Directory extensions.
1039 + New commands: |:CtrlPTag|, |:CtrlPQuickfix|, |:CtrlPDir|.
1040 + New options: |g:ctrlp_use_migemo|,
1041 |g:ctrlp_lazy_update|,
1042 |g:ctrlp_follow_symlinks|
1043
1044 Before 2011/11/13~
1045
1046 + New special input: '/' and '\' find root (|ctrlp-input-formats| (e))
1047 + Remove ctrlp#SetWorkingPath().
1048 + Remove *g:ctrlp_mru_files* and make MRU mode permanent.
1049 + Extend g:ctrlp_open_multi, add new ways to open files.
1050 + New option: g:ctrlp_dont_split,
1051 |g:ctrlp_mruf_case_sensitive|
1052
1053 Before 2011/10/30~
1054
1055 + New feature: Support for custom extensions.
1056 <F5> also removes non-existent files from MRU list.
1057 + New option: g:ctrlp_jump_to_buffer
1058
1059 Before 2011/10/12~
1060
1061 + New features: Open multiple files.
1062 Pass Vim’s |++opt| and |+cmd| to the opening file
1063 (|ctrlp-input-formats| (c))
1064 Auto-complete each dir for |:CtrlP| [starting-directory]
1065 + New mappings: <c-z> mark/unmark a file to be opened with <c-o>.
1066 <c-o> open all marked files.
1067 + New option: g:ctrlp_open_multi
1068 + Remove *g:ctrlp_persistent_input* *g:ctrlp_live_update* and <c-^>.
1069
1070 Before 2011/09/29~
1071
1072 + New mappings: <c-n>, <c-p> next/prev string in the input history.
1073 <c-y> create a new file and its parent dirs.
1074 + New options: |g:ctrlp_open_new_file|,
1075 |g:ctrlp_max_history|
1076 + Added a new open-in-horizontal-split mapping: <c-x>
1077
1078 Before 2011/09/19~
1079
1080 + New command: ResetCtrlP
1081 + New options: |g:ctrlp_max_files|,
1082 |g:ctrlp_max_depth|,
1083 g:ctrlp_live_update
1084 + New mapping: <c-^>
1085
1086 Before 2011/09/12~
1087
1088 + Ability to cycle through matched lines in the match window.
1089 + Extend the behavior of g:ctrlp_persistent_input
1090 + Extend the behavior of |:CtrlP|
1091 + New options: |g:ctrlp_dotfiles|,
1092 |g:ctrlp_clear_cache_on_exit|,
1093 g:ctrlp_highlight_match,
1094 |g:ctrlp_user_command|
1095 + New special input: '..' (|ctrlp-input-formats| (d))
1096 + New mapping: <F5>.
1097 + New commands: |:CtrlPCurWD|,
1098 |:CtrlPCurFile|,
1099 |:CtrlPRoot|
1100
1101 + New feature: Search in most recently used (MRU) files
1102 + New mapping: <c-b>.
1103 + Extended the behavior of <c-f>.
1104 + New options: g:ctrlp_mru_files,
1105 |g:ctrlp_mruf_max|,
1106 |g:ctrlp_mruf_exclude|,
1107 |g:ctrlp_mruf_include|
1108 + New command: |:CtrlPMRU|
1109
1110 First public release: 2011/09/06~
1111
1112 ===============================================================================
1113 vim:ft=help:et:ts=2:sw=2:sts=2:norl