| *NERD_tree.txt* A tree explorer plugin that owns your momma! |
| |
| |
| |
| omg its ... ~ |
| |
| ________ ________ _ ____________ ____ __________ ____________~ |
| /_ __/ / / / ____/ / | / / ____/ __ \/ __ \ /_ __/ __ \/ ____/ ____/~ |
| / / / /_/ / __/ / |/ / __/ / /_/ / / / / / / / /_/ / __/ / __/ ~ |
| / / / __ / /___ / /| / /___/ _, _/ /_/ / / / / _, _/ /___/ /___ ~ |
| /_/ /_/ /_/_____/ /_/ |_/_____/_/ |_/_____/ /_/ /_/ |_/_____/_____/ ~ |
| |
| |
| Reference Manual~ |
| |
| |
| |
| |
| ============================================================================== |
| CONTENTS *NERDTree-contents* |
| |
| 1.Intro...................................|NERDTree| |
| 2.Functionality provided..................|NERDTreeFunctionality| |
| 2.1.Global commands...................|NERDTreeGlobalCommands| |
| 2.2.Bookmarks.........................|NERDTreeBookmarks| |
| 2.2.1.The bookmark table..........|NERDTreeBookmarkTable| |
| 2.2.2.Bookmark commands...........|NERDTreeBookmarkCommands| |
| 2.2.3.Invalid bookmarks...........|NERDTreeInvalidBookmarks| |
| 2.3.NERD tree mappings................|NERDTreeMappings| |
| 2.4.The NERD tree menu................|NERDTreeMenu| |
| 3.Options.................................|NERDTreeOptions| |
| 3.1.Option summary....................|NERDTreeOptionSummary| |
| 3.2.Option details....................|NERDTreeOptionDetails| |
| 4.The NERD tree API.......................|NERDTreeAPI| |
| 4.1.Key map API.......................|NERDTreeKeymapAPI| |
| 4.2.Menu API..........................|NERDTreeMenuAPI| |
| 5.About...................................|NERDTreeAbout| |
| 6.Changelog...............................|NERDTreeChangelog| |
| 7.Credits.................................|NERDTreeCredits| |
| 8.License.................................|NERDTreeLicense| |
| |
| ============================================================================== |
| 1. Intro *NERDTree* |
| |
| What is this "NERD tree"?? |
| |
| The NERD tree allows you to explore your filesystem and to open files and |
| directories. It presents the filesystem to you in the form of a tree which you |
| manipulate with the keyboard and/or mouse. It also allows you to perform |
| simple filesystem operations. |
| |
| The following features and functionality are provided by the NERD tree: |
| * Files and directories are displayed in a hierarchical tree structure |
| * Different highlighting is provided for the following types of nodes: |
| * files |
| * directories |
| * sym-links |
| * windows .lnk files |
| * read-only files |
| * executable files |
| * Many (customisable) mappings are provided to manipulate the tree: |
| * Mappings to open/close/explore directory nodes |
| * Mappings to open files in new/existing windows/tabs |
| * Mappings to change the current root of the tree |
| * Mappings to navigate around the tree |
| * ... |
| * Directories and files can be bookmarked. |
| * Most NERD tree navigation can also be done with the mouse |
| * Filtering of tree content (can be toggled at runtime) |
| * custom file filters to prevent e.g. vim backup files being displayed |
| * optional displaying of hidden files (. files) |
| * files can be "turned off" so that only directories are displayed |
| * The position and size of the NERD tree window can be customised |
| * The order in which the nodes in the tree are listed can be customised. |
| * A model of your filesystem is created/maintained as you explore it. This |
| has several advantages: |
| * All filesystem information is cached and is only re-read on demand |
| * If you revisit a part of the tree that you left earlier in your |
| session, the directory nodes will be opened/closed as you left them |
| * The script remembers the cursor position and window position in the NERD |
| tree so you can toggle it off (or just close the tree window) and then |
| reopen it (with NERDTreeToggle) the NERD tree window will appear exactly |
| as you left it |
| * You can have a separate NERD tree for each tab, share trees across tabs, |
| or a mix of both. |
| * By default the script overrides the default file browser (netw), so if |
| you :edit a directory a (slighly modified) NERD tree will appear in the |
| current window |
| * A programmable menu system is provided (simulates right clicking on a |
| node) |
| * one default menu plugin is provided to perform basic filesytem |
| operations (create/delete/move/copy files/directories) |
| * There's an API for adding your own keymappings |
| |
| |
| ============================================================================== |
| 2. Functionality provided *NERDTreeFunctionality* |
| |
| ------------------------------------------------------------------------------ |
| 2.1. Global Commands *NERDTreeGlobalCommands* |
| |
| :NERDTree [<start-directory> | <bookmark>] *:NERDTree* |
| Opens a fresh NERD tree. The root of the tree depends on the argument |
| given. There are 3 cases: If no argument is given, the current directory |
| will be used. If a directory is given, that will be used. If a bookmark |
| name is given, the corresponding directory will be used. For example: > |
| :NERDTree /home/marty/vim7/src |
| :NERDTree foo (foo is the name of a bookmark) |
| < |
| :NERDTreeFromBookmark <bookmark> *:NERDTreeFromBookmark* |
| Opens a fresh NERD tree with the root initialized to the dir for |
| <bookmark>. This only reason to use this command over :NERDTree is for |
| the completion (which is for bookmarks rather than directories). |
| |
| :NERDTreeToggle [<start-directory> | <bookmark>] *:NERDTreeToggle* |
| If a NERD tree already exists for this tab, it is reopened and rendered |
| again. If no NERD tree exists for this tab then this command acts the |
| same as the |:NERDTree| command. |
| |
| :NERDTreeMirror *:NERDTreeMirror* |
| Shares an existing NERD tree, from another tab, in the current tab. |
| Changes made to one tree are reflected in both as they are actually the |
| same buffer. |
| |
| If only one other NERD tree exists, that tree is automatically mirrored. If |
| more than one exists, the script will ask which tree to mirror. |
| |
| :NERDTreeClose *:NERDTreeClose* |
| Close the NERD tree in this tab. |
| |
| :NERDTreeFind *:NERDTreeFind* |
| Find the current file in the tree. If no tree exists for the current tab, |
| or the file is not under the current root, then initialize a new tree where |
| the root is the directory of the current file. |
| |
| ------------------------------------------------------------------------------ |
| 2.2. Bookmarks *NERDTreeBookmarks* |
| |
| Bookmarks in the NERD tree are a way to tag files or directories of interest. |
| For example, you could use bookmarks to tag all of your project directories. |
| |
| ------------------------------------------------------------------------------ |
| 2.2.1. The Bookmark Table *NERDTreeBookmarkTable* |
| |
| If the bookmark table is active (see |NERDTree-B| and |
| |'NERDTreeShowBookmarks'|), it will be rendered above the tree. You can double |
| click bookmarks or use the |NERDTree-o| mapping to activate them. See also, |
| |NERDTree-t| and |NERDTree-T| |
| |
| ------------------------------------------------------------------------------ |
| 2.2.2. Bookmark commands *NERDTreeBookmarkCommands* |
| |
| Note that the following commands are only available in the NERD tree buffer. |
| |
| :Bookmark <name> |
| Bookmark the current node as <name>. If there is already a <name> |
| bookmark, it is overwritten. <name> must not contain spaces. |
| |
| :BookmarkToRoot <bookmark> |
| Make the directory corresponding to <bookmark> the new root. If a treenode |
| corresponding to <bookmark> is already cached somewhere in the tree then |
| the current tree will be used, otherwise a fresh tree will be opened. |
| Note that if <bookmark> points to a file then its parent will be used |
| instead. |
| |
| :RevealBookmark <bookmark> |
| If the node is cached under the current root then it will be revealed |
| (i.e. directory nodes above it will be opened) and the cursor will be |
| placed on it. |
| |
| :OpenBookmark <bookmark> |
| <bookmark> must point to a file. The file is opened as though |NERDTree-o| |
| was applied. If the node is cached under the current root then it will be |
| revealed and the cursor will be placed on it. |
| |
| :ClearBookmarks [<bookmarks>] |
| Remove all the given bookmarks. If no bookmarks are given then remove all |
| bookmarks on the current node. |
| |
| :ClearAllBookmarks |
| Remove all bookmarks. |
| |
| :ReadBookmarks |
| Re-read the bookmarks in the |'NERDTreeBookmarksFile'|. |
| |
| See also |:NERDTree| and |:NERDTreeFromBookmark|. |
| |
| ------------------------------------------------------------------------------ |
| 2.2.3. Invalid Bookmarks *NERDTreeInvalidBookmarks* |
| |
| If invalid bookmarks are detected, the script will issue an error message and |
| the invalid bookmarks will become unavailable for use. |
| |
| These bookmarks will still be stored in the bookmarks file (see |
| |'NERDTreeBookmarksFile'|), down the bottom. There will always be a blank line |
| after the valid bookmarks but before the invalid ones. |
| |
| Each line in the bookmarks file represents one bookmark. The proper format is: |
| <bookmark name><space><full path to the bookmark location> |
| |
| After you have corrected any invalid bookmarks, either restart vim, or go |
| :ReadBookmarks from the NERD tree window. |
| |
| ------------------------------------------------------------------------------ |
| 2.3. NERD tree Mappings *NERDTreeMappings* |
| |
| Default Description~ help-tag~ |
| Key~ |
| |
| o.......Open files, directories and bookmarks....................|NERDTree-o| |
| go......Open selected file, but leave cursor in the NERDTree.....|NERDTree-go| |
| t.......Open selected node/bookmark in a new tab.................|NERDTree-t| |
| T.......Same as 't' but keep the focus on the current tab........|NERDTree-T| |
| i.......Open selected file in a split window.....................|NERDTree-i| |
| gi......Same as i, but leave the cursor on the NERDTree..........|NERDTree-gi| |
| s.......Open selected file in a new vsplit.......................|NERDTree-s| |
| gs......Same as s, but leave the cursor on the NERDTree..........|NERDTree-gs| |
| O.......Recursively open the selected directory..................|NERDTree-O| |
| x.......Close the current nodes parent...........................|NERDTree-x| |
| X.......Recursively close all children of the current node.......|NERDTree-X| |
| e.......Edit the current dif.....................................|NERDTree-e| |
| |
| <CR>...............same as |NERDTree-o|. |
| double-click.......same as the |NERDTree-o| map. |
| middle-click.......same as |NERDTree-i| for files, same as |
| |NERDTree-e| for dirs. |
| |
| D.......Delete the current bookmark .............................|NERDTree-D| |
| |
| P.......Jump to the root node....................................|NERDTree-P| |
| p.......Jump to current nodes parent.............................|NERDTree-p| |
| K.......Jump up inside directories at the current tree depth.....|NERDTree-K| |
| J.......Jump down inside directories at the current tree depth...|NERDTree-J| |
| <C-J>...Jump down to the next sibling of the current directory...|NERDTree-C-J| |
| <C-K>...Jump up to the previous sibling of the current directory.|NERDTree-C-K| |
| |
| C.......Change the tree root to the selected dir.................|NERDTree-C| |
| u.......Move the tree root up one directory......................|NERDTree-u| |
| U.......Same as 'u' except the old root node is left open........|NERDTree-U| |
| r.......Recursively refresh the current directory................|NERDTree-r| |
| R.......Recursively refresh the current root.....................|NERDTree-R| |
| m.......Display the NERD tree menu...............................|NERDTree-m| |
| cd......Change the CWD to the dir of the selected node...........|NERDTree-cd| |
| |
| I.......Toggle whether hidden files displayed....................|NERDTree-I| |
| f.......Toggle whether the file filters are used.................|NERDTree-f| |
| F.......Toggle whether files are displayed.......................|NERDTree-F| |
| B.......Toggle whether the bookmark table is displayed...........|NERDTree-B| |
| |
| q.......Close the NERDTree window................................|NERDTree-q| |
| A.......Zoom (maximize/minimize) the NERDTree window.............|NERDTree-A| |
| ?.......Toggle the display of the quick help.....................|NERDTree-?| |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-o* |
| Default key: o |
| Map option: NERDTreeMapActivateNode |
| Applies to: files and directories. |
| |
| If a file node is selected, it is opened in the previous window. |
| |
| If a directory is selected it is opened or closed depending on its current |
| state. |
| |
| If a bookmark that links to a directory is selected then that directory |
| becomes the new root. |
| |
| If a bookmark that links to a file is selected then that file is opened in the |
| previous window. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-go* |
| Default key: go |
| Map option: None |
| Applies to: files. |
| |
| If a file node is selected, it is opened in the previous window, but the |
| cursor does not move. |
| |
| The key combo for this mapping is always "g" + NERDTreeMapActivateNode (see |
| |NERDTree-o|). |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-t* |
| Default key: t |
| Map option: NERDTreeMapOpenInTab |
| Applies to: files and directories. |
| |
| Opens the selected file in a new tab. If a directory is selected, a fresh |
| NERD Tree for that directory is opened in a new tab. |
| |
| If a bookmark which points to a directory is selected, open a NERD tree for |
| that directory in a new tab. If the bookmark points to a file, open that file |
| in a new tab. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-T* |
| Default key: T |
| Map option: NERDTreeMapOpenInTabSilent |
| Applies to: files and directories. |
| |
| The same as |NERDTree-t| except that the focus is kept in the current tab. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-i* |
| Default key: i |
| Map option: NERDTreeMapOpenSplit |
| Applies to: files. |
| |
| Opens the selected file in a new split window and puts the cursor in the new |
| window. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-gi* |
| Default key: gi |
| Map option: None |
| Applies to: files. |
| |
| The same as |NERDTree-i| except that the cursor is not moved. |
| |
| The key combo for this mapping is always "g" + NERDTreeMapOpenSplit (see |
| |NERDTree-i|). |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-s* |
| Default key: s |
| Map option: NERDTreeMapOpenVSplit |
| Applies to: files. |
| |
| Opens the selected file in a new vertically split window and puts the cursor in |
| the new window. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-gs* |
| Default key: gs |
| Map option: None |
| Applies to: files. |
| |
| The same as |NERDTree-s| except that the cursor is not moved. |
| |
| The key combo for this mapping is always "g" + NERDTreeMapOpenVSplit (see |
| |NERDTree-s|). |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-O* |
| Default key: O |
| Map option: NERDTreeMapOpenRecursively |
| Applies to: directories. |
| |
| Recursively opens the selelected directory. |
| |
| All files and directories are cached, but if a directory would not be |
| displayed due to file filters (see |'NERDTreeIgnore'| |NERDTree-f|) or the |
| hidden file filter (see |'NERDTreeShowHidden'|) then its contents are not |
| cached. This is handy, especially if you have .svn directories. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-x* |
| Default key: x |
| Map option: NERDTreeMapCloseDir |
| Applies to: files and directories. |
| |
| Closes the parent of the selected node. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-X* |
| Default key: X |
| Map option: NERDTreeMapCloseChildren |
| Applies to: directories. |
| |
| Recursively closes all children of the selected directory. |
| |
| Tip: To quickly "reset" the tree, use |NERDTree-P| with this mapping. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-e* |
| Default key: e |
| Map option: NERDTreeMapOpenExpl |
| Applies to: files and directories. |
| |
| |:edit|s the selected directory, or the selected file's directory. This could |
| result in a NERD tree or a netrw being opened, depending on |
| |'NERDTreeHijackNetrw'|. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-D* |
| Default key: D |
| Map option: NERDTreeMapDeleteBookmark |
| Applies to: lines in the bookmarks table |
| |
| Deletes the currently selected bookmark. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-P* |
| Default key: P |
| Map option: NERDTreeMapJumpRoot |
| Applies to: no restrictions. |
| |
| Jump to the tree root. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-p* |
| Default key: p |
| Map option: NERDTreeMapJumpParent |
| Applies to: files and directories. |
| |
| Jump to the parent node of the selected node. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-K* |
| Default key: K |
| Map option: NERDTreeMapJumpFirstChild |
| Applies to: files and directories. |
| |
| Jump to the first child of the current nodes parent. |
| |
| If the cursor is already on the first node then do the following: |
| * loop back thru the siblings of the current nodes parent until we find an |
| open dir with children |
| * go to the first child of that node |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-J* |
| Default key: J |
| Map option: NERDTreeMapJumpLastChild |
| Applies to: files and directories. |
| |
| Jump to the last child of the current nodes parent. |
| |
| If the cursor is already on the last node then do the following: |
| * loop forward thru the siblings of the current nodes parent until we find |
| an open dir with children |
| * go to the last child of that node |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-C-J* |
| Default key: <C-J> |
| Map option: NERDTreeMapJumpNextSibling |
| Applies to: files and directories. |
| |
| Jump to the next sibling of the selected node. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-C-K* |
| Default key: <C-K> |
| Map option: NERDTreeMapJumpPrevSibling |
| Applies to: files and directories. |
| |
| Jump to the previous sibling of the selected node. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-C* |
| Default key: C |
| Map option: NERDTreeMapChdir |
| Applies to: directories. |
| |
| Make the selected directory node the new tree root. If a file is selected, its |
| parent is used. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-u* |
| Default key: u |
| Map option: NERDTreeMapUpdir |
| Applies to: no restrictions. |
| |
| Move the tree root up a dir (like doing a "cd .."). |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-U* |
| Default key: U |
| Map option: NERDTreeMapUpdirKeepOpen |
| Applies to: no restrictions. |
| |
| Like |NERDTree-u| except that the old tree root is kept open. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-r* |
| Default key: r |
| Map option: NERDTreeMapRefresh |
| Applies to: files and directories. |
| |
| If a dir is selected, recursively refresh that dir, i.e. scan the filesystem |
| for changes and represent them in the tree. |
| |
| If a file node is selected then the above is done on it's parent. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-R* |
| Default key: R |
| Map option: NERDTreeMapRefreshRoot |
| Applies to: no restrictions. |
| |
| Recursively refresh the tree root. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-m* |
| Default key: m |
| Map option: NERDTreeMapMenu |
| Applies to: files and directories. |
| |
| Display the NERD tree menu. See |NERDTreeMenu| for details. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-cd* |
| Default key: cd |
| Map option: NERDTreeMapChdir |
| Applies to: files and directories. |
| |
| Change vims current working directory to that of the selected node. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-I* |
| Default key: I |
| Map option: NERDTreeMapToggleHidden |
| Applies to: no restrictions. |
| |
| Toggles whether hidden files (i.e. "dot files") are displayed. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-f* |
| Default key: f |
| Map option: NERDTreeMapToggleFilters |
| Applies to: no restrictions. |
| |
| Toggles whether file filters are used. See |'NERDTreeIgnore'| for details. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-F* |
| Default key: F |
| Map option: NERDTreeMapToggleFiles |
| Applies to: no restrictions. |
| |
| Toggles whether file nodes are displayed. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-B* |
| Default key: B |
| Map option: NERDTreeMapToggleBookmarks |
| Applies to: no restrictions. |
| |
| Toggles whether the bookmarks table is displayed. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-q* |
| Default key: q |
| Map option: NERDTreeMapQuit |
| Applies to: no restrictions. |
| |
| Closes the NERDtree window. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-A* |
| Default key: A |
| Map option: NERDTreeMapToggleZoom |
| Applies to: no restrictions. |
| |
| Maximize (zoom) and minimize the NERDtree window. |
| |
| ------------------------------------------------------------------------------ |
| *NERDTree-?* |
| Default key: ? |
| Map option: NERDTreeMapHelp |
| Applies to: no restrictions. |
| |
| Toggles whether the quickhelp is displayed. |
| |
| ------------------------------------------------------------------------------ |
| 2.3. The NERD tree menu *NERDTreeMenu* |
| |
| The NERD tree has a menu that can be programmed via the an API (see |
| |NERDTreeMenuAPI|). The idea is to simulate the "right click" menus that most |
| file explorers have. |
| |
| The script comes with two default menu plugins: exec_menuitem.vim and |
| fs_menu.vim. fs_menu.vim adds some basic filesystem operations to the menu for |
| creating/deleting/moving/copying files and dirs. exec_menuitem.vim provides a |
| menu item to execute executable files. |
| |
| Related tags: |NERDTree-m| |NERDTreeApi| |
| |
| ============================================================================== |
| 3. Customisation *NERDTreeOptions* |
| |
| |
| ------------------------------------------------------------------------------ |
| 3.1. Customisation summary *NERDTreeOptionSummary* |
| |
| The script provides the following options that can customise the behaviour the |
| NERD tree. These options should be set in your vimrc. |
| |
| |'loaded_nerd_tree'| Turns off the script. |
| |
| |'NERDChristmasTree'| Tells the NERD tree to make itself colourful |
| and pretty. |
| |
| |'NERDTreeAutoCenter'| Controls whether the NERD tree window centers |
| when the cursor moves within a specified |
| distance to the top/bottom of the window. |
| |'NERDTreeAutoCenterThreshold'| Controls the sensitivity of autocentering. |
| |
| |'NERDTreeCaseSensitiveSort'| Tells the NERD tree whether to be case |
| sensitive or not when sorting nodes. |
| |
| |'NERDTreeChDirMode'| Tells the NERD tree if/when it should change |
| vim's current working directory. |
| |
| |'NERDTreeHighlightCursorline'| Tell the NERD tree whether to highlight the |
| current cursor line. |
| |
| |'NERDTreeHijackNetrw'| Tell the NERD tree whether to replace the netrw |
| autocommands for exploring local directories. |
| |
| |'NERDTreeIgnore'| Tells the NERD tree which files to ignore. |
| |
| |'NERDTreeBookmarksFile'| Where the bookmarks are stored. |
| |
| |'NERDTreeMouseMode'| Tells the NERD tree how to handle mouse |
| clicks. |
| |
| |'NERDTreeQuitOnOpen'| Closes the tree window after opening a file. |
| |
| |'NERDTreeShowBookmarks'| Tells the NERD tree whether to display the |
| bookmarks table on startup. |
| |
| |'NERDTreeShowFiles'| Tells the NERD tree whether to display files |
| in the tree on startup. |
| |
| |'NERDTreeShowHidden'| Tells the NERD tree whether to display hidden |
| files on startup. |
| |
| |'NERDTreeShowLineNumbers'| Tells the NERD tree whether to display line |
| numbers in the tree window. |
| |
| |'NERDTreeSortOrder'| Tell the NERD tree how to sort the nodes in |
| the tree. |
| |
| |'NERDTreeStatusline'| Set a statusline for NERD tree windows. |
| |
| |'NERDTreeWinPos'| Tells the script where to put the NERD tree |
| window. |
| |
| |'NERDTreeWinSize'| Sets the window size when the NERD tree is |
| opened. |
| |
| ------------------------------------------------------------------------------ |
| 3.2. Customisation details *NERDTreeOptionDetails* |
| |
| To enable any of the below options you should put the given line in your |
| ~/.vimrc |
| |
| *'loaded_nerd_tree'* |
| If this plugin is making you feel homicidal, it may be a good idea to turn it |
| off with this line in your vimrc: > |
| let loaded_nerd_tree=1 |
| < |
| ------------------------------------------------------------------------------ |
| *'NERDChristmasTree'* |
| Values: 0 or 1. |
| Default: 1. |
| |
| If this option is set to 1 then some extra syntax highlighting elements are |
| added to the nerd tree to make it more colourful. |
| |
| Set it to 0 for a more vanilla looking tree. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeAutoCenter'* |
| Values: 0 or 1. |
| Default: 1 |
| |
| If set to 1, the NERD tree window will center around the cursor if it moves to |
| within |'NERDTreeAutoCenterThreshold'| lines of the top/bottom of the window. |
| |
| This is ONLY done in response to tree navigation mappings, |
| i.e. |NERDTree-J| |NERDTree-K| |NERDTree-C-J| |NERDTree-C-K| |NERDTree-p| |
| |NERDTree-P| |
| |
| The centering is done with a |zz| operation. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeAutoCenterThreshold'* |
| Values: Any natural number. |
| Default: 3 |
| |
| This option controls the "sensitivity" of the NERD tree auto centering. See |
| |'NERDTreeAutoCenter'| for details. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeCaseSensitiveSort'* |
| Values: 0 or 1. |
| Default: 0. |
| |
| By default the NERD tree does not sort nodes case sensitively, i.e. nodes |
| could appear like this: > |
| bar.c |
| Baz.c |
| blarg.c |
| boner.c |
| Foo.c |
| < |
| But, if you set this option to 1 then the case of the nodes will be taken into |
| account. The above nodes would then be sorted like this: > |
| Baz.c |
| Foo.c |
| bar.c |
| blarg.c |
| boner.c |
| < |
| ------------------------------------------------------------------------------ |
| *'NERDTreeChDirMode'* |
| |
| Values: 0, 1 or 2. |
| Default: 0. |
| |
| Use this option to tell the script when (if at all) to change the current |
| working directory (CWD) for vim. |
| |
| If it is set to 0 then the CWD is never changed by the NERD tree. |
| |
| If set to 1 then the CWD is changed when the NERD tree is first loaded to the |
| directory it is initialized in. For example, if you start the NERD tree with > |
| :NERDTree /home/marty/foobar |
| < |
| then the CWD will be changed to /home/marty/foobar and will not be changed |
| again unless you init another NERD tree with a similar command. |
| |
| If the option is set to 2 then it behaves the same as if set to 1 except that |
| the CWD is changed whenever the tree root is changed. For example, if the CWD |
| is /home/marty/foobar and you make the node for /home/marty/foobar/baz the new |
| root then the CWD will become /home/marty/foobar/baz. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeHighlightCursorline'* |
| Values: 0 or 1. |
| Default: 1. |
| |
| If set to 1, the current cursor line in the NERD tree buffer will be |
| highlighted. This is done using the |'cursorline'| option. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeHijackNetrw'* |
| Values: 0 or 1. |
| Default: 1. |
| |
| If set to 1, doing a > |
| :edit <some directory> |
| < |
| will open up a "secondary" NERD tree instead of a netrw in the target window. |
| |
| Secondary NERD trees behaves slighly different from a regular trees in the |
| following respects: |
| 1. 'o' will open the selected file in the same window as the tree, |
| replacing it. |
| 2. you can have as many secondary tree as you want in the same tab. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeIgnore'* |
| Values: a list of regular expressions. |
| Default: ['\~$']. |
| |
| This option is used to specify which files the NERD tree should ignore. It |
| must be a list of regular expressions. When the NERD tree is rendered, any |
| files/dirs that match any of the regex's in 'NERDTreeIgnore' wont be |
| displayed. |
| |
| For example if you put the following line in your vimrc: > |
| let NERDTreeIgnore=['\.vim$', '\~$'] |
| < |
| then all files ending in .vim or ~ will be ignored. |
| |
| Note: to tell the NERD tree not to ignore any files you must use the following |
| line: > |
| let NERDTreeIgnore=[] |
| < |
| |
| The file filters can be turned on and off dynamically with the |NERDTree-f| |
| mapping. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeBookmarksFile'* |
| Values: a path |
| Default: $HOME/.NERDTreeBookmarks |
| |
| This is where bookmarks are saved. See |NERDTreeBookmarkCommands|. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeMouseMode'* |
| Values: 1, 2 or 3. |
| Default: 1. |
| |
| If set to 1 then a double click on a node is required to open it. |
| If set to 2 then a single click will open directory nodes, while a double |
| click will still be required for file nodes. |
| If set to 3 then a single click will open any node. |
| |
| Note: a double click anywhere on a line that a tree node is on will |
| activate it, but all single-click activations must be done on name of the node |
| itself. For example, if you have the following node: > |
| | | |-application.rb |
| < |
| then (to single click activate it) you must click somewhere in |
| 'application.rb'. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeQuitOnOpen'* |
| |
| Values: 0 or 1. |
| Default: 0 |
| |
| If set to 1, the NERD tree window will close after opening a file with the |
| |NERDTree-o|, |NERDTree-i|, |NERDTree-t| and |NERDTree-T| mappings. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeShowBookmarks'* |
| Values: 0 or 1. |
| Default: 0. |
| |
| If this option is set to 1 then the bookmarks table will be displayed. |
| |
| This option can be toggled dynamically, per tree, with the |NERDTree-B| |
| mapping. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeShowFiles'* |
| Values: 0 or 1. |
| Default: 1. |
| |
| If this option is set to 1 then files are displayed in the NERD tree. If it is |
| set to 0 then only directories are displayed. |
| |
| This option can be toggled dynamically, per tree, with the |NERDTree-F| |
| mapping and is useful for drastically shrinking the tree when you are |
| navigating to a different part of the tree. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeShowHidden'* |
| Values: 0 or 1. |
| Default: 0. |
| |
| This option tells vim whether to display hidden files by default. This option |
| can be dynamically toggled, per tree, with the |NERDTree-I| mapping. Use one |
| of the follow lines to set this option: > |
| let NERDTreeShowHidden=0 |
| let NERDTreeShowHidden=1 |
| < |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeShowLineNumbers'* |
| Values: 0 or 1. |
| Default: 0. |
| |
| This option tells vim whether to display line numbers for the NERD tree |
| window. Use one of the follow lines to set this option: > |
| let NERDTreeShowLineNumbers=0 |
| let NERDTreeShowLineNumbers=1 |
| < |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeSortOrder'* |
| Values: a list of regular expressions. |
| Default: ['\/$', '*', '\.swp$', '\.bak$', '\~$'] |
| |
| This option is set to a list of regular expressions which are used to |
| specify the order of nodes under their parent. |
| |
| For example, if the option is set to: > |
| ['\.vim$', '\.c$', '\.h$', '*', 'foobar'] |
| < |
| then all .vim files will be placed at the top, followed by all .c files then |
| all .h files. All files containing the string 'foobar' will be placed at the |
| end. The star is a special flag: it tells the script that every node that |
| doesnt match any of the other regexps should be placed here. |
| |
| If no star is present in 'NERDTreeSortOrder' then one is automatically |
| appended to the array. |
| |
| The regex '\/$' should be used to match directory nodes. |
| |
| After this sorting is done, the files in each group are sorted alphabetically. |
| |
| Other examples: > |
| (1) ['*', '\/$'] |
| (2) [] |
| (3) ['\/$', '\.rb$', '\.php$', '*', '\.swp$', '\.bak$', '\~$'] |
| < |
| 1. Directories will appear last, everything else will appear above. |
| 2. Everything will simply appear in alphabetical order. |
| 3. Dirs will appear first, then ruby and php. Swap files, bak files and vim |
| backup files will appear last with everything else preceding them. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeStatusline'* |
| Values: Any valid statusline setting. |
| Default: %{b:NERDTreeRoot.path.strForOS(0)} |
| |
| Tells the script what to use as the |'statusline'| setting for NERD tree |
| windows. |
| |
| Note that the statusline is set using |:let-&| not |:set| so escaping spaces |
| isn't necessary. |
| |
| Setting this option to -1 will will deactivate it so that your global |
| statusline setting is used instead. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeWinPos'* |
| Values: "left" or "right" |
| Default: "left". |
| |
| This option is used to determine where NERD tree window is placed on the |
| screen. |
| |
| This option makes it possible to use two different explorer plugins |
| simultaneously. For example, you could have the taglist plugin on the left of |
| the window and the NERD tree on the right. |
| |
| ------------------------------------------------------------------------------ |
| *'NERDTreeWinSize'* |
| Values: a positive integer. |
| Default: 31. |
| |
| This option is used to change the size of the NERD tree when it is loaded. |
| |
| ============================================================================== |
| 4. The NERD tree API *NERDTreeAPI* |
| |
| The NERD tree script allows you to add custom key mappings and menu items via |
| a set of API calls. Any scripts that use this API should be placed in |
| ~/.vim/nerdtree_plugin/ (*nix) or ~/vimfiles/nerdtree_plugin (windows). |
| |
| The script exposes some prototype objects that can be used to manipulate the |
| tree and/or get information from it: > |
| g:NERDTreePath |
| g:NERDTreeDirNode |
| g:NERDTreeFileNode |
| g:NERDTreeBookmark |
| < |
| See the code/comments in NERD_tree.vim to find how to use these objects. The |
| following code conventions are used: |
| * class members start with a capital letter |
| * instance members start with a lower case letter |
| * private members start with an underscore |
| |
| See this blog post for more details: |
| http://got-ravings.blogspot.com/2008/09/vim-pr0n-prototype-based-objects.html |
| |
| ------------------------------------------------------------------------------ |
| 4.1. Key map API *NERDTreeKeymapAPI* |
| |
| NERDTreeAddKeyMap({options}) *NERDTreeAddKeyMap()* |
| Adds a new keymapping for all NERD tree buffers. |
| {options} must be a dictionary, and must contain the following keys: |
| "key" - the trigger key for the new mapping |
| "callback" - the function the new mapping will be bound to |
| "quickhelpText" - the text that will appear in the quickhelp (see |
| |NERDTree-?|) |
| |
| Example: > |
| call NERDTreeAddKeyMap({ |
| \ 'key': 'b', |
| \ 'callback': 'NERDTreeEchoCurrentNode', |
| \ 'quickhelpText': 'echo full path of current node' }) |
| |
| function! NERDTreeEchoCurrentNode() |
| let n = g:NERDTreeFileNode.GetSelected() |
| if n != {} |
| echomsg 'Current node: ' . n.path.str() |
| endif |
| endfunction |
| < |
| This code should sit in a file like ~/.vim/nerdtree_plugin/mymapping.vim. |
| It adds a (rather useless) mapping on 'b' which echos the full path to the |
| current node. |
| |
| ------------------------------------------------------------------------------ |
| 4.2. Menu API *NERDTreeMenuAPI* |
| |
| NERDTreeAddSubmenu({options}) *NERDTreeAddSubmenu()* |
| Creates and returns a new submenu. |
| |
| {options} must be a dictionary and must contain the following keys: |
| "text" - the text of the submenu that the user will see |
| "shortcut" - a shortcut key for the submenu (need not be unique) |
| |
| The following keys are optional: |
| "isActiveCallback" - a function that will be called to determine whether |
| this submenu item will be displayed or not. The callback function must return |
| 0 or 1. |
| "parent" - the parent submenu of the new submenu (returned from a previous |
| invocation of NERDTreeAddSubmenu()). If this key is left out then the new |
| submenu will sit under the top level menu. |
| |
| See below for an example. |
| |
| NERDTreeAddMenuItem({options}) *NERDTreeAddMenuItem()* |
| Adds a new menu item to the NERD tree menu (see |NERDTreeMenu|). |
| |
| {options} must be a dictionary and must contain the |
| following keys: |
| "text" - the text of the menu item which the user will see |
| "shortcut" - a shortcut key for the menu item (need not be unique) |
| "callback" - the function that will be called when the user activates the |
| menu item. |
| |
| The following keys are optional: |
| "isActiveCallback" - a function that will be called to determine whether |
| this menu item will be displayed or not. The callback function must return |
| 0 or 1. |
| "parent" - if the menu item belongs under a submenu then this key must be |
| specified. This value for this key will be the object that |
| was returned when the submenu was created with |NERDTreeAddSubmenu()|. |
| |
| See below for an example. |
| |
| NERDTreeAddMenuSeparator([{options}]) *NERDTreeAddMenuSeparator()* |
| Adds a menu separator (a row of dashes). |
| |
| {options} is an optional dictionary that may contain the following keys: |
| "isActiveCallback" - see description in |NERDTreeAddMenuItem()|. |
| |
| Below is an example of the menu API in action. > |
| call NERDTreeAddMenuSeparator() |
| |
| call NERDTreeAddMenuItem({ |
| \ 'text': 'a (t)op level menu item', |
| \ 'shortcut': 't', |
| \ 'callback': 'SomeFunction' }) |
| |
| let submenu = NERDTreeAddSubmenu({ |
| \ 'text': 'a (s)ub menu', |
| \ 'shortcut': 's' }) |
| |
| call NERDTreeAddMenuItem({ |
| \ 'text': '(n)ested item 1', |
| \ 'shortcut': 'n', |
| \ 'callback': 'SomeFunction', |
| \ 'parent': submenu }) |
| |
| call NERDTreeAddMenuItem({ |
| \ 'text': '(n)ested item 2', |
| \ 'shortcut': 'n', |
| \ 'callback': 'SomeFunction', |
| \ 'parent': submenu }) |
| < |
| This will create the following menu: > |
| -------------------- |
| a (t)op level menu item |
| a (s)ub menu |
| < |
| Where selecting "a (s)ub menu" will lead to a second menu: > |
| (n)ested item 1 |
| (n)ested item 2 |
| < |
| When any of the 3 concrete menu items are selected the function "SomeFunction" |
| will be called. |
| |
| ------------------------------------------------------------------------------ |
| NERDTreeRender() *NERDTreeRender()* |
| Re-renders the NERD tree buffer. Useful if you change the state of the |
| tree and you want to it to be reflected in the UI. |
| |
| ============================================================================== |
| 5. About *NERDTreeAbout* |
| |
| The author of the NERD tree is a terrible terrible monster called Martyzilla |
| who gobbles up small children with milk and sugar for breakfast. |
| |
| He can be reached at martin.grenfell at gmail dot com. He would love to hear |
| from you, so feel free to send him suggestions and/or comments about this |
| plugin. Don't be shy --- the worst he can do is slaughter you and stuff you in |
| the fridge for later ;) |
| |
| The latest stable versions can be found at |
| http://www.vim.org/scripts/script.php?script_id=1658 |
| |
| The latest dev versions are on github |
| http://github.com/scrooloose/nerdtree |
| |
| |
| ============================================================================== |
| 6. Changelog *NERDTreeChangelog* |
| |
| 4.1.0 |
| features: |
| - NERDTreeFind to reveal the node for the current buffer in the tree, |
| see |NERDTreeFind|. This effectively merges the FindInNERDTree plugin (by |
| Doug McInnes) into the script. |
| - make NERDTreeQuitOnOpen apply to the t/T keymaps too. Thanks to Stefan |
| Ritter and Rémi Prévost. |
| - truncate the root node if wider than the tree window. Thanks to Victor |
| Gonzalez. |
| |
| bugfixes: |
| - really fix window state restoring |
| - fix some win32 path escaping issues. Thanks to Stephan Baumeister, Ricky, |
| jfilip1024, and Chris Chambers |
| |
| 4.0.0 |
| - add a new programmable menu system (see :help NERDTreeMenu). |
| - add new APIs to add menus/menu-items to the menu system as well as |
| custom key mappings to the NERD tree buffer (see :help NERDTreeAPI). |
| - removed the old API functions |
| - added a mapping to maximize/restore the size of nerd tree window, thanks |
| to Guillaume Duranceau for the patch. See :help NERDTree-A for details. |
| |
| - fix a bug where secondary nerd trees (netrw hijacked trees) and |
| NERDTreeQuitOnOpen didnt play nicely, thanks to Curtis Harvey. |
| - fix a bug where the script ignored directories whose name ended in a dot, |
| thanks to Aggelos Orfanakos for the patch. |
| - fix a bug when using the x mapping on the tree root, thanks to Bryan |
| Venteicher for the patch. |
| - fix a bug where the cursor position/window size of the nerd tree buffer |
| wasnt being stored on closing the window, thanks to Richard Hart. |
| - fix a bug where NERDTreeMirror would mirror the wrong tree |
| |
| 3.1.1 |
| - fix a bug where a non-listed no-name buffer was getting created every |
| time the tree windows was created, thanks to Derek Wyatt and owen1 |
| - make <CR> behave the same as the 'o' mapping |
| - some helptag fixes in the doc, thanks strull |
| - fix a bug when using :set nohidden and opening a file where the previous |
| buf was modified. Thanks iElectric |
| - other minor fixes |
| |
| 3.1.0 |
| New features: |
| - add mappings to open files in a vsplit, see :help NERDTree-s and :help |
| NERDTree-gs |
| - make the statusline for the nerd tree window default to something |
| hopefully more useful. See :help 'NERDTreeStatusline' |
| Bugfixes: |
| - make the hijack netrw functionality work when vim is started with "vim |
| <some dir>" (thanks to Alf Mikula for the patch). |
| - fix a bug where the CWD wasnt being changed for some operations even when |
| NERDTreeChDirMode==2 (thanks to Lucas S. Buchala) |
| - add -bar to all the nerd tree :commands so they can chain with other |
| :commands (thanks to tpope) |
| - fix bugs when ignorecase was set (thanks to nach) |
| - fix a bug with the relative path code (thanks to nach) |
| - fix a bug where doing a :cd would cause :NERDTreeToggle to fail (thanks nach) |
| |
| |
| 3.0.1 |
| Bugfixes: |
| - fix bugs with :NERDTreeToggle and :NERDTreeMirror when 'hidden |
| was not set |
| - fix a bug where :NERDTree <path> would fail if <path> was relative and |
| didnt start with a ./ or ../ Thanks to James Kanze. |
| - make the q mapping work with secondary (:e <dir> style) trees, |
| thanks to jamessan |
| - fix a bunch of small bugs with secondary trees |
| |
| More insane refactoring. |
| |
| 3.0.0 |
| - hijack netrw so that doing an :edit <directory> will put a NERD tree in |
| the window rather than a netrw browser. See :help 'NERDTreeHijackNetrw' |
| - allow sharing of trees across tabs, see :help :NERDTreeMirror |
| - remove "top" and "bottom" as valid settings for NERDTreeWinPos |
| - change the '<tab>' mapping to 'i' |
| - change the 'H' mapping to 'I' |
| - lots of refactoring |
| |
| ============================================================================== |
| 7. Credits *NERDTreeCredits* |
| |
| Thanks to the following people for testing, bug reports, ideas etc. Without |
| you I probably would have got bored of the hacking the NERD tree and |
| just downloaded pr0n instead. |
| |
| Tim Carey-Smith (halorgium) |
| Vigil |
| Nick Brettell |
| Thomas Scott Urban |
| Terrance Cohen |
| Yegappan Lakshmanan |
| Jason Mills |
| Michael Geddes (frogonwheels) |
| Yu Jun |
| Michael Madsen |
| AOYAMA Shotaro |
| Zhang Weiwu |
| Niels Aan de Brugh |
| Olivier Yiptong |
| Zhang Shuhan |
| Cory Echols |
| Piotr Czachur |
| Yuan Jiang |
| Matan Nassau |
| Maxim Kim |
| Charlton Wang |
| Matt Wozniski (godlygeek) |
| knekk |
| Sean Chou |
| Ryan Penn |
| Simon Peter Nicholls |
| Michael Foobar |
| Tomasz Chomiuk |
| Denis Pokataev |
| Tim Pope (tpope) |
| James Kanze |
| James Vega (jamessan) |
| Frederic Chanal (nach) |
| Alf Mikula |
| Lucas S. Buchala |
| Curtis Harvey |
| Guillaume Duranceau |
| Richard Hart (hates) |
| Doug McInnes |
| Stefan Ritter |
| Rémi Prévost |
| Victor Gonzalez |
| Stephan Baumeister |
| Ricky |
| jfilip1024 |
| Chris Chambers |
| |
| ============================================================================== |
| 8. License *NERDTreeLicense* |
| |
| The NERD tree is released under the wtfpl. |
| See http://sam.zoy.org/wtfpl/COPYING. |