1 *NERDTree.txt* A tree explorer plugin to rule the Vim world. Bwahahaha!! 2 3 # #### #### ~ 4 ### \/#|### |/#### ~ 5 d8 888 ##\/#/ \||/##/_/##/_# ~ 6 d88 888 ee ,e e, ### \/###|/ \/ # ### ~ 7 d88888 888 88b d88 88b ##_\_#\_\## | #/###_/_#### ~ 8 888 888 888 888 , ## #### # \ #| / #### ##/## ~ 9 888 888 888 "YeeP" __#_--###`. |{,###---###-~ ~ 10 \ % @% ~ 11 Y88b Y88 888'Y88 888 88e 888 88e \%@% 88P'888'Y88 ~ 12 Y88b Y8 888 ,'Y 888 888D 888 888b %o% P' 888 'Y 888,8, ,e e, ,e e, ~ 13 b Y88b Y 888C8 888 88" 888 8888D %@% 888 888 " d88 88b d88 88b ~ 14 8b Y88b 888 ",d 888 b, 888 888P %@% 888 888 888 , 888 , ~ 15 88b Y88b 888,d88 888 88b, 888 88" %@% 888 888 "YeeP" "YeeP" ~ 16 , -=-%{@%-^- _ ~ 17 ejm `} Reference Manual ~ 18 { ~ 19 ============================================================================== 20 CONTENTS *NERDTree-contents* 21 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.NERDTree mappings.................|NERDTreeMappings| 30 2.4.The NERDTree menu.................|NERDTreeMenu| 31 3.Settings................................|NERDTreeSettings| 32 3.1.Settings summary..................|NERDTreeSettingsSummary| 33 3.2.Settings details..................|NERDTreeSettingsDetails| 34 4.The NERDTree API........................|NERDTreeAPI| 35 4.1.Key map API.......................|NERDTreeKeymapAPI| 36 4.2.Menu API..........................|NERDTreeMenuAPI| 37 4.3.Menu API..........................|NERDTreeAddPathFilter()| 38 4.4.Path Listener API.................|NERDTreePathListenerAPI| 39 5.About...................................|NERDTreeAbout| 40 6.License.................................|NERDTreeLicense| 41 42 ============================================================================== 43 1. Intro *NERDTree* 44 45 What is this "NERDTree"?? 46 47 The NERDTree allows you to explore your filesystem and to open files and 48 directories. It presents the filesystem to you in the form of a tree which you 49 manipulate with the keyboard and/or mouse. It also allows you to perform 50 simple filesystem operations. 51 52 The following features and functionality are provided by the NERDTree: 53 * Files and directories are displayed in a hierarchical tree structure 54 * Different highlighting is provided for the following types of nodes: 55 * files 56 * directories 57 * sym-links 58 * windows .lnk files 59 * read-only files 60 * executable files 61 * Many (customisable) mappings are provided to manipulate the tree: 62 * Mappings to open/close/explore directory nodes 63 * Mappings to open files in new/existing windows/tabs 64 * Mappings to change the current root of the tree 65 * Mappings to navigate around the tree 66 * ... 67 * Directories and files can be bookmarked. 68 * Most NERDTree navigation can also be done with the mouse 69 * Filtering of tree content (can be toggled at runtime) 70 * custom file filters to prevent e.g. vim backup files being displayed 71 * optional displaying of hidden files (. files) 72 * files can be "turned off" so that only directories are displayed 73 * The position and size of the NERDTree window can be customised 74 * The order in which the nodes in the tree are listed can be customised. 75 * A model of your filesystem is created/maintained as you explore it. This 76 has several advantages: 77 * All filesystem information is cached and is only re-read on demand 78 * If you revisit a part of the tree that you left earlier in your 79 session, the directory nodes will be opened/closed as you left them 80 * The script remembers the cursor position and window position in the NERD 81 tree so you can toggle it off (or just close the tree window) and then 82 reopen it (with NERDTreeToggle) the NERDTree window will appear exactly 83 as you left it 84 * You can have a separate NERDTree for each tab, share trees across tabs, 85 or a mix of both. 86 * By default the script overrides the default file browser (netrw), so if 87 you :edit a directory a (slightly modified) NERDTree will appear in the 88 current window 89 * A programmable menu system is provided (simulates right clicking on a 90 node) 91 * one default menu plugin is provided to perform basic filesystem 92 operations (create/delete/move/copy files/directories) 93 * There's an API for adding your own keymappings 94 95 96 ============================================================================== 97 2. Functionality provided *NERDTreeFunctionality* 98 99 ------------------------------------------------------------------------------ 100 2.1. Global Commands *NERDTreeGlobalCommands* 101 102 :NERDTree [<start-directory> | <bookmark>] *:NERDTree* 103 Opens a fresh NERDTree. The root of the tree depends on the argument 104 given. There are 3 cases: If no argument is given, the current directory 105 will be used. If a directory is given, that will be used. If a bookmark 106 name is given, the corresponding directory will be used. For example: > 107 :NERDTree /home/marty/vim7/src 108 :NERDTree foo (foo is the name of a bookmark) 109 < 110 :NERDTreeVCS [<start-directory> | <bookmark>] *:NERDTreeVCS* 111 Like |:NERDTree|, but searches up the directory tree to find the top of 112 the version control system repository, and roots the NERDTree there. It 113 works with Git, Subversion, Mercurial, Bazaar, and Darcs repositories. A 114 couple of examples: > 115 :NERDTreeVCS /home/marty/nerdtree/doc (opens /home/marty/nerdtree) 116 :NERDTreeVCS (opens root of repository containing CWD) 117 < 118 :NERDTreeFromBookmark <bookmark> *:NERDTreeFromBookmark* 119 Opens a fresh NERDTree with the root initialized to the directory for 120 <bookmark>. The only reason to use this command over :NERDTree is for 121 the completion (which is for bookmarks rather than directories). 122 123 :NERDTreeToggle [<start-directory> | <bookmark>] *:NERDTreeToggle* 124 If a NERDTree already exists for this tab, it is reopened and rendered 125 again. If <start-directory> or <bookmark> is given, the root of NERDTree 126 is set to that path. If no NERDTree exists for this tab then this command 127 acts the same as the |:NERDTree| command. 128 129 :NERDTreeToggleVCS [<start-directory> | <bookmark>] *:NERDTreeToggleVCS* 130 Like |:NERDTreeToggle|, but searches up the directory tree to find the top of 131 the version control system repository, and roots the NERDTree there. It 132 works with Git, Subversion, Mercurial, Bazaar, and Darcs repositories. A 133 couple of examples: > 134 :NERDTreeToggleVCS /home/marty/nerdtree/doc (opens /home/marty/nerdtree) 135 :NERDTreeToggleVCS (opens root of repository containing CWD) 136 137 :NERDTreeFocus *:NERDTreeFocus* 138 Opens (or reopens) the NERDTree if it is not currently visible; 139 otherwise, the cursor is moved to the already-open NERDTree. 140 141 :NERDTreeMirror *:NERDTreeMirror* 142 Shares an existing NERDTree, from another tab, in the current tab. 143 Changes made to one tree are reflected in both as they are actually the 144 same buffer. 145 146 If only one other NERDTree exists, that tree is automatically mirrored. 147 If more than one exists, the script will ask which tree to mirror. 148 149 :NERDTreeClose *:NERDTreeClose* 150 Close the NERDTree in this tab. 151 152 :NERDTreeFind [<path>] *:NERDTreeFind* 153 Without the optional argument, find and reveal the file for the active 154 buffer in the NERDTree window. With the <path> argument, find and 155 reveal the specified path. 156 157 Focus will be shifted to the NERDTree window, and the cursor will be 158 placed on the tree node for the determined path. If a NERDTree for the 159 current tab does not exist, a new one will be initialized. 160 161 :NERDTreeCWD *:NERDTreeCWD* 162 Change the NERDTree root to the current working directory. If no 163 NERDTree exists for this tab, a new one is opened. 164 165 :NERDTreeRefreshRoot *:NERDTreeRefreshRoot* 166 Refreshes the NERDTree root node. 167 168 ------------------------------------------------------------------------------ 169 2.2. Bookmarks *NERDTreeBookmarks* 170 171 Bookmarks in the NERDTree are a way to tag files or directories of interest. 172 For example, you could use bookmarks to tag all of your project directories. 173 174 ------------------------------------------------------------------------------ 175 2.2.1. The Bookmark Table *NERDTreeBookmarkTable* 176 177 If the bookmark table is active (see |NERDTree-B| and 178 |NERDTreeShowBookmarks|), it will be rendered above the tree. You can double 179 click bookmarks or use the |NERDTree-o| mapping to activate them. See also, 180 |NERDTree-t| and |NERDTree-T| 181 182 ------------------------------------------------------------------------------ 183 2.2.2. Bookmark commands *NERDTreeBookmarkCommands* 184 185 Note: The following commands are only available within the NERDTree buffer. 186 187 :Bookmark [<name>] 188 Bookmark the current node as <name>. If there is already a <name> 189 bookmark, it is overwritten. <name> must not contain spaces. 190 If <name> is not provided, it defaults to the file or directory name. 191 For directories, a trailing slash is present. 192 193 :BookmarkToRoot <bookmark> 194 Make the directory corresponding to <bookmark> the new root. If a treenode 195 corresponding to <bookmark> is already cached somewhere in the tree then 196 the current tree will be used, otherwise a fresh tree will be opened. 197 Note that if <bookmark> points to a file then its parent will be used 198 instead. 199 200 :RevealBookmark <bookmark> 201 If the node is cached under the current root then it will be revealed 202 (i.e. directory nodes above it will be opened) and the cursor will be 203 placed on it. 204 205 :OpenBookmark <name> 206 The Bookmark named <name> is opened as if |NERDTree-o| was applied to 207 its entry in the Bookmark table. If the Bookmark points to a directory, 208 it is made the new root of the current NERDTree. If the Bookmark points 209 to a file, that file is opened for editing in another window. 210 211 :ClearBookmarks [<bookmarks>] 212 Remove all the given bookmarks. If no bookmarks are given then remove all 213 bookmarks on the current node. 214 215 :ClearAllBookmarks 216 Remove all bookmarks. 217 218 :EditBookmarks 219 Opens the bookmarks file for manual editing, e.g. for removing invalid 220 bookmarks. 221 222 :ReadBookmarks 223 Re-read the bookmarks in the |NERDTreeBookmarksFile|. 224 225 See also |:NERDTree| and |:NERDTreeFromBookmark|. 226 227 ------------------------------------------------------------------------------ 228 2.2.3. Invalid Bookmarks *NERDTreeInvalidBookmarks* 229 230 If invalid bookmarks are detected, the script will issue an error message and 231 the invalid bookmarks will become unavailable for use. 232 233 These bookmarks will still be stored in the bookmarks file (see 234 |NERDTreeBookmarksFile|), down at the bottom. There will always be a blank line 235 after the valid bookmarks but before the invalid ones. 236 237 Each line in the bookmarks file represents one bookmark. The proper format is: 238 <bookmark name><space><full path to the bookmark location> 239 240 You can use the :EditBookmarks command to open the bookmarks file for editing. 241 After you have corrected any invalid bookmarks, either restart vim, or run 242 :ReadBookmarks from the NERDTree window. 243 244 ------------------------------------------------------------------------------ 245 2.3. NERDTree Mappings *NERDTreeMappings* 246 247 Default~ 248 Key Description help-tag~ 249 250 o........Open files, directories and bookmarks......................|NERDTree-o| 251 go.......Open selected file, but leave cursor in the NERDTree......|NERDTree-go| 252 Find selected bookmark directory in current NERDTree 253 t........Open selected node/bookmark in a new tab...................|NERDTree-t| 254 T........Same as 't' but keep the focus on the current tab..........|NERDTree-T| 255 i........Open selected file in a split window.......................|NERDTree-i| 256 gi.......Same as i, but leave the cursor on the NERDTree...........|NERDTree-gi| 257 s........Open selected file in a new vsplit.........................|NERDTree-s| 258 gs.......Same as s, but leave the cursor on the NERDTree...........|NERDTree-gs| 259 <CR>.....User-definable custom open action.......................|NERDTree-<CR>| 260 O........Recursively open the selected directory....................|NERDTree-O| 261 x........Close the current nodes parent.............................|NERDTree-x| 262 X........Recursively close all children of the current node.........|NERDTree-X| 263 e........Edit the current directory.................................|NERDTree-e| 264 265 double-click....same as |NERDTree-o|. 266 middle-click....same as |NERDTree-i| for files, and |NERDTree-e| for directories. 267 268 D........Delete the current bookmark ...............................|NERDTree-D| 269 270 P........Jump to the root node......................................|NERDTree-P| 271 p........Jump to current nodes parent...............................|NERDTree-p| 272 K........Jump up inside directories at the current tree depth.......|NERDTree-K| 273 J........Jump down inside directories at the current tree depth.....|NERDTree-J| 274 <C-J>....Jump down to next sibling of the current directory.......|NERDTree-C-J| 275 <C-K>....Jump up to previous sibling of the current directory.....|NERDTree-C-K| 276 277 C........Change the tree root to the selected directory.............|NERDTree-C| 278 u........Move the tree root up one directory........................|NERDTree-u| 279 U........Same as 'u' except the old root node is left open..........|NERDTree-U| 280 r........Recursively refresh the current directory..................|NERDTree-r| 281 R........Recursively refresh the current root.......................|NERDTree-R| 282 m........Display the NERDTree menu..................................|NERDTree-m| 283 cd.......Change the CWD to the directory of the selected node......|NERDTree-cd| 284 CD.......Change tree root to the CWD...............................|NERDTree-CD| 285 286 I........Toggle whether hidden files displayed......................|NERDTree-I| 287 f........Toggle whether the file filters are used...................|NERDTree-f| 288 F........Toggle whether files are displayed.........................|NERDTree-F| 289 B........Toggle whether the bookmark table is displayed.............|NERDTree-B| 290 291 q........Close the NERDTree window..................................|NERDTree-q| 292 A........Zoom (maximize/minimize) the NERDTree window...............|NERDTree-A| 293 ?........Toggle the display of the quick help.......................|NERDTree-?| 294 295 ------------------------------------------------------------------------------ 296 *NERDTree-o* 297 Default key: o 298 Map setting: NERDTreeMapActivateNode 299 Applies to: files and directories. 300 301 If a file node is selected, it is opened in the previous window. 302 303 If a directory is selected it is opened or closed depending on its current 304 state. 305 306 If a bookmark that links to a directory is selected then that directory 307 becomes the new root. 308 309 If a bookmark that links to a file is selected then that file is opened in the 310 previous window. 311 312 ------------------------------------------------------------------------------ 313 *NERDTree-go* 314 Default key: go 315 Map setting: NERDTreeMapPreview 316 Applies to: files. 317 318 If a file node or a bookmark that links to a file is selected, it is opened in 319 the previous window, but the cursor does not move. 320 321 If a bookmark that links to a directory is selected then that directory 322 becomes the new root. 323 324 The default key combo for this mapping is "g" + NERDTreeMapActivateNode (see 325 |NERDTree-o|). 326 327 ------------------------------------------------------------------------------ 328 *NERDTree-t* 329 Default key: t 330 Map setting: *NERDTreeMapOpenInTab* 331 Applies to: files and directories. 332 333 Opens the selected file in a new tab. If a directory is selected, a fresh 334 NERDTree for that directory is opened in a new tab. 335 336 If a bookmark which points to a directory is selected, open a NERDTree for 337 that directory in a new tab. If the bookmark points to a file, open that file 338 in a new tab. 339 340 ------------------------------------------------------------------------------ 341 *NERDTree-T* 342 Default key: T 343 Map setting: *NERDTreeMapOpenInTabSilent* 344 Applies to: files and directories. 345 346 The same as |NERDTree-t| except that the focus is kept in the current tab. 347 348 ------------------------------------------------------------------------------ 349 *NERDTree-i* 350 Default key: i 351 Map setting: *NERDTreeMapOpenSplit* 352 Applies to: files, and bookmarks pointing to files. 353 354 Opens the selected file in a new split window and puts the cursor in the new 355 window. 356 357 ------------------------------------------------------------------------------ 358 *NERDTree-gi* 359 Default key: gi 360 Map setting: *NERDTreeMapPreviewSplit* 361 Applies to: files, and bookmarks pointing to files. 362 363 The same as |NERDTree-i| except that the cursor is not moved. 364 365 The default key combo for this mapping is "g" + NERDTreeMapOpenSplit (see 366 |NERDTree-i|). 367 368 ------------------------------------------------------------------------------ 369 *NERDTree-s* 370 Default key: s 371 Map setting: *NERDTreeMapOpenVSplit* 372 Applies to: files, and bookmarks pointing to files. 373 374 Opens the selected file in a new vertically split window and puts the cursor 375 in the new window. 376 377 ------------------------------------------------------------------------------ 378 *NERDTree-gs* 379 Default key: gs 380 Map setting: *NERDTreeMapPreviewVSplit* 381 Applies to: files, and bookmarks pointing to files. 382 383 The same as |NERDTree-s| except that the cursor is not moved. 384 385 The default key combo for this mapping is "g" + NERDTreeMapOpenVSplit (see 386 |NERDTree-s|). 387 388 ------------------------------------------------------------------------------ 389 *NERDTree-<CR>* 390 Default key: <CR> 391 Map setting: *NERDTreeMapCustomOpen* 392 Applies to: files, directories, and bookmarks 393 394 Performs a customized open action on the selected node. This allows the user 395 to define an action that behaves differently from any of the standard 396 keys. See |NERDTreeCustomOpenArgs| for more details. 397 ------------------------------------------------------------------------------ 398 *NERDTree-O* 399 Default key: O 400 Map setting: *NERDTreeMapOpenRecursively* 401 Applies to: directories. 402 403 Recursively opens the selected directory. 404 405 All files and directories are cached, but if a directory would not be 406 displayed due to file filters (see |NERDTreeIgnore| |NERDTree-f|) or the 407 hidden file filter (see |NERDTreeShowHidden|) then its contents are not 408 cached. This is handy, especially if you have .svn directories. 409 410 ------------------------------------------------------------------------------ 411 *NERDTree-x* 412 Default key: x 413 Map setting: *NERDTreeMapCloseDir* 414 Applies to: files and directories. 415 416 Closes the parent of the selected node. 417 418 ------------------------------------------------------------------------------ 419 *NERDTree-X* 420 Default key: X 421 Map setting: *NERDTreeMapCloseChildren* 422 Applies to: directories. 423 424 Recursively closes all children of the selected directory. 425 426 Tip: To quickly "reset" the tree, use |NERDTree-P| with this mapping. 427 428 ------------------------------------------------------------------------------ 429 *NERDTree-e* 430 Default key: e 431 Map setting: *NERDTreeMapOpenExpl* 432 Applies to: files and directories. 433 434 |:edit|s the selected directory, or the selected file's directory. This could 435 result in a NERDTree or a netrw being opened, depending on 436 |NERDTreeHijackNetrw|. 437 438 ------------------------------------------------------------------------------ 439 *NERDTree-D* 440 Default key: D 441 Map setting: *NERDTreeMapDeleteBookmark* 442 Applies to: lines in the bookmarks table 443 444 Deletes the currently selected bookmark. 445 446 ------------------------------------------------------------------------------ 447 *NERDTree-P* 448 Default key: P 449 Map setting: *NERDTreeMapJumpRoot* 450 Applies to: no restrictions. 451 452 Jump to the tree root. 453 454 ------------------------------------------------------------------------------ 455 *NERDTree-p* 456 Default key: p 457 Map setting: *NERDTreeMapJumpParent* 458 Applies to: files and directories. 459 460 Jump to the parent node of the selected node. 461 462 ------------------------------------------------------------------------------ 463 *NERDTree-K* 464 Default key: K 465 Map setting: *NERDTreeMapJumpFirstChild* 466 Applies to: files and directories. 467 468 Jump to the first child of the current nodes parent. 469 470 If the cursor is already on the first node then do the following: 471 * loop back thru the siblings of the current nodes parent until we find an 472 open directory with children 473 * go to the first child of that node 474 475 ------------------------------------------------------------------------------ 476 *NERDTree-J* 477 Default key: J 478 Map setting: *NERDTreeMapJumpLastChild* 479 Applies to: files and directories. 480 481 Jump to the last child of the current nodes parent. 482 483 If the cursor is already on the last node then do the following: 484 * loop forward thru the siblings of the current nodes parent until we find 485 an open directory with children 486 * go to the last child of that node 487 488 ------------------------------------------------------------------------------ 489 *NERDTree-C-J* 490 Default key: <C-J> 491 Map setting: *NERDTreeMapJumpNextSibling* 492 Applies to: files and directories. 493 494 Jump to the next sibling of the selected node. 495 496 ------------------------------------------------------------------------------ 497 *NERDTree-C-K* 498 Default key: <C-K> 499 Map setting: *NERDTreeMapJumpPrevSibling* 500 Applies to: files and directories. 501 502 Jump to the previous sibling of the selected node. 503 504 ------------------------------------------------------------------------------ 505 *NERDTree-C* 506 Default key: C 507 Map setting: *NERDTreeMapChangeRoot* 508 Applies to: files and directories. 509 510 Make the selected directory node the new tree root. If a file is selected, its 511 parent is used. 512 513 ------------------------------------------------------------------------------ 514 *NERDTree-u* 515 Default key: u 516 Map setting: *NERDTreeMapUpdir* 517 Applies to: no restrictions. 518 519 Move the tree root up a directory (like doing a "cd .."). 520 521 ------------------------------------------------------------------------------ 522 *NERDTree-U* 523 Default key: U 524 Map setting: *NERDTreeMapUpdirKeepOpen* 525 Applies to: no restrictions. 526 527 Like |NERDTree-u| except that the old tree root is kept open. 528 529 ------------------------------------------------------------------------------ 530 *NERDTree-r* 531 Default key: r 532 Map setting: *NERDTreeMapRefresh* 533 Applies to: files and directories. 534 535 If a directory is selected, recursively refresh that directory, i.e. scan the 536 filesystem for changes and represent them in the tree. 537 538 If a file node is selected then the above is done on it's parent. 539 540 ------------------------------------------------------------------------------ 541 *NERDTree-R* 542 Default key: R 543 Map setting: *NERDTreeMapRefreshRoot* 544 Applies to: no restrictions. 545 546 Recursively refresh the tree root. 547 548 ------------------------------------------------------------------------------ 549 *NERDTree-m* 550 Default key: m 551 Map setting: *NERDTreeMapMenu* 552 Applies to: files and directories. 553 554 Display the NERDTree menu. See |NERDTreeMenu| for details. 555 556 ------------------------------------------------------------------------------ 557 *NERDTree-cd* 558 Default key: cd 559 Map setting: *NERDTreeMapChdir* 560 Applies to: files and directories. 561 562 Change Vim's current working directory to that of the selected node. 563 564 ------------------------------------------------------------------------------ 565 *NERDTree-CD* 566 Default key: CD 567 Map setting: *NERDTreeMapCWD* 568 Applies to: no restrictions. 569 570 Change the NERDTree root to Vim's current working directory. 571 572 ------------------------------------------------------------------------------ 573 *NERDTree-I* 574 Default key: I 575 Map setting: *NERDTreeMapToggleHidden* 576 Applies to: no restrictions. 577 578 Toggles whether hidden files (i.e. "dot files") are displayed. 579 580 ------------------------------------------------------------------------------ 581 *NERDTree-f* 582 Default key: f 583 Map setting: *NERDTreeMapToggleFilters* 584 Applies to: no restrictions. 585 586 Toggles whether file filters are used. See |NERDTreeIgnore| for details. 587 588 ------------------------------------------------------------------------------ 589 *NERDTree-F* 590 Default key: F 591 Map setting: *NERDTreeMapToggleFiles* 592 Applies to: no restrictions. 593 594 Toggles whether file nodes are displayed. 595 596 ------------------------------------------------------------------------------ 597 *NERDTree-B* 598 Default key: B 599 Map setting: *NERDTreeMapToggleBookmarks* 600 Applies to: no restrictions. 601 602 Toggles whether the bookmarks table is displayed. 603 604 ------------------------------------------------------------------------------ 605 *NERDTree-q* 606 Default key: q 607 Map setting: *NERDTreeMapQuit* 608 Applies to: no restrictions. 609 610 Closes the NERDTree window. 611 612 ------------------------------------------------------------------------------ 613 *NERDTree-A* 614 Default key: A 615 Map setting: *NERDTreeMapToggleZoom* 616 Applies to: no restrictions. 617 618 Maximize (zoom) and minimize the NERDTree window. 619 620 ------------------------------------------------------------------------------ 621 *NERDTree-?* 622 Default key: ? 623 Map setting: *NERDTreeMapHelp* 624 Applies to: no restrictions. 625 626 Toggles whether the quickhelp is displayed. 627 628 ------------------------------------------------------------------------------ 629 2.3. The NERDTree menu *NERDTreeMenu* 630 631 The NERDTree has a menu that can be programmed via the an API (see 632 |NERDTreeMenuAPI|). The idea is to simulate the "right click" menus that most 633 file explorers have. 634 635 The script comes with two default menu plugins: exec_menuitem.vim and 636 fs_menu.vim. fs_menu.vim adds some basic filesystem operations to the menu for 637 creating/deleting/moving/copying files and directories. exec_menuitem.vim 638 provides a menu item to execute executable files. 639 640 Related tags: |NERDTree-m| |NERDTreeApi| 641 642 ------------------------------------------------------------------------------ 643 *NERDTreeMenu-j* 644 Default key: j 645 Map option: *NERDTreeMenuDown* 646 Applies to: The NERDTree menu. 647 648 Moves the cursor down. 649 650 ------------------------------------------------------------------------------ 651 *NERDTreeMenu-k* 652 Default key: k 653 Map option: *NERDTreeMenuUp* 654 Applies to: The NERDTree menu. 655 656 Moves the cursor up. 657 658 ============================================================================== 659 3. Customisation *NERDTreeSettings* 660 661 662 ------------------------------------------------------------------------------ 663 3.1. Customisation summary *NERDTreeSettingsSummary* 664 665 The plugin provides the following settings that can customise the behaviour 666 the NERDTree. These settings should be set in your vimrc, using `:let`. 667 668 |loaded_nerd_tree| Turns off the script. 669 670 |NERDTreeAutoCenter| Controls whether the NERDTree window centers 671 when the cursor moves within a specified 672 distance to the top/bottom of the window. 673 674 |NERDTreeAutoCenterThreshold| Controls the sensitivity of autocentering. 675 676 |NERDTreeCaseSensitiveSort| Tells the NERDTree whether to be case 677 sensitive or not when sorting nodes. 678 679 |NERDTreeNaturalSort| Tells the NERDTree whether to use natural sort 680 order or not when sorting nodes. 681 682 |NERDTreeSortHiddenFirst| Tells the NERDTree whether to take the dot at 683 the beginning of the hidden file names into 684 account when sorting nodes. 685 686 |NERDTreeChDirMode| Tells the NERDTree if/when it should change 687 vim's current working directory. 688 689 |NERDTreeHighlightCursorline| Tell the NERDTree whether to highlight the 690 current cursor line. 691 692 |NERDTreeHijackNetrw| Tell the NERDTree whether to replace the netrw 693 autocommands for exploring local directories. 694 695 |NERDTreeIgnore| Tells the NERDTree which files to ignore. 696 697 |NERDTreeRespectWildIgnore| Tells the NERDTree to respect `'wildignore'`. 698 699 |NERDTreeBookmarksFile| Where the bookmarks are stored. 700 701 |NERDTreeBookmarksSort| Control how the Bookmark table is sorted. 702 703 |NERDTreeMarkBookmarks| Render bookmarked nodes with markers. 704 705 |NERDTreeMouseMode| Manage the interpretation of mouse clicks. 706 707 |NERDTreeQuitOnOpen| Closes the tree window or bookmark table after 708 opening a file. 709 710 |NERDTreeShowBookmarks| Tells the NERDTree whether to display the 711 bookmarks table on startup. 712 713 |NERDTreeShowFiles| Tells the NERDTree whether to display files in 714 the tree on startup. 715 716 |NERDTreeShowHidden| Tells the NERDTree whether to display hidden 717 files on startup. 718 719 |NERDTreeShowLineNumbers| Tells the NERDTree whether to display line 720 numbers in the tree window. 721 722 |NERDTreeSortOrder| Tell the NERDTree how to sort the nodes in the 723 tree. 724 725 |NERDTreeStatusline| Set a statusline for NERDTree windows. 726 727 |NERDTreeWinPos| Tells the script where to put the NERDTree 728 window. 729 730 |NERDTreeWinSize| Sets the window size when the NERDTree is 731 opened. 732 733 |NERDTreeWinSizeMax| Sets the maximum window size when the NERDTree 734 is zoomed. 735 736 |NERDTreeMinimalUI| Disables display of the 'Bookmarks' label and 737 'Press ? for help' text. 738 739 |NERDTreeMinimalMenu| Use a compact menu that fits on a single line 740 for adding, copying, deleting, etc 741 742 |NERDTreeCascadeSingleChildDir| 743 Collapses on the same line directories that have 744 only one child directory. 745 746 |NERDTreeCascadeOpenSingleChildDir| 747 Cascade open while selected directory has only 748 one child that also is a directory. 749 750 |NERDTreeAutoDeleteBuffer| Tells the NERDTree to automatically remove a 751 buffer when a file is being deleted or renamed 752 via a context menu command. 753 754 |NERDTreeCreatePrefix| Specify a prefix to be used when creating the 755 NERDTree window. 756 757 |NERDTreeRemoveFileCmd| Specify a custom shell command to be used when 758 deleting files. Note that it should include one 759 space character at the end of the command and it 760 applies only to files. 761 762 |NERDTreeRemoveDirCmd| Specify a custom shell command to be used when 763 deleting directories. Note that it should 764 include one space character at the end of the 765 command and it applies only to directories. 766 767 |NERDTreeDirArrowCollapsible| These characters indicate when a directory is 768 |NERDTreeDirArrowExpandable| either collapsible or expandable. 769 770 |NERDTreeNodeDelimiter| A single character that is used to separate the 771 file or directory name from the rest of the 772 characters on the line of text. 773 774 |NERDTreeCustomOpenArgs| A dictionary with values that control how a node 775 is opened with the |NERDTree-<CR>| key. 776 777 ------------------------------------------------------------------------------ 778 3.2. Customisation details *NERDTreeSettingsDetails* 779 780 To enable any of the below settings you should put an appropriate > 781 let <setting>=<value> 782 <line in your ~/.vimrc. 783 784 *loaded_nerd_tree* 785 If this plugin is making you feel homicidal, it may be a good idea to turn it 786 off with this line in your vimrc: > 787 let loaded_nerd_tree=1 788 < 789 ------------------------------------------------------------------------------ 790 *NERDTreeAutoCenter* 791 Values: 0 or 1. 792 Default: 1 793 794 If set to 1, the NERDTree window will center around the cursor if it moves to 795 within |NERDTreeAutoCenterThreshold| lines of the top/bottom of the window. 796 797 This is ONLY done in response to tree navigation mappings, 798 i.e. |NERDTree-J| |NERDTree-K| |NERDTree-C-J| |NERDTree-C-K| |NERDTree-p| 799 |NERDTree-P| 800 801 The centering is done with a |zz| operation. 802 803 ------------------------------------------------------------------------------ 804 *NERDTreeAutoCenterThreshold* 805 Values: Any natural number. 806 Default: 3 807 808 This setting controls the "sensitivity" of the NERDTree auto centering. See 809 |NERDTreeAutoCenter| for details. 810 811 ------------------------------------------------------------------------------ 812 *NERDTreeCaseSensitiveSort* 813 Values: 0 or 1. 814 Default: 0. 815 816 By default the NERDTree does not sort nodes case sensitively, i.e. nodes 817 could appear like this: > 818 bar.c 819 Baz.c 820 blarg.c 821 boner.c 822 Foo.c 823 < 824 But, if you set this setting to 1 then the case of the nodes will be taken 825 into account. The above nodes would then be sorted like this: > 826 Baz.c 827 Foo.c 828 bar.c 829 blarg.c 830 boner.c 831 < 832 ------------------------------------------------------------------------------ 833 *NERDTreeNaturalSort* 834 Values: 0 or 1. 835 Default: 0. 836 837 By default the NERDTree does not sort nodes in natural sort order, i.e. nodes 838 could appear like this: > 839 z1.txt 840 z10.txt 841 z100.txt 842 z11.txt 843 z110.txt 844 z2.txt 845 z20.txt 846 z3.txt 847 < 848 But if you set this setting to 1 then the natural sort order will be used. The 849 above nodes would then be sorted like this: > 850 z1.txt 851 z2.txt 852 z3.txt 853 z10.txt 854 z11.txt 855 z20.txt 856 z100.txt 857 z110.txt 858 < 859 ------------------------------------------------------------------------------ 860 *NERDTreeUseTCD* 861 Values: 0 or 1. 862 Default: 0. 863 864 By default, NERDTree will use the `:cd` command to change the current working 865 directory. If this setting is turned on, and the `:tcd` command is available, it 866 will be used instead. 867 868 ------------------------------------------------------------------------------ 869 *NERDTreeChDirMode* 870 Values: 0, 1, 2, or 3. 871 Default: 0. 872 873 Use this setting to tell the script when (if at all) to change the current 874 working directory (CWD) for vim. 875 876 If it is set to 0 then the CWD is never changed by the NERDTree. 877 878 If set to 1 then the CWD is changed when the NERDTree is first loaded to the 879 directory it is initialized in. For example, if you start the NERDTree with > 880 :NERDTree /home/marty/foobar 881 < 882 then the CWD will be changed to /home/marty/foobar and will not be changed 883 again unless you init another NERDTree with a similar command. 884 885 If the setting is set to 2 then it behaves the same as if set to 1 except that 886 the CWD is changed whenever the tree root is changed. For example, if the CWD 887 is /home/marty/foobar and you make the node for /home/marty/foobar/baz the new 888 root then the CWD will become /home/marty/foobar/baz. 889 890 If the set to 3, then it behaves the same as if set to 2, and the CWD is 891 changed whenever changing tabs to whatever the tree root is on that tab. 892 893 ------------------------------------------------------------------------------ 894 *NERDTreeHighlightCursorline* 895 Values: 0 or 1. 896 Default: 1. 897 898 If set to 1, the current cursor line in the NERDTree buffer will be 899 highlighted. This is done using the `'cursorline'` Vim option. 900 901 ------------------------------------------------------------------------------ 902 *NERDTreeHijackNetrw* 903 Values: 0 or 1. 904 Default: 1. 905 906 If set to 1, doing a > 907 :edit <some directory> 908 < 909 will open up a window level NERDTree instead of a netrw in the target window. 910 911 Window level trees behaves slightly different from a regular trees in the 912 following respects: 913 1. 'o' will open the selected file in the same window as the tree, 914 replacing it. 915 2. you can have one tree per window - instead of per tab. 916 917 ------------------------------------------------------------------------------ 918 *NERDTreeIgnore* 919 Values: a list of regular expressions. 920 Default: ['\~$']. 921 922 This setting is used to specify which files the NERDTree should ignore. It 923 must be a list of regular expressions. When the NERDTree is rendered, any 924 files/directories that match any of the regex's in NERDTreeIgnore won't be 925 displayed. 926 927 For example if you put the following line in your vimrc: > 928 let NERDTreeIgnore=['\.vim$', '\~$'] 929 < 930 then all files ending in .vim or ~ will be ignored. 931 932 There are 3 magic flags that can be appended to the end of each regular 933 expression to specify that the regex should match only filenames, only lowest 934 level directories, or a full path. These flags are "[[dir]]", "[[file]]", and 935 "[[path]]". Example: > 936 let NERDTreeIgnore=['\.d$[[dir]]', '\.o$[[file]]', 'tmp/cache$[[path]]'] 937 < 938 This will cause all directories ending in ".d" to be ignored, all files ending 939 in ".o" to be ignored, and the "cache" subdirectory of any "tmp" directory to 940 be ignored. All other "cache" directories will be displayed. 941 942 When using the "[[path]]" tag on Windows, make sure you use escaped 943 backslashes for the separators in the regex, eg. 'Temp\\cache$[[path]]' 944 945 Note: to tell the NERDTree not to ignore any files you must use the following 946 line: > 947 let NERDTreeIgnore=[] 948 < 949 The file filters can be turned on and off dynamically with the |NERDTree-f| 950 mapping. 951 952 ------------------------------------------------------------------------------ 953 *NERDTreeRespectWildIgnore* 954 Values: 0 or 1. 955 Default: 0. 956 957 If set to 1, the `'wildignore'` setting is respected. 958 959 ------------------------------------------------------------------------------ 960 *NERDTreeBookmarksFile* 961 Values: a path 962 Default: $HOME/.NERDTreeBookmarks 963 964 This is where bookmarks are saved. See |NERDTreeBookmarkCommands|. 965 966 ------------------------------------------------------------------------------ 967 *NERDTreeBookmarksSort* 968 Values: 0, 1, or 2 969 Default: 1 970 971 This setting controls the method by which the list of user bookmarks is 972 sorted. When sorted, bookmarks will render in alphabetical order by name. 973 974 If set to 0, the bookmarks list is not sorted. 975 If set to 1, the bookmarks list is sorted in a case-insensitive manner. 976 If set to 2, the bookmarks list is sorted in a case-sensitive manner. 977 978 ------------------------------------------------------------------------------ 979 *NERDTreeMarkBookmarks* 980 Values: 0 or 1 981 Default: 1 982 983 If set to 1, Bookmarks will be specially marked whenever the NERDTree is 984 rendered. Users of the |NERDTreeMinimalUI| setting may prefer to disable 985 this setting for even less visual clutter. 986 987 ------------------------------------------------------------------------------ 988 *NERDTreeMouseMode* 989 Values: 1, 2 or 3. 990 Default: 1. 991 992 If set to 1 then a double click on a node is required to open it. 993 If set to 2 then a single click will open directory nodes, while a double 994 click will still be required for file nodes. 995 If set to 3 then a single click will open any node. 996 997 Note: a double click anywhere on a line that a tree node is on will 998 activate it, but all single-click activations must be done on name of the node 999 itself. For example, if you have the following node: > 1000 | | |-application.rb 1001 < 1002 then (to single click activate it) you must click somewhere in 1003 'application.rb'. 1004 1005 ------------------------------------------------------------------------------ 1006 *NERDTreeQuitOnOpen* 1007 Values: 0,1,2 or 3. 1008 Default: 0 1009 1010 This setting governs whether the NERDTree window or the bookmarks table closes 1011 after opening a file with the |NERDTree-o|, |NERDTree-i|, |NERDTree-t| and 1012 |NERDTree-T| mappings. 1013 1014 Value | NERDTree Window Behavior 1015 -------+------------------------------------------------------- 1016 0 | No change 1017 1 | Closes after opening a file 1018 2 | Closes the bookmark table after opening a bookmark 1019 3(1+2) | Same as both 1 and 2 1020 1021 ------------------------------------------------------------------------------ 1022 *NERDTreeShowBookmarks* 1023 Values: 0 or 1. 1024 Default: 0. 1025 1026 If this setting is set to 1 then the bookmarks table will be displayed. 1027 1028 This setting can be toggled dynamically, per tree, with the |NERDTree-B| 1029 mapping. 1030 1031 ------------------------------------------------------------------------------ 1032 *NERDTreeShowFiles* 1033 Values: 0 or 1. 1034 Default: 1. 1035 1036 If this setting is set to 1 then files are displayed in the NERDTree. If it 1037 is set to 0 then only directories are displayed. 1038 1039 This setting can be toggled dynamically, per tree, with the |NERDTree-F| 1040 mapping and is useful for drastically shrinking the tree when you are 1041 navigating to a different part of the tree. 1042 1043 ------------------------------------------------------------------------------ 1044 *NERDTreeShowHidden* 1045 Values: 0 or 1. 1046 Default: 0. 1047 1048 This setting tells vim whether to display hidden files by default. This 1049 setting can be dynamically toggled, per tree, with the |NERDTree-I| mapping. 1050 Use one of the follow lines for this setting: > 1051 let NERDTreeShowHidden=0 1052 let NERDTreeShowHidden=1 1053 < 1054 ------------------------------------------------------------------------------ 1055 *NERDTreeShowLineNumbers* 1056 Values: 0 or 1. 1057 Default: 0. 1058 1059 This setting tells vim whether to display line numbers for the NERDTree 1060 window. Use one of the follow lines for this setting: > 1061 let NERDTreeShowLineNumbers=0 1062 let NERDTreeShowLineNumbers=1 1063 < 1064 ------------------------------------------------------------------------------ 1065 *NERDTreeSortOrder* 1066 Values: a list of regular expressions. 1067 Default: ['\/$', '*', '\.swp$', '\.bak$', '\~$'] 1068 1069 This setting is a list of regular expressions which are used to group or sort 1070 the nodes under their parent. 1071 1072 For example, if the setting is: > 1073 ['\.vim$', '\.c$', '\.h$', '*', 'foobar'] 1074 < 1075 then all .vim files will be grouped at the top, followed by all .c files then 1076 all .h files. All files containing the string 'foobar' will be placed at the 1077 end. The star is a special flag: it tells the script that every node that 1078 doesn't match any of the other regexps should be placed here. 1079 1080 If no star is present in NERDTreeSortOrder, then one is automatically 1081 appended to the end of the list. 1082 1083 The regex '\/$' should be used to match directory nodes. 1084 1085 Files can also be sorted by 1) the modification timestamp, 2) the size, or 3) 1086 the extension. Directories are always sorted by name. To accomplish this, the 1087 following special flags are used: 1088 [[timestamp]] [[-timestamp]] [[size]] [[-size]] [[extension]] 1089 The hyphen specifies a descending sort; extensions are sorted in ascending 1090 order only. If placed at the beginning of the list, files are sorted according 1091 to these flags first, and then grouped by the remaining items in the list. If 1092 the flags are in any other position of the list, this special sorting is done 1093 secondarily. See examples 4, 5, and 6 below. 1094 1095 After this sorting is done, the files in each group are sorted alphabetically. 1096 1097 Examples: > 1098 (1) ['*', '\/$'] 1099 (2) [] 1100 (3) ['\/$', '\.rb$', '\.php$', '*', '\.swp$', '\.bak$', '\~$'] 1101 (4) ['[[-size]]'] 1102 (5) ['\/$', '*', '[[timestamp]]'] 1103 (6) ['foo','\/$','[[extension]]'] 1104 < 1105 1. Directories will appear last, everything else will appear above. 1106 2. Everything will simply appear in alphabetical order. 1107 3. Directories will appear first, then ruby and php. Swap files, bak files 1108 and vim backup files will appear last with everything else preceding them. 1109 4. Everything is sorted by size, largest to smallest, with directories 1110 considered to have size 0 bytes. 1111 5. Directories will appear first alphabetically, followed by files, sorted by 1112 timestamp, oldest first. 1113 6. Files and directories matching 'foo' first, followed by other directories, 1114 then all other files. Each section of files is sorted by file extension. 1115 1116 ------------------------------------------------------------------------------ 1117 *NERDTreeStatusline* 1118 Values: Any valid `'statusline'` setting. 1119 Default: %{exists('b:NERDTree')?b:NERDTree.root.path.str():''} 1120 1121 Defines the value for the `'statusline'` setting in NERDTree windows. 1122 1123 Note: The setting is actually applied using |:let-&|, not |:set|, so 1124 escaping spaces is not necessary. 1125 1126 Setting this to -1 will deactivate it so that your global `'statusline'` 1127 setting is used. 1128 1129 ------------------------------------------------------------------------------ 1130 *NERDTreeWinPos* 1131 Values: "left", "right", "top" or "bottom" 1132 Default: "left". 1133 1134 This setting is used to determine where NERDTree window is placed on the 1135 screen. 1136 1137 This setting makes it possible to use two different explorer plugins 1138 simultaneously. For example, you could have the taglist plugin on the left of 1139 the window and the NERDTree on the right. 1140 1141 When setting this variable to "top" or "bottom" make sure to also change the 1142 |NERDTreeWinSize| to a more reasonable size. 1143 1144 For example: 1145 > 1146 let g:NERDTreeWinSize = 15 1147 < 1148 ------------------------------------------------------------------------------ 1149 *NERDTreeWinSize* 1150 Values: a positive integer. 1151 Default: 31. 1152 1153 This setting is used to change the size of the NERDTree when it is loaded. 1154 1155 ------------------------------------------------------------------------------ 1156 *NERDTreeMinimalUI* 1157 Values: 0 or 1 1158 Default: 0 1159 1160 This setting disables the 'Bookmarks' label 'Press ? for help' text. Use one 1161 of the following lines for this setting: > 1162 let NERDTreeMinimalUI=0 1163 let NERDTreeMinimalUI=1 1164 < 1165 ------------------------------------------------------------------------------ 1166 *NERDTreeMinimalMenu* 1167 Values: 0 or 1 1168 Default: 0 1169 1170 This setting makes NERDTree use a smaller, more compact menu for adding, 1171 copying, deleting nodes. This menu fits on a single line so Vim doesn't need to 1172 scroll down to present it. This setting is recommended for users already 1173 familiar with the menu items. It will look similar to this: 1174 1175 Menu: [ (a)dd ,m,d,r,o,q,c,l] (Use j/k/enter or shortcut): 1176 1177 An action can be selected with its shortcut key or with the NERDTreeMenuUp and 1178 NERDTreeMenuDown keys, then pressing enter. 1179 1180 Use one of the following lines for this setting: > 1181 let NERDTreeMinimalMenu=0 1182 let NERDTreeMinimalMenu=1 1183 < 1184 ------------------------------------------------------------------------------ 1185 *NERDTreeCascadeSingleChildDir* 1186 Values: 0 or 1 1187 Default: 1. 1188 1189 When displaying directory nodes, this setting tells NERDTree to collapse 1190 directories that have only one child. Use one of the following lines for this 1191 setting: > 1192 let NERDTreeCascadeSingleChildDir=0 1193 let NERDTreeCascadeSingleChildDir=1 1194 < 1195 ------------------------------------------------------------------------------ 1196 *NERDTreeCascadeOpenSingleChildDir* 1197 Values: 0 or 1 1198 Default: 1. 1199 1200 When opening directory nodes, this setting tells NERDTree to recursively open 1201 directories that have only one child which is also a directory. NERDTree will 1202 stop when it finds a directory that contains anything but another single 1203 directory. This setting also causes the |NERDTree-x| mapping to close 1204 directories in the same manner. This setting may be useful for Java projects. 1205 Use one of the following lines for this setting: > 1206 let NERDTreeCascadeOpenSingleChildDir=0 1207 let NERDTreeCascadeOpenSingleChildDir=1 1208 < 1209 ------------------------------------------------------------------------------ 1210 *NERDTreeAutoDeleteBuffer* 1211 Values: 0 or 1 1212 Default: 0. 1213 1214 When using a context menu to delete or rename a file you may also want to 1215 delete the buffer which is no more valid. If the setting is not set you will 1216 see a confirmation if you really want to delete an old buffer. If you always 1217 press 'y' then it's worth it to set this setting to 1. Use one of the 1218 following lines for this setting: > 1219 let NERDTreeAutoDeleteBuffer=0 1220 let NERDTreeAutoDeleteBuffer=1 1221 < 1222 ------------------------------------------------------------------------------ 1223 *NERDTreeCreatePrefix* 1224 Values: Any valid command prefix. 1225 Default: "silent". 1226 1227 Internally, NERDTree uses the |:edit| command to create a buffer in which to 1228 display its tree view. You can augment this behavior by specifying a prefix 1229 string such as "keepalt" or similar. For example, to have NERDTree create its 1230 tree window using `silent keepalt keepjumps edit`: > 1231 let NERDTreeCreatePrefix='silent keepalt keepjumps' 1232 < 1233 ------------------------------------------------------------------------------ 1234 *NERDTreeDirArrowCollapsible* *NERDTreeDirArrowExpandable* 1235 Values: Any single character. 1236 Defaults: Windows: ~ and + Others: ▾ and ▸ 1237 1238 These characters indicate whether a directory is collapsible or expandable. 1239 Example: > 1240 let NERDTreeDirArrowExpandable=">" 1241 let NERDTreeDirArrowCollapsible="v" 1242 < 1243 They can be set to "\u00a0" to replace the arrows with a non-breaking space. 1244 If you do this you may need to change the node delimiter. See 1245 |NERDTreeNodeDelimiter|. You cannot use the same character for both the arrows 1246 and the delimiter. 1247 1248 Alternatively, they can be set to '' (an empty string). This removes the 1249 arrows and the single space that follows them, shifting the entire tree two 1250 character positions to the left. 1251 1252 ------------------------------------------------------------------------------ 1253 *NERDTreeNodeDelimiter* 1254 Values: Any single character. 1255 Default: varies (see below) 1256 1257 This character is used to separate the file or directory name from the rest of 1258 the characters in the line of text. It allows filenames to contain special 1259 characters that are otherwise used in the NERDTree, such as square brackets, 1260 braces, trailing asterisk, and leading space. For more details, see the 1261 responsible pull request: https://github.com/preservim/nerdtree/pull/868. 1262 1263 The default value of this variable depends on the features compiled into your 1264 vim and the values of |NERDTreeDirArrowCollapsible| and 1265 |NERDTreeDirArrowExpandable|. 1266 * If your vim is compiled with the +conceal feature, it is the "\x07" 1267 (BEL) character, and it is hidden by setting 'conceallevel' to 2. If you 1268 use autocommands, make sure none of them change that setting in the 1269 NERD_Tree_* buffers. 1270 * If your vim does NOT have the +conceal feature and you're using "\u00a0" 1271 (non-breaking space) to hide the directory arrows, "\u00b7" (middle dot) 1272 is used as the default delimiter. 1273 * If neither condition above applies, NERDTree uses "\u00a0" (non-breaking 1274 space) as the default delimiter. 1275 1276 In the 2nd and 3rd cases, NERDTree will use the Ignore highlight group to 1277 "hide" the delimiter. It should appear as an empty space. 1278 1279 Other plugins can interfere with these defaults, so if you need to change the 1280 delimiter, be sure to choose a character that won't appear in your filenames 1281 or any of the flags set by your installed NERDTree plugins. The suggestions 1282 below are but a few of the many possibilities. Remember to use double quotes 1283 when specifying by hex or Unicode. > 1284 let NERDTreeNodeDelimiter="\x07" "bell 1285 let NERDTreeNodeDelimiter="\u00b7" "middle dot 1286 let NERDTreeNodeDelimiter="\u00a0" "non-breaking space 1287 let NERDTreeNodeDelimiter="😀" "smiley face 1288 < 1289 ------------------------------------------------------------------------------ 1290 *NERDTreeCustomOpenArgs* 1291 Values: A nested dictionary, as described below 1292 Default: {'file': {'reuse': 'all', 'where': 'p'}, 'dir': {}} 1293 1294 This dictionary contains two keys, 'file' and 'dir', whose values each are 1295 another dictionary. The inner dictionary is a set of parameters used by 1296 |NERDTree-<CR>| to open a file or directory. Setting these parameters allows you 1297 to customize the way the node is opened. The default value matches what 1298 |NERDTree-o| does. To change that behavior, use these keys and 1299 values in the inner dictionaries: 1300 1301 'where': specifies whether the node should be opened in a new split ("h" or 1302 "v"), in a new tab ("t") or, in the last window ("p"). 1303 'reuse': if file is already shown in a window, jump there; takes values 1304 "all", "currenttab", or empty 1305 'keepopen': boolean (0 or 1); if true, the tree window will not be closed 1306 'stay': boolean (0 or 1); if true, remain in tree window after opening 1307 1308 For example: 1309 To open files and directories (creating a new NERDTree) in a new tab, > 1310 {'file':{'where': 't'}, 'dir':{'where':'t'}} 1311 < 1312 To open a file always in the current tab, and expand directories in place, > 1313 {'file': {'reuse':'currenttab', 'where':'p', 'keepopen':1, 'stay':1}} 1314 < 1315 ============================================================================== 1316 4. The NERDTree API *NERDTreeAPI* 1317 1318 The NERDTree script allows you to add custom key mappings and menu items via 1319 a set of API calls. Any scripts that use this API should be placed in 1320 ~/.vim/nerdtree_plugin/ (*nix) or ~/vimfiles/nerdtree_plugin (windows). 1321 1322 The script exposes some prototype objects that can be used to manipulate the 1323 tree and/or get information from it: > 1324 g:NERDTreePath 1325 g:NERDTreeDirNode 1326 g:NERDTreeFileNode 1327 g:NERDTreeBookmark 1328 < 1329 See the code/comments in NERD_tree.vim to find how to use these objects. The 1330 following code conventions are used: 1331 * class members start with a capital letter 1332 * instance members start with a lower case letter 1333 * private members start with an underscore 1334 1335 See this blog post for more details: 1336 http://got-ravings.blogspot.com/2008/09/vim-pr0n-prototype-based-objects.html 1337 1338 A number of API functions take a callback argument to call. The callback can 1339 be either a string with the name of a function to call, or a |Funcref| object 1340 which will be called directly. 1341 1342 ------------------------------------------------------------------------------ 1343 4.1. Key map API *NERDTreeKeymapAPI* 1344 1345 NERDTreeAddKeyMap({options}) *NERDTreeAddKeyMap()* 1346 Adds a new keymapping for all NERDTree buffers. 1347 {options} must be a dictionary, and must contain the following keys: 1348 "key" - the trigger key for the new mapping 1349 "callback" - the function the new mapping will be bound to 1350 "quickhelpText" - the text that will appear in the quickhelp (see 1351 |NERDTree-?|) 1352 "override" - if 1 then this new mapping will override whatever previous 1353 mapping was defined for the key/scope combo. Useful for overriding the 1354 default mappings. 1355 1356 Additionally, a "scope" argument may be supplied. This constrains the 1357 mapping so that it is only activated if the cursor is on a certain object. 1358 That object is then passed into the handling method. Possible values are: 1359 1360 "FileNode" .... a file node 1361 "DirNode" ..... a directory node 1362 "Node" ........ a file node OR a directory node 1363 "Bookmark" .... a bookmark 1364 "all" ......... global scope; handler receives no arguments (default) 1365 1366 Example: > 1367 call NERDTreeAddKeyMap({ 1368 \ 'key': 'foo', 1369 \ 'callback': 'NERDTreeEchoPathHandler', 1370 \ 'quickhelpText': 'echo full path of current node', 1371 \ 'scope': 'DirNode' }) 1372 1373 function! NERDTreeEchoPathHandler(dirnode) 1374 echo a:dirnode.path.str() 1375 endfunction 1376 < 1377 This code should sit in a file like ~/.vim/nerdtree_plugin/mymapping.vim. 1378 It adds a (redundant) mapping on 'foo' which changes vim's CWD to that of 1379 the current directory node. Note this mapping will only fire when the 1380 cursor is on a directory node. 1381 1382 ------------------------------------------------------------------------------ 1383 4.2. Menu API *NERDTreeMenuAPI* 1384 1385 NERDTreeAddSubmenu({options}) *NERDTreeAddSubmenu()* 1386 Creates and returns a new submenu. 1387 1388 {options} must be a dictionary and must contain the following keys: 1389 "text" - the text of the submenu that the user will see 1390 "shortcut" - a shortcut key for the submenu (need not be unique) 1391 1392 The following keys are optional: 1393 "isActiveCallback" - a function that will be called to determine whether 1394 this submenu item will be displayed or not. The callback function must 1395 return 0 or 1. 1396 "parent" - the parent submenu of the new submenu (returned from a previous 1397 invocation of NERDTreeAddSubmenu()). If this key is left out then the new 1398 submenu will sit under the top level menu. 1399 1400 See below for an example. 1401 1402 NERDTreeAddMenuItem({options}) *NERDTreeAddMenuItem()* 1403 Adds a new menu item to the NERDTree menu (see |NERDTreeMenu|). 1404 1405 {options} must be a dictionary and must contain the 1406 following keys: 1407 "text" - the text of the menu item which the user will see 1408 "shortcut" - a shortcut key for the menu item (need not be unique) 1409 "callback" - the function that will be called when the user activates the 1410 menu item. 1411 1412 The following keys are optional: 1413 "isActiveCallback" - a function that will be called to determine whether 1414 this menu item will be displayed or not. The callback function must return 1415 0 or 1. 1416 "parent" - if the menu item belongs under a submenu then this key must be 1417 specified. This value for this key will be the object that 1418 was returned when the submenu was created with |NERDTreeAddSubmenu()|. 1419 1420 See below for an example. 1421 1422 NERDTreeAddMenuSeparator([{options}]) *NERDTreeAddMenuSeparator()* 1423 Adds a menu separator (a row of dashes). 1424 1425 {options} is an optional dictionary that may contain the following keys: 1426 "isActiveCallback" - see description in |NERDTreeAddMenuItem()|. 1427 1428 Below is an example of the menu API in action. > 1429 call NERDTreeAddMenuSeparator() 1430 1431 call NERDTreeAddMenuItem({ 1432 \ 'text': 'a (t)op level menu item', 1433 \ 'shortcut': 't', 1434 \ 'callback': 'SomeFunction' }) 1435 1436 let submenu = NERDTreeAddSubmenu({ 1437 \ 'text': 'a (s)ub menu', 1438 \ 'shortcut': 's' }) 1439 1440 call NERDTreeAddMenuItem({ 1441 \ 'text': '(n)ested item 1', 1442 \ 'shortcut': 'n', 1443 \ 'callback': 'SomeFunction', 1444 \ 'parent': submenu }) 1445 1446 call NERDTreeAddMenuItem({ 1447 \ 'text': '(n)ested item 2', 1448 \ 'shortcut': 'n', 1449 \ 'callback': 'SomeFunction', 1450 \ 'parent': submenu }) 1451 < 1452 This will create the following menu: > 1453 -------------------- 1454 a (t)op level menu item 1455 a (s)ub menu 1456 < 1457 Where selecting "a (s)ub menu" will lead to a second menu: > 1458 (n)ested item 1 1459 (n)ested item 2 1460 < 1461 When any of the 3 concrete menu items are selected the function "SomeFunction" 1462 will be called. 1463 1464 ------------------------------------------------------------------------------ 1465 4.3 NERDTreeAddPathFilter(callback) *NERDTreeAddPathFilter()* 1466 1467 Path filters are essentially a more powerful version of |NERDTreeIgnore|. 1468 If the simple regex matching in |NERDTreeIgnore| is not enough then use 1469 |NERDTreeAddPathFilter()| to add a callback function that paths will be 1470 checked against when the decision to ignore them is made. Example > 1471 1472 call NERDTreeAddPathFilter('MyFilter') 1473 1474 function! MyFilter(params) 1475 "params is a dict containing keys: 'nerdtree' and 'path' which are 1476 "g:NERDTree and g:NERDTreePath objects 1477 1478 "return 1 to ignore params['path'] or 0 otherwise 1479 endfunction 1480 < 1481 ------------------------------------------------------------------------------ 1482 4.4 Path Listener API *NERDTreePathListenerAPI* 1483 1484 Use this API if you want to run a callback for events on Path objects. E.G > 1485 1486 call g:NERDTreePathNotifier.AddListener("init", "MyListener") 1487 1488 ".... 1489 1490 function! MyListener(event) 1491 "This function will be called whenever a Path object is created. 1492 1493 "a:event is an object that contains a bunch of relevant info - 1494 "including the affected path. See lib/nerdtree/event.vim for details. 1495 endfunction 1496 < 1497 Current events supported: 1498 init ~ 1499 refresh ~ 1500 refreshFlags ~ 1501 1502 ------------------------------------------------------------------------------ 1503 NERDTreeRender() *NERDTreeRender()* 1504 Re-renders the NERDTree buffer. Useful if you change the state of the 1505 tree and you want to it to be reflected in the UI. 1506 1507 ============================================================================== 1508 5. About *NERDTreeAbout* 1509 1510 The author of the NERDTree is a terrible terrible monster called Martyzilla 1511 who gobbles up small children with milk and sugar for breakfast. 1512 1513 He can be reached at martin.grenfell at gmail dot com. He would love to hear 1514 from you, so feel free to send him suggestions and/or comments about this 1515 plugin. Don't be shy --- the worst he can do is slaughter you and stuff you 1516 in the fridge for later ;) 1517 1518 Martyzilla recruited two other unwitting accomplices to become his minions in 1519 his quest to conquer the Vim plugin world. While he may still love to receive 1520 your emails, the best way to send suggestions, bug reports, and questions is 1521 to submit an issue at http://github.com/preservim/nerdtree/issues. 1522 1523 The latest stable and development versions are on Github. 1524 Stable: http://github.com/preservim/nerdtree (master branch) 1525 Development: http://github.com/preservim/nerdtree/branches 1526 1527 Title Credit: 1528 * http://ascii.co.uk/art/tree 1529 1530 * Patrick Gillespie's Text ASCII Art Generator 1531 http://patorjk.com/software/taag 1532 http://patorjk.com/software/taag/#p=display&f=Rozzo&t=the%20NERD%20Tree 1533 1534 ============================================================================== 1535 6. License *NERDTreeLicense* 1536 1537 The NERDTree is released under the wtfpl. 1538 See http://sam.zoy.org/wtfpl/COPYING. 1539 1540 ------------------------------------------------------------------------------ 1541 vim:tw=78:ts=8:ft=help:noet:nospell
