| blob | 196eeb1112a32b151e8ac1a0f9092236bd81e115 |
1 *NERD_tree.txt* A tree explorer plugin that owns your momma!
5 omg its ... ~
7 ________ ________ _ ____________ ____ __________ ____________~
8 /_ __/ / / / ____/ / | / / ____/ __ \/ __ \ /_ __/ __ \/ ____/ ____/~
9 / / / /_/ / __/ / |/ / __/ / /_/ / / / / / / / /_/ / __/ / __/ ~
10 / / / __ / /___ / /| / /___/ _, _/ /_/ / / / / _, _/ /___/ /___ ~
11 /_/ /_/ /_/_____/ /_/ |_/_____/_/ |_/_____/ /_/ /_/ |_/_____/_____/ ~
14 Reference Manual~
19 ==============================================================================
20 CONTENTS *NERDTree-contents*
22 1.Intro...................................|NERDTree|
23 2.Functionality provided..................|NERDTreeFunctionality|
24 2.1 Global commands...................|NERDTreeGlobalCommands|
25 2.2 Bookmarks.........................|NERDTreeBookmarks|
26 2.2.1 The bookmark table..........|NERDTreeBookmarkTable|
27 2.2.2 Bookmark commands...........|NERDTreeBookmarkCommands|
28 2.2.3 Invalid bookmarks...........|NERDTreeInvalidBookmarks|
29 2.3 NERD tree mappings................|NERDTreeMappings|
30 2.4 The filesystem menu...............|NERDTreeFilesysMenu|
31 3.Options.................................|NERDTreeOptions|
32 3.1 Option summary....................|NERDTreeOptionSummary|
33 3.2 Option details....................|NERDTreeOptionDetails|
34 4.Public functions........................|NERDTreePublicFunctions|
35 5.TODO list...............................|NERDTreeTodo|
36 6.The Author..............................|NERDTreeAuthor|
37 7.Changelog...............................|NERDTreeChangelog|
38 8.Credits.................................|NERDTreeCredits|
39 9.License.................................|NERDTreeLicense|
41 ==============================================================================
42 1. Intro *NERDTree*
44 What is this "NERD tree"??
46 The NERD tree allows you to explore your filesystem and to open files and
47 directories. It presents the filesystem to you in the form of a tree which you
48 manipulate with the keyboard and/or mouse. It also allows you to perform
49 simple filesystem operations.
51 The following features and functionality are provided by the NERD tree:
52 * Files and directories are displayed in a hierarchical tree structure
53 * Different highlighting is provided for the following types of nodes:
54 * files
55 * directories
56 * sym-links
57 * windows .lnk files
58 * read-only files
59 * executable files
60 * Many (customisable) mappings are provided to manipulate the tree:
61 * Mappings to open/close/explore directory nodes
62 * Mappings to open files in new/existing windows/tabs
63 * Mappings to change the current root of the tree
64 * Mappings to navigate around the tree
65 * ...
66 * Directories and files can be bookmarked.
67 * Most NERD tree navigation can also be done with the mouse
68 * Dynamic customisation of tree content
69 * custom file filters to prevent e.g. vim backup files being displayed
70 * optional displaying of hidden files (. files)
71 * files can be "turned off" so that only directories are displayed
72 * A textual filesystem menu is provided which allows you to
73 create/delete/move file and directory nodes as well as copy (for
74 supported OSs)
75 * The position and size of the NERD tree window can be customised
76 * The order in which the nodes in the tree are listed can be customised.
77 * A model of your filesystem is created/maintained as you explore it. This
78 has several advantages:
79 * All filesystem information is cached and is only re-read on demand
80 * If you revisit a part of the tree that you left earlier in your
81 session, the directory nodes will be opened/closed as you left them
82 * The script remembers the cursor position and window position in the NERD
83 tree so you can toggle it off (or just close the tree window) and then
84 reopen it (with NERDTreeToggle) the NERD tree window will appear EXACTLY
85 as you left it
86 * You can have a separate NERD tree for each tab
88 ==============================================================================
89 2. Functionality provided *NERDTreeFunctionality*
91 ------------------------------------------------------------------------------
92 2.1. Global Commands *NERDTreeGlobalCommands*
94 :NERDTree [<start-directory> | <bookmark>] *:NERDTree*
95 Opens a fresh NERD tree. The root of the tree depends on the argument
96 given. There are 3 cases: If no argument is given, the current directory
97 will be used. If a directory is given, that will be used. If a bookmark
98 name is given, the corresponding directory will be used. For example: >
99 :NERDTree /home/marty/vim7/src
100 :NERDTree foo (foo is the name of a bookmark)
101 <
102 :NERDTreeFromBookmark <bookmark> *:NERDTreeFromBookmark*
103 Opens a fresh NERD tree with the root initialized to the dir for
104 <bookmark>. This only reason to use this command over :NERDTree is for
105 the completion (which is for bookmarks rather than directories).
107 :NERDTreeToggle [<start-directory> | <bookmark>] *:NERDTreeToggle*
108 If a NERD tree already exists for this tab, it is reopened and rendered
109 again. If no NERD tree exists for this tab then this command acts the
110 same as the |:NERDTree| command.
112 :NERDTreeClose
113 Close the NERD tree in this tab.
115 ------------------------------------------------------------------------------
116 2.2. Bookmarks *NERDTreeBookmarks*
118 Bookmarks in the NERD tree are a way to tag files or directories of interest.
119 For example, you could use bookmarks to tag all of your project directories.
121 ------------------------------------------------------------------------------
122 2.2.1. The Bookmark Table *NERDTreeBookmarkTable*
124 If the bookmark table is active (see |NERDTree-B| and
125 |'NERDTreeShowBookmarks'|), it will be rendered above the tree. You can double
126 click bookmarks or use the |NERDTree-o| mapping to activate them. See also,
127 |NERDTree-t| and |NERDTree-T|
129 ------------------------------------------------------------------------------
130 2.2.2. Bookmark commands *NERDTreeBookmarkCommands*
132 Note that the following commands are only available in the NERD tree buffer.
134 :Bookmark <name>
135 Bookmark the current node as <name>. If there is already a <name>
136 bookmark, it is overwritten. <name> must not contain spaces.
138 :BookmarkToRoot <bookmark>
139 Make the directory corresponding to <bookmark> the new root. If a treenode
140 corresponding to <bookmark> is already cached somewhere in the tree then
141 the current tree will be used, otherwise a fresh tree will be opened.
142 Note that if <bookmark> points to a file then its parent will be used
143 instead.
145 :RevealBookmark <bookmark>
146 If the node is cached under the current root then it will be revealed
147 (i.e. directory nodes above it will be opened) and the cursor will be
148 placed on it.
150 :OpenBookmark <bookmark>
151 <bookmark> must point to a file. The file is opened as though |NERDTree-o|
152 was applied. If the node is cached under the current root then it will be
153 revealed and the cursor will be placed on it.
155 :ClearBookmarks [<bookmarks>]
156 Remove all the given bookmarks. If no bookmarks are given then remove all
157 bookmarks on the current node.
159 :ClearAllBookmarks
160 Remove all bookmarks.
162 :ReadBookmarks
163 Re-read the bookmarks in the |'NERDTreeBookmarksFile'|.
165 See also |:NERDTree| and |:NERDTreeFromBookmark|.
167 ------------------------------------------------------------------------------
168 2.2.3. Invalid Bookmarks *NERDTreeInvalidBookmarks*
170 If invalid bookmarks are detected, the script will issue an error message and
171 the invalid bookmarks will become unavailable for use.
173 These bookmarks will still be stored in the bookmarks file (see
174 |'NERDTreeBookmarksFile'|), down the bottom. There will always be a blank line
175 after the valid bookmarks but before the invalid ones.
177 Each line in the bookmarks file represents one bookmark. The proper format is:
178 <bookmark name><space><full path to the bookmark location>
180 After you have corrected any invalid bookmarks, either restart vim, or go
181 :ReadBookmarks from the NERD tree window.
183 ------------------------------------------------------------------------------
184 2.3. NERD tree Mappings *NERDTreeMappings*
186 Default Description~ help-tag~
187 Key~
189 o.......Open files, directories and bookmarks....................|NERDTree-o|
190 go......Open selected file, but leave cursor in the NERDTree.....|NERDTree-go|
191 t.......Open selected node/bookmark in a new tab.................|NERDTree-t|
192 T.......Same as 't' but keep the focus on the current tab........|NERDTree-T|
193 <tab>...Open selected file in a split window.....................|NERDTree-tab|
194 g<tab>..Same as <tab>, but leave the cursor on the NERDTree......|NERDTree-gtab|
195 !.......Execute the current file.................................|NERDTree-!|
196 O.......Recursively open the selected directory..................|NERDTree-O|
197 x.......Close the current nodes parent...........................|NERDTree-x|
198 X.......Recursively close all children of the current node.......|NERDTree-X|
199 e.......Open a netrw for the current dir.........................|NERDTree-e|
201 double-click.......same as the |NERDTree-o| map.
202 middle-click.......same as |NERDTree-tab| for files, same as
203 |NERDTree-e| for dirs.
205 D.......Delete the current bookmark .............................|NERDTree-D|
207 P.......Jump to the root node....................................|NERDTree-P|
208 p.......Jump to current nodes parent.............................|NERDTree-p|
209 K.......Jump up inside directories at the current tree depth.....|NERDTree-K|
210 J.......Jump down inside directories at the current tree depth...|NERDTree-J|
211 <C-j>...Jump down to the next sibling of the current directory...|NERDTree-c-j|
212 <C-k>...Jump up to the previous sibling of the current directory.|NERDTree-c-k|
214 C.......Change the tree root to the selected dir.................|NERDTree-C|
215 u.......Move the tree root up one directory......................|NERDTree-u|
216 U.......Same as 'u' except the old root node is left open........|NERDTree-U|
217 r.......Recursively refresh the current directory................|NERDTree-r|
218 R.......Recursively refresh the current root.....................|NERDTree-R|
219 m.......Display the filesystem menu..............................|NERDTree-m|
220 cd......Change the CWD to the dir of the selected node...........|NERDTree-cd|
222 H.......Toggle whether hidden files displayed....................|NERDTree-H|
223 f.......Toggle whether the file filters are used.................|NERDTree-f|
224 F.......Toggle whether files are displayed.......................|NERDTree-F|
225 B.......Toggle whether the bookmark table is displayed...........|NERDTree-B|
227 q.......Close the NERDTree window................................|NERDTree-q|
228 ?.......Toggle the display of the quick help.....................|NERDTree-?|
230 ------------------------------------------------------------------------------
231 *NERDTree-o*
232 Default key: o
233 Map option: NERDTreeMapActivateNode
234 Applies to: files and directories.
236 If a file node is selected, it is opened in the previous window.
238 If a directory is selected it is opened or closed depending on its current
239 state.
241 If a bookmark that links to a directory is selected then that directory
242 becomes the new root.
244 If a bookmark that links to a file is selected then that file is opened in the
245 previous window.
247 ------------------------------------------------------------------------------
248 *NERDTree-go*
249 Default key: go
250 Map option: None
251 Applies to: files.
253 If a file node is selected, it is opened in the previous window, but the
254 cursor does not move.
256 The key combo for this mapping is always "g" + NERDTreeMapActivateNode (see
257 |NERDTree-o|).
259 ------------------------------------------------------------------------------
260 *NERDTree-t*
261 Default key: t
262 Map option: NERDTreeMapOpenInTab
263 Applies to: files and directories.
265 Opens the selected file in a new tab. If a directory is selected, a fresh
266 NERD Tree for that directory is opened in a new tab.
268 If a bookmark which points to a directory is selected, open a NERD tree for
269 that directory in a new tab. If the bookmark points to a file, open that file
270 in a new tab.
272 ------------------------------------------------------------------------------
273 *NERDTree-T*
274 Default key: T
275 Map option: NERDTreeMapOpenInTabSilent
276 Applies to: files and directories.
278 The same as |NERDTree-t| except that the focus is kept in the current tab.
280 ------------------------------------------------------------------------------
281 *NERDTree-tab*
282 Default key: <tab>
283 Map option: NERDTreeMapOpenSplit
284 Applies to: files.
286 Opens the selected file in a new split window and puts the cursor in the new
287 window.
289 ------------------------------------------------------------------------------
290 *NERDTree-gtab*
291 Default key: g<tab>
292 Map option: None
293 Applies to: files.
295 The same as |NERDTree-tab| except that the cursor is not moved.
297 The key combo for this mapping is always "g" + NERDTreeMapOpenSplit (see
298 |NERDTree-tab|).
300 ------------------------------------------------------------------------------
301 *NERDTree-!*
302 Default key: !
303 Map option: NERDTreeMapExecute
304 Applies to: files.
306 Executes the selected file, prompting for arguments first.
308 ------------------------------------------------------------------------------
309 *NERDTree-O*
310 Default key: O
311 Map option: NERDTreeMapOpenRecursively
312 Applies to: directories.
314 Recursively opens the selelected directory.
316 All files and directories are cached, but if a directory would not be
317 displayed due to file filters (see |'NERDTreeIgnore'| |NERDTree-f|) or the
318 hidden file filter (see |'NERDTreeShowHidden'|) then its contents are not
319 cached. This is handy, especially if you have .svn directories.
321 ------------------------------------------------------------------------------
322 *NERDTree-x*
323 Default key: x
324 Map option: NERDTreeMapCloseDir
325 Applies to: files and directories.
327 Closes the parent of the selected node.
329 ------------------------------------------------------------------------------
330 *NERDTree-X*
331 Default key: X
332 Map option: NERDTreeMapCloseChildren
333 Applies to: directories.
335 Recursively closes all children of the selected directory.
337 Tip: To quickly "reset" the tree, use |NERDTree-P| with this mapping.
339 ------------------------------------------------------------------------------
340 *NERDTree-e*
341 Default key: e
342 Map option: NERDTreeMapOpenExpl
343 Applies to: files and directories.
345 Opens a netrw on the selected directory, or the selected file's directory.
347 ------------------------------------------------------------------------------
348 *NERDTree-D*
349 Default key: D
350 Map option: NERDTreeMapDeleteBookmark
351 Applies to: lines in the bookmarks table
353 Deletes the currently selected bookmark.
355 ------------------------------------------------------------------------------
356 *NERDTree-P*
357 Default key: P
358 Map option: NERDTreeMapJumpRoot
359 Applies to: no restrictions.
361 Jump to the tree root.
363 ------------------------------------------------------------------------------
364 *NERDTree-p*
365 Default key: p
366 Map option: NERDTreeMapJumpParent
367 Applies to: files and directories.
369 Jump to the parent node of the selected node.
371 ------------------------------------------------------------------------------
372 *NERDTree-K*
373 Default key: K
374 Map option: NERDTreeMapJumpFirstChild
375 Applies to: files and directories.
377 Jump to the first child of the current nodes parent.
379 If the cursor is already on the first node then do the following:
380 * loop back thru the siblings of the current nodes parent until we find an
381 open dir with children
382 * go to the first child of that node
384 ------------------------------------------------------------------------------
385 *NERDTree-J*
386 Default key: J
387 Map option: NERDTreeMapJumpLastChild
388 Applies to: files and directories.
390 Jump to the last child of the current nodes parent.
392 If the cursor is already on the last node then do the following:
393 * loop forward thru the siblings of the current nodes parent until we find
394 an open dir with children
395 * go to the last child of that node
397 ------------------------------------------------------------------------------
398 *NERDTree-c-j*
399 Default key: <C-j>
400 Map option: NERDTreeMapJumpNextSibling
401 Applies to: files and directories.
403 Jump to the next sibling of the selected node.
405 ------------------------------------------------------------------------------
406 *NERDTree-c-k*
407 Default key: <C-k>
408 Map option: NERDTreeMapJumpPrevSibling
409 Applies to: files and directories.
411 Jump to the previous sibling of the selected node.
413 ------------------------------------------------------------------------------
414 *NERDTree-C*
415 Default key: C
416 Map option: NERDTreeMapChdir
417 Applies to: directories.
419 Make the selected directory node the new tree root. If a file is selected, its
420 parent is used.
422 ------------------------------------------------------------------------------
423 *NERDTree-u*
424 Default key: u
425 Map option: NERDTreeMapUpdir
426 Applies to: no restrictions.
428 Move the tree root up a dir (like doing a "cd ..").
430 ------------------------------------------------------------------------------
431 *NERDTree-U*
432 Default key: U
433 Map option: NERDTreeMapUpdirKeepOpen
434 Applies to: no restrictions.
436 Like |NERDTree-u| except that the old tree root is kept open.
438 ------------------------------------------------------------------------------
439 *NERDTree-r*
440 Default key: r
441 Map option: NERDTreeMapRefresh
442 Applies to: files and directories.
444 If a dir is selected, recursively refresh that dir, i.e. scan the filesystem
445 for changes and represent them in the tree.
447 If a file node is selected then the above is done on it's parent.
449 ------------------------------------------------------------------------------
450 *NERDTree-R*
451 Default key: R
452 Map option: NERDTreeMapRefreshRoot
453 Applies to: no restrictions.
455 Recursively refresh the tree root.
457 ------------------------------------------------------------------------------
458 *NERDTree-m*
459 Default key: m
460 Map option: NERDTreeMapFilesystemMenu
461 Applies to: files and directories.
463 Display the filesystem menu. See |NERDTreeFilesysMenu| for details.
465 ------------------------------------------------------------------------------
466 *NERDTree-H*
467 Default key: H
468 Map option: NERDTreeMapToggleHidden
469 Applies to: no restrictions.
471 Toggles whether hidden files are displayed. Hidden files are any
472 file/directory that starts with a "."
474 ------------------------------------------------------------------------------
475 *NERDTree-f*
476 Default key: f
477 Map option: NERDTreeMapToggleFilters
478 Applies to: no restrictions.
480 Toggles whether file filters are used. See |'NERDTreeIgnore'| for details.
482 ------------------------------------------------------------------------------
483 *NERDTree-F*
484 Default key: F
485 Map option: NERDTreeMapToggleFiles
486 Applies to: no restrictions.
488 Toggles whether file nodes are displayed.
490 ------------------------------------------------------------------------------
491 *NERDTree-B*
492 Default key: B
493 Map option: NERDTreeMapToggleBookmarks
494 Applies to: no restrictions.
496 Toggles whether the bookmarks table is displayed.
498 ------------------------------------------------------------------------------
499 *NERDTree-q*
500 Default key: q
501 Map option: NERDTreeMapQuit
502 Applies to: no restrictions.
504 Closes the NERDtree window.
506 ------------------------------------------------------------------------------
507 *NERDTree-?*
508 Default key: ?
509 Map option: NERDTreeMapHelp
510 Applies to: no restrictions.
512 Toggles whether the quickhelp is displayed.
514 ------------------------------------------------------------------------------
515 2.3. The filesystem menu *NERDTreeFilesysMenu*
517 The purpose of the filesystem menu is to allow you to perform basic filesystem
518 operations quickly from the NERD tree rather than the console.
520 The filesystem menu can be accessed with 'm' mapping and has four supported
521 operations: >
522 1. Adding nodes.
523 2. Move nodes.
524 3. Deleting nodes.
525 3. Copying nodes.
526 <
527 1. Adding nodes:
528 To add a node move the cursor onto (or anywhere inside) the directory you wish
529 to create the new node inside. Select the 'add node' option from the
530 filesystem menu and type a filename. If the filename you type ends with a '/'
531 character then a directory will be created. Once the operation is completed,
532 the cursor is placed on the new node.
534 2. Move nodes:
535 To move/rename a node, put the cursor on it and select the 'move' option from
536 the filesystem menu. Enter the new location for the node and it will be
537 moved. If the old file is open in a buffer, you will be asked if you wish to
538 delete that buffer. Once the operation is complete the cursor will be placed
539 on the renamed node.
541 3. Deleting nodes:
542 To delete a node put the cursor on it and select the 'delete' option from the
543 filesystem menu. After confirmation the node will be deleted. If a file is
544 deleted but still exists as a buffer you will be given the option to delete
545 that buffer.
547 4. Copying nodes:
548 To copy a node put the cursor on it and select the 'copy' option from the
549 filesystem menu. Enter the new location and you're done. Note: copying is
550 currently only supported for *nix operating systems. If someone knows a
551 one line copying command for windows that doesnt require user confirmation
552 then id be grateful if you'd email me.
554 ==============================================================================
555 3. Customisation *NERDTreeOptions*
558 ------------------------------------------------------------------------------
559 3.1. Customisation summary *NERDTreeOptionSummary*
561 The script provides the following options that can customise the behaviour the
562 NERD tree. These options should be set in your vimrc.
564 |'loaded_nerd_tree'| Turns off the script.
566 |'NERDChristmasTree'| Tells the NERD tree to make itself colourful
567 and pretty.
569 |'NERDTreeAutoCenter'| Controls whether the NERD tree window centers
570 when the cursor moves within a specified
571 distance to the top/bottom of the window.
572 |'NERDTreeAutoCenterThreshold'| Controls the sensitivity of autocentering.
574 |'NERDTreeCaseSensitiveSort'| Tells the NERD tree whether to be case
575 sensitive or not when sorting nodes.
577 |'NERDTreeChDirMode'| Tells the NERD tree if/when it should change
578 vim's current working directory.
580 |'NERDTreeHighlightCursorline'| Tell the NERD tree whether to highlight the
581 current cursor line.
583 |'NERDTreeIgnore'| Tells the NERD tree which files to ignore.
585 |'NERDTreeBookmarksFile'| Where the bookmarks are stored.
587 |'NERDTreeMouseMode'| Tells the NERD tree how to handle mouse
588 clicks.
590 |'NERDTreeQuitOnOpen'| Closes the tree window after opening a file.
592 |'NERDTreeShowBookmarks'| Tells the NERD tree whether to display the
593 bookmarks table on startup.
595 |'NERDTreeShowFiles'| Tells the NERD tree whether to display files
596 in the tree on startup.
598 |'NERDTreeShowHidden'| Tells the NERD tree whether to display hidden
599 files on startup.
601 |'NERDTreeShowLineNumbers'| Tells the NERD tree whether to display line
602 numbers in the tree window.
604 |'NERDTreeSortOrder'| Tell the NERD tree how to sort the nodes in
605 the tree.
607 |'NERDTreeWinPos'| Tells the script where to put the NERD tree
608 window.
610 |'NERDTreeWinSize'| Sets the window size when the NERD tree is
611 opened.
613 ------------------------------------------------------------------------------
614 3.2. Customisation details *NERDTreeOptionDetails*
616 To enable any of the below options you should put the given line in your
617 ~/.vimrc
619 *'loaded_nerd_tree'*
620 If this plugin is making you feel homicidal, it may be a good idea to turn it
621 off with this line in your vimrc: >
622 let loaded_nerd_tree=1
623 <
624 ------------------------------------------------------------------------------
625 *'NERDChristmasTree'*
626 Values: 0 or 1.
627 Default: 1.
629 If this option is set to 1 then some extra syntax highlighting elements are
630 added to the nerd tree to make it more colourful.
632 Set it to 0 for a more vanilla looking tree.
634 ------------------------------------------------------------------------------
635 *'NERDTreeAutoCenter'*
636 Values: 0 or 1.
637 Default: 1
639 If set to 1, the NERD tree window will center around the cursor if it moves to
640 within |'NERDTreeAutoCenterThreshold'| lines of the top/bottom of the window.
642 This is ONLY done in response to tree navigation mappings,
643 i.e. |NERDTree-J| |NERDTree-K| |NERDTree-C-J| |NERDTree-c-K| |NERDTree-p|
644 |NERDTree-P|
646 The centering is done with a |zz| operation.
648 ------------------------------------------------------------------------------
649 *'NERDTreeAutoCenterThreshold'*
650 Values: Any natural number.
651 Default: 3
653 This option controls the "sensitivity" of the NERD tree auto centering. See
654 |'NERDTreeAutoCenter'| for details.
656 ------------------------------------------------------------------------------
657 *'NERDTreeCaseSensitiveSort'*
658 Values: 0 or 1.
659 Default: 0.
661 By default the NERD tree does not sort nodes case sensitively, i.e. nodes
662 could appear like this: >
663 bar.c
664 Baz.c
665 blarg.c
666 boner.c
667 Foo.c
668 <
669 But, if you set this option to 1 then the case of the nodes will be taken into
670 account. The above nodes would then be sorted like this: >
671 Baz.c
672 Foo.c
673 bar.c
674 blarg.c
675 boner.c
676 <
677 ------------------------------------------------------------------------------
678 *'NERDTreeChDirMode'*
680 Values: 0, 1 or 2.
681 Default: 0.
683 Use this option to tell the script when (if at all) to change the current
684 working directory (CWD) for vim.
686 If it is set to 0 then the CWD is never changed by the NERD tree.
688 If set to 1 then the CWD is changed when the NERD tree is first loaded to the
689 directory it is initialized in. For example, if you start the NERD tree with >
690 :NERDTree /home/marty/foobar
691 <
692 then the CWD will be changed to /home/marty/foobar and will not be changed
693 again unless you init another NERD tree with a similar command.
695 If the option is set to 2 then it behaves the same as if set to 1 except that
696 the CWD is changed whenever the tree root is changed. For example, if the CWD
697 is /home/marty/foobar and you make the node for /home/marty/foobar/baz the new
698 root then the CWD will become /home/marty/foobar/baz.
700 ------------------------------------------------------------------------------
701 *'NERDTreeHighlightCursorline'*
702 Values: 0 or 1.
703 Default: 1.
705 If set to 1, the current cursor line in the NERD tree buffer will be
706 highlighted. This is done using the |cursorline| option.
708 ------------------------------------------------------------------------------
709 *'NERDTreeIgnore'*
710 Values: a list of regular expressions.
711 Default: ['\~$'].
713 This option is used to specify which files the NERD tree should ignore. It
714 must be a list of regular expressions. When the NERD tree is rendered, any
715 files/dirs that match any of the regex's in 'NERDTreeIgnore' wont be
716 displayed.
718 For example if you put the following line in your vimrc: >
719 let NERDTreeIgnore=['\.vim$', '\~$']
720 <
721 then all files ending in .vim or ~ will be ignored.
723 Note: to tell the NERD tree not to ignore any files you must use the following
724 line: >
725 let NERDTreeIgnore=[]
726 <
728 The file filters can be turned on and off dynamically with the |NERDTree-f|
729 mapping.
731 ------------------------------------------------------------------------------
732 *'NERDTreeBookmarksFile'*
733 Values: a path
734 Default: $HOME/.NERDTreeBookmarks
736 This is where bookmarks are saved. See |NERDTreeBookmarkCommands|.
738 ------------------------------------------------------------------------------
739 *'NERDTreeMouseMode'*
740 Values: 1, 2 or 3.
741 Default: 1.
743 If set to 1 then a double click on a node is required to open it.
744 If set to 2 then a single click will open directory nodes, while a double
745 click will still be required for file nodes.
746 If set to 3 then a single click will open any node.
748 Note: a double click anywhere on a line that a tree node is on will
749 activate it, but all single-click activations must be done on name of the node
750 itself. For example, if you have the following node: >
751 | | |-application.rb
752 <
753 then (to single click activate it) you must click somewhere in
754 'application.rb'.
756 ------------------------------------------------------------------------------
757 *'NERDTreeQuitOnOpen'*
759 Values: 0 or 1.
760 Default: 0
762 If set to 1, the NERD tree window will close after opening a file with the
763 |NERDTree-o| or |NERDTree-tab| mappings.
765 ------------------------------------------------------------------------------
766 *'NERDTreeShowBookmarks'*
767 Values: 0 or 1.
768 Default: 0.
770 If this option is set to 1 then the bookmarks table will be displayed.
772 This option can be toggled dynamically, per tree, with the |NERDTree-B|
773 mapping.
775 ------------------------------------------------------------------------------
776 *'NERDTreeShowFiles'*
777 Values: 0 or 1.
778 Default: 1.
780 If this option is set to 1 then files are displayed in the NERD tree. If it is
781 set to 0 then only directories are displayed.
783 This option can be toggled dynamically, per tree, with the |NERDTree-F|
784 mapping and is useful for drastically shrinking the tree when you are
785 navigating to a different part of the tree.
787 ------------------------------------------------------------------------------
788 *'NERDTreeShowHidden'*
789 Values: 0 or 1.
790 Default: 0.
792 This option tells vim whether to display hidden files by default. This option
793 can be dynamically toggled, per tree, with the |NERDTree-H| mapping. Use one
794 of the follow lines to set this option: >
795 let NERDTreeShowHidden=0
796 let NERDTreeShowHidden=1
797 <
799 ------------------------------------------------------------------------------
800 *'NERDTreeShowLineNumbers'*
801 Values: 0 or 1.
802 Default: 0.
804 This option tells vim whether to display line numbers for the NERD tree
805 window. Use one of the follow lines to set this option: >
806 let NERDTreeShowLineNumbers=0
807 let NERDTreeShowLineNumbers=1
808 <
810 ------------------------------------------------------------------------------
811 *'NERDTreeSortOrder'*
812 Values: a list of regular expressions.
813 Default: ['\/$', '*', '\.swp$', '\.bak$', '\~$']
815 This option is set to a list of regular expressions which are used to
816 specify the order of nodes under their parent.
818 For example, if the option is set to: >
819 ['\.vim$', '\.c$', '\.h$', '*', 'foobar']
820 <
821 then all .vim files will be placed at the top, followed by all .c files then
822 all .h files. All files containing the string 'foobar' will be placed at the
823 end. The star is a special flag: it tells the script that every node that
824 doesnt match any of the other regexps should be placed here.
826 If no star is present in 'NERDTreeSortOrder' then one is automatically
827 appended to the array.
829 The regex '\/$' should be used to match directory nodes.
831 After this sorting is done, the files in each group are sorted alphabetically.
833 Other examples: >
834 (1) ['*', '\/$']
835 (2) []
836 (3) ['\/$', '\.rb$', '\.php$', '*', '\.swp$', '\.bak$', '\~$']
837 <
838 1. Directories will appear last, everything else will appear above.
839 2. Everything will simply appear in alphabetical order.
840 3. Dirs will appear first, then ruby and php. Swap files, bak files and vim
841 backup files will appear last with everything else preceding them.
843 ------------------------------------------------------------------------------
844 *'NERDTreeWinPos'*
845 Values: "left", "right", "top" or "bottom"
846 Default: "left".
848 This option is used to determine where NERD tree window is placed on the
849 screen.
851 "top" or "bottom", will cause a horizontal split to be created for the tree,
852 while "left" and "right" will cause a vertical split.
854 This option is makes it possible to use two different explorer type
855 plugins simultaneously. For example, you could have the taglist plugin on the
856 left of the window and the NERD tree on the right.
858 ------------------------------------------------------------------------------
859 *'NERDTreeWinSize'*
860 Values: a positive integer.
861 Default: 31.
863 This option is used to change the size of the NERD tree when it is loaded.
865 ==============================================================================
866 *NERDTreePublicFunctions*
867 5. Public functions ~
869 The script provides 2 public functions for your hacking pleasure. Their
870 signatures are: >
871 function! NERDTreeGetCurrentNode()
872 function! NERDTreeGetCurrentPath()
873 <
874 The first returns the node object that the cursor is currently on, while the
875 second returns the corresponding path object.
877 This is probably a good time to mention that the script implements prototype
878 style OO. To see the functions that each class provides you can read look at
879 the code.
881 Use the node objects to manipulate the structure of the tree. Use the path
882 objects to access the data the tree represents and to make changes to the
883 filesystem.
885 ==============================================================================
886 5. TODO list *NERDTreeTodo*
888 Window manager integration?
890 ==============================================================================
891 6. The Author *NERDTreeAuthor*
893 The author of the NERD tree is a terrible terrible monster called Martyzilla
894 who gobbles up small children with milk and sugar for breakfast.
896 He can be reached at martin_grenfell at msn.com. He would love to hear from
897 you, so feel free to send him suggestions and/or comments about this plugin.
898 Don't be shy --- the worst he can do is slaughter you and stuff you in the
899 fridge for later ;)
901 ==============================================================================
902 7. Changelog *NERDTreeChangelog*
904 2.14.1
905 - dont clobber &cpo. Thanks to godlygeek for the bug report.
906 - a bunch of other minor fixes and refactoring
908 2.14.0
909 - fix a bug where the <c-w>o mapping would cause the tree window to be
910 incorrectly sized when reopened.
911 - add keymapping to delete bookmarks from the bookmarks table, see
912 :help NERDTree-D
913 - lots of refactoring
914 2.13.0
915 - make NERDTreeChDir option default to 0 (i.e. never change vims current
916 working dir by default)
917 - when moving/deleting nodes with the filesystem menu, move/delete any
918 associated bookmarks
919 - make the t/T on directory nodes open a fresh NERD tree for the selected
920 dir in a new tab, rather than a netrw.
921 - place the cursor at the top of the bookmarks table when opening it with B
922 - make NERDTreeQuitOnOpen option work with the g<tab> and go mappings,
923 thanks to Maxim Kim for the bug report
924 - change how invalid bookmarks are handled. Now they are not deleted. If a
925 bookmark is malformed (in the bookmarks file) or points to an
926 invalid/nonexisting location then print an error and place the offending
927 bookmarks at the bottom of the bookmarks file. See :help
928 |NERDTreeInvalidBookmarks| for info. Thanks to Zhang Shuhan for the
929 suggestion and the testing.
930 - fix a bug with the 'o' mapping that occurred when opening a new buffer
931 for a file whose name was a substring of an already open file. Thanks to
932 Charlton Wang for the report.
933 - stop the script from going into an infinite loop when it tries to cache
934 a named pipe. Thanks to Charlton Wang for the report.
936 2.12.0
937 - added a UI for bookmarks. See :help NERDTreeBookmarkTable for details.
938 Thanks to Zhang Shuhan for testing and bug reports.
939 - relaxed the restrictions on bookmark names, now the only restriction is
940 that they cant contain spaces. This allows for e.g. Chinese bookmark
941 names. Thanks to Zhang Shuhan for the suggestion.
942 - combined the NERDTreeWinPos and NERDTreeSplitVertical options. See :help
943 NERDTreeWinPos.
944 - applied a patch from Matan Nassau to add the NERDTreeQuitOnOpen option
945 which closes the tree window after opening a file. See :help
946 NERDTreeQuitOnOpen.
947 - optimised the nerd tree rendering. Now it takes just over 1/3 of the
948 time it previously took to render.
949 - now the tree filter mappings toggle the filters "per tree" rather than
950 globally. The global filter variables are used to set the initial filter
951 settings for each new NERD tree.
952 - fix to window resizing when opening a file when NERD tree is the only
953 window open
954 - other fixes
956 2.11.0
957 - changes to the 'o' mapping when opening files:
958 - dont clobber "special" windows (eg taglist/quickfix/etc). This should
959 make the NERD tree play nicer with other explorer plugins. Thanks to
960 Yuan Jiang for the suggestion.
961 - if the file is already open in the current tab, just move the cursor
962 to that window
963 - highlight executable files, made some slight changes to other
964 highlighting
965 - if the user resizes the tree window, keep that new size. Dont reset to
966 the default during the <tab> mapping, or :NERDTreeToggle command. Only
967 reset the size if a fresh tree is started with :NERDTree.
968 - remove the "magic" functionality from the <c-j>/<c-k> mappings (it was
969 more confusing than helpful)
970 - other minor fixes
972 2.10.0
973 - added bookmarks, see :help NERDTreeBookmarkCommands for details. Thanks
974 to Piotr Czachur for all his testing and suggestions.
975 - fixed screen jumping bug with when &scrolloff != 0
976 - fixed some bugs with copying nodes
977 - other random fixes
978 - change license to wtfpl
980 2.9.0
982 - path handling improvements, thanks to Zhang Shuhan for heaps of
983 testing/bug reports
984 * improved how paths are stored, now the script will no longer get
985 confused about drives on MF Windows
986 * made the script way better at handling paths with strange characters
987 in them (eg '$@; etc)
988 - applied a patch from Cory Echols
989 * add the command :NERDTreeClose to close the tree for the current tab
990 * set the filetype for the NERD tree buffer to "nerdtree"
992 2.8.0
993 - added an option to enable/disable line numbers in the NERD tree window,
994 thanks to Olivier Yiptong for the email.
996 2.7.1
997 - Changed the keys for the filesystem menu to be mnemonic rather than
998 arbitrary integers
999 - Documented the copying functionality in the filesystem menu
1001 2.7.0
1002 - Bug fix: Now when you have the tree on the right and you open it with
1003 multiple windows stacked, it will take up the full height of the vim
1004 window.
1005 - Now line numbers always turned off in the tree by default
1006 - Implemented copying of nodes (via the filesystem menu) for *nix/macosx
1007 - took the help doc out of the script and repackaged the whole thing as a
1008 zip
1010 2.6.2
1011 - Now when you try to open a file node into a window that is modified, the
1012 window is not split if the &hidden option is set. Thanks to Niels Aan
1013 de Brugh for this suggestion.
1015 2.6.1
1016 - Fixed a major bug with the <tab> mapping. Thanks to Zhang Weiwu for
1017 emailing me.
1019 2.6.0
1020 - Extended the behaviour of <c-j/k>. Now if the cursor is on a file node
1021 and you use <c-j/k> the cursor will jump to its PARENTS next/previous
1022 sibling. Go :help NERDTree-c-j and :help NERDTree-c-k for info.
1023 - Extended the behaviour of the J/K mappings. Now if the cursor is on the
1024 last child of a node and you push J/K it will jump down to the last
1025 child of the next/prev of its parents siblings that is open and has
1026 children. Go :help NERDTree-J and :help NERDTree-K for info.
1027 - The goal of these changes is to make tree navigation faster.
1028 - Reorganised the help page a bit.
1029 - Removed the E mapping.
1030 - bugfixes
1032 2.5.0
1033 - Added an option to enforce case sensitivity when sorting tree nodes.
1034 Read :help NERDTreeCaseSensitiveSort for details. (thanks to Michael
1035 Madsen for emailing me about this). Case sensitivity defaults to off.
1036 - Made the script echo a "please wait" style message when opening large
1037 directories. Thanks to AOYAMA Shotaro for this suggestion.
1038 - Added 2 public functions that can be used to retrieve the treenode and
1039 path that the cursor is on. Read :help NERDTreePublicFunctions for
1040 details (thanks again to AOYAMA Shotaro for the idea :).
1041 - added 2 new mappings for file nodes: "g<tab>" and "go". These are the
1042 same as the "<tab>" and "o" maps except that the cursor stays in the
1043 NERDTree. Note: these maps are slaved to the o and <tab> mappings, so if
1044 eg you remap "<tab>" to "i" then the "g<tab>" map will also be changed
1045 to "gi".
1046 - Renamed many of the help tags to be simpler.
1047 - Simplified the ascii "graphics" for the filesystem menu
1048 - Fixed bugs.
1049 - Probably created bugs.
1050 - Refactoring.
1052 2.4.0
1053 - Added the P mapping to jump to the tree root.
1054 - Added window centering functionality that can be triggered when doing
1055 using any of the tree nav mappings. Essentially, if the cursor comes
1056 within a certain distance of the top/bottom of the window then a zz is
1057 done in the window. Two related options were added: NERDTreeAutoCenter
1058 to turn this functionality on/off, and NERDTreeAutoCenterThreshold to
1059 control how close the cursor has to be to the window edge to trigger the
1060 centering.
1062 2.3.0
1063 - Tree navigation changes:
1064 - Added J and K mappings to jump to last/first child of the current dir.
1065 Options to customise these mappings have also been added.
1066 - Remapped the jump to next/prev sibling commands to be <C-j> and <C-k>
1067 by default.
1068 These changes should hopefully make tree navigation mappings easier to
1069 remember and use as the j and k keys are simply reused 3 times (twice
1070 with modifier keys).
1072 - Made it so that, when any of the tree filters are toggled, the cursor
1073 stays with the selected node (or goes to its parent/grandparent/... if
1074 that node is no longer visible)
1075 - Fixed an error in the doc for the mouse mode option.
1076 - Made the quickhelp correctly display the current single/double click
1077 mappings for opening nodes as specified by the NERDTreeMouseMode option.
1078 - Fixed a bug where the script was spazzing after prompting you to delete
1079 a modified buffer when using the filesystem menu.
1080 - Refactoring
1081 2.2.3
1082 - Refactored the :echo output from the script.
1083 - Fixed some minor typos in the doc.
1084 - Made some minor changes to the output of the 'Tree filtering mappings'
1085 part of the quickhelp
1087 2.2.2
1088 - More bugfixes... doh.
1090 2.2.1
1091 - Bug fix that was causing an exception when closing the nerd tree. Thanks
1092 to Tim carey-smith and Yu Jun for pointing this out.
1094 2.2.0
1095 - Now 'cursorline' is set in the NERD tree buffer by default. See :help
1096 NERDTreeHighlightCursorline for how to disable it.
1098 2.1.2
1099 - Stopped the script from clobbering the 1,2,3 .. 9 registers.
1100 - Made it "silent!"ly delete buffers when renaming/deleting file nodes.
1101 - Minor correction to the doc
1102 - Fixed a bug when refreshing that was occurring when the node you
1103 refreshed had been deleted externally.
1104 - Fixed a bug that was occurring when you open a file that is already open
1105 and modified.
1107 2.1.1
1108 - Added a bit more info about the buffers you are prompted to delete when
1109 renaming/deleting nodes from the filesystem menu that are already loaded
1110 into buffers.
1111 - Refactoring and bugfixes
1113 2.1.0
1114 - Finally removed the blank line that always appears at the top of the
1115 NERDTree buffer
1116 - Added NERDTreeMouseMode option. If set to 1, then a double click is
1117 required to activate all nodes, if set to 2 then a single click will
1118 activate directory nodes, if set to 3 then a single click will activate
1119 all nodes.
1120 - Now if you delete a file node and have it open in a buffer you are given
1121 the option to delete that buffer as well. Similarly if you rename a file
1122 you are given the option to delete any buffers containing the old file
1123 (if any exist)
1124 - When you rename or create a node, the cursor is now put on the new node,
1125 this makes it easy immediately edit the new file.
1126 - Fixed a bug with the ! mapping that was occurring on windows with paths
1127 containing spaces.
1128 - Made all the mappings customisable. See |NERD_tree-mappings| for
1129 details. A side effect is that a lot of the "double mappings" have
1130 disappeared. E.g 'o' is now the key that is used to activate a node,
1131 <CR> is no longer mapped to the same.
1132 - Made the script echo warnings in some places rather than standard echos
1133 - Insane amounts of refactoring all over the place.
1135 2.0.0
1136 - Added two new NERDChristmasTree decorations. First person to spot them
1137 and email me gets a free copy of the NERDTree.
1138 - Made it so that when you jump around the tree (with the p, s and S
1139 mappings) it is counted as a jump by vim. This means if you, eg, push
1140 'p' one too many times then you can go `` or ctrl-o.
1141 - Added a new option called NERDTreeSortOrder which takes an array of
1142 regexs and is used to determine the order that the treenodes are listed
1143 in. Go :help NERDTreeSortOrder for details.
1144 - Removed the NERDTreeSortDirs option because it is consumed by
1145 NERDTreeSortOrder
1146 - Added the 'i' mapping which is the same as <tab> but requires less
1147 effort to reach.
1148 - Added the ! mapping which is used to execute file in the tree (after it
1149 prompts you for arguments etc)
1152 ==============================================================================
1153 8. Credits *NERDTreeCredits*
1155 Thanks to Tim Carey-Smith for testing/using the NERD tree from the first
1156 pre-beta version, for his many suggestions and for his constant stream of bug
1157 complaints.
1159 Thanks to Vigil for trying it out before the first release :) and suggesting
1160 that mappings to open files in new tabs should be implemented.
1162 Thanks to Nick Brettell for testing, fixing my spelling and suggesting i put a
1163 .. (up a directory)
1164 line in the gui.
1166 Thanks to Thomas Scott Urban - the author of the vtreeexplorer plugin - whose
1167 gui code i borrowed from.
1169 Thanks to Terrance Cohen for pointing out a bug where the script was changing
1170 vims CWD all over the show.
1172 Thanks to Yegappan Lakshmanan (author of Taglist and other orgasmically
1173 wonderful plugins) for telling me how to fix a bug that was causing vim to go
1174 into visual mode everytime you double clicked a node :)
1176 Thanks to Jason Mills for sending me a fix that allows windows paths to use
1177 forward slashes as well as backward.
1179 Thanks to Michael Geddes (frogonwheels on #vim at freenode) for giving me some
1180 tips about syntax highlighting when i was doing highlighting for the
1181 quickhelp.
1183 Thanks to Yu Jun for emailing me about a bug that was occurring when closing
1184 the tree.
1186 Thanks to Michael Madsen for emailing me about making case sensitivity
1187 optional when sorting nodes.
1189 Thanks to AOYAMA Shotaro for suggesting that i echo a "please wait" message
1190 when opening large directories.
1192 Thanks to Michael Madsen for requesting the NERDTreeCaseSensitiveSort option.
1194 Thanks to AOYAMA Shotaro for suggesting that a "please wait" style message be
1195 echoed when opening large directories. Also, thanks for the suggestion of
1196 having public functions in the script to access the internal data :D
1198 Thanks to Zhang Weiwu for emailing me about a bug with the the <tab> mapping
1199 in 2.6.0
1201 Thanks to Niels Aan de Brugh for the suggestion that the script now split the
1202 window if you try to open a file in a window containing a modified buffer when
1203 the &hidden option is set.
1205 Thanks to Olivier Yiptong for prompting me to make line numbers in the
1206 NERD tree window optional.
1208 Thanks to Zhang Shuhan for all of his emails and testing to help improve the
1209 NERD tree path handling. Thanks also for suggesting the bookmarks gui, and for
1210 testing and his many suggestions and bugreports about bookmarks.
1212 Thanks to Cory Echols for sending a patch to add the :NERDTreeClose command and
1213 set the NERD tree buffers filetype to 'nerdtree'
1215 Thanks to Piotr Czachur for all his suggestions and testing for the bookmarks
1216 feature.
1218 Thanks to Yuan Jiang for suggesting the "o" mapping shouldnt clobber "special"
1219 windows, like taglist.
1221 Thanks to Matan Nassau for the patch to add the NERDTreeQuitOnOpen option.
1223 Thanks to Maxim Kim for reporting a bug with g<tab> and go mappings when
1224 NERDTreeQuitOnOpen was set.
1226 Thanks to Charlton Wang for reporting bugs with the 'o' mapping and with
1227 handling named pipes.
1229 Chur to godlygeek for reporting a bug where &cpo was getting clobbered.
1231 ==============================================================================
1232 9. License *NERDTreeLicense*
1234 The NERD tree is released under the wtfpl.
1235 See http://sam.zoy.org/wtfpl/COPYING.