1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534 |
- *NERDTree.txt* A tree explorer plugin to rule the Vim world. Bwahahaha!!
- # #### #### ~
- ### \/#|### |/#### ~
- d8 888 ##\/#/ \||/##/_/##/_# ~
- d88 888 ee ,e e, ### \/###|/ \/ # ### ~
- d88888 888 88b d88 88b ##_\_#\_\## | #/###_/_#### ~
- 888 888 888 888 , ## #### # \ #| / #### ##/## ~
- 888 888 888 "YeeP" __#_--###`. |{,###---###-~ ~
- \ % @% ~
- Y88b Y88 888'Y88 888 88e 888 88e \%@% 88P'888'Y88 ~
- Y88b Y8 888 ,'Y 888 888D 888 888b %o% P' 888 'Y 888,8, ,e e, ,e e, ~
- b Y88b Y 888C8 888 88" 888 8888D %@% 888 888 " d88 88b d88 88b ~
- 8b Y88b 888 ",d 888 b, 888 888P %@% 888 888 888 , 888 , ~
- 88b Y88b 888,d88 888 88b, 888 88" %@% 888 888 "YeeP" "YeeP" ~
- , -=-%{@%-^- _ ~
- ejm `} 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.NERDTree mappings.................|NERDTreeMappings|
- 2.4.The NERDTree menu.................|NERDTreeMenu|
- 3.Settings................................|NERDTreeSettings|
- 3.1.Settings summary..................|NERDTreeSettingsSummary|
- 3.2.Settings details..................|NERDTreeSettingsDetails|
- 4.The NERDTree API........................|NERDTreeAPI|
- 4.1.Key map API.......................|NERDTreeKeymapAPI|
- 4.2.Menu API..........................|NERDTreeMenuAPI|
- 4.3.Menu API..........................|NERDTreeAddPathFilter()|
- 4.4.Path Listener API.................|NERDTreePathListenerAPI|
- 5.About...................................|NERDTreeAbout|
- 6.License.................................|NERDTreeLicense|
- ==============================================================================
- 1. Intro *NERDTree*
- What is this "NERDTree"??
- The NERDTree 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 NERDTree:
- * 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 NERDTree 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 NERDTree 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 NERDTree window will appear exactly
- as you left it
- * You can have a separate NERDTree for each tab, share trees across tabs,
- or a mix of both.
- * By default the script overrides the default file browser (netrw), so if
- you :edit a directory a (slightly modified) NERDTree 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 filesystem
- 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 NERDTree. 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)
- <
- :NERDTreeVCS [<start-directory> | <bookmark>] *:NERDTreeVCS*
- Like |:NERDTree|, but searches up the directory tree to find the top of
- the version control system repository, and roots the NERDTree there. It
- works with Git, Subversion, Mercurial, Bazaar, and Darcs repositories. A
- couple of examples: >
- :NERDTreeVCS /home/marty/nerdtree/doc (opens /home/marty/nerdtree)
- :NERDTreeVCS (opens root of repository containing CWD)
- <
- :NERDTreeFromBookmark <bookmark> *:NERDTreeFromBookmark*
- Opens a fresh NERDTree with the root initialized to the directory for
- <bookmark>. The 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 NERDTree already exists for this tab, it is reopened and rendered
- again. If <start-directory> or <bookmark> is given, the root of NERDTree
- is set to that path. If no NERDTree exists for this tab then this command
- acts the same as the |:NERDTree| command.
- :NERDTreeToggleVCS [<start-directory> | <bookmark>] *:NERDTreeToggleVCS*
- Like |:NERDTreeToggle|, but searches up the directory tree to find the top of
- the version control system repository, and roots the NERDTree there. It
- works with Git, Subversion, Mercurial, Bazaar, and Darcs repositories. A
- couple of examples: >
- :NERDTreeToggleVCS /home/marty/nerdtree/doc (opens /home/marty/nerdtree)
- :NERDTreeToggleVCS (opens root of repository containing CWD)
- :NERDTreeFocus *:NERDTreeFocus*
- Opens (or reopens) the NERDTree if it is not currently visible;
- otherwise, the cursor is moved to the already-open NERDTree.
- :NERDTreeMirror *:NERDTreeMirror*
- Shares an existing NERDTree, 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 NERDTree exists, that tree is automatically mirrored.
- If more than one exists, the script will ask which tree to mirror.
- :NERDTreeClose *:NERDTreeClose*
- Close the NERDTree in this tab.
- :NERDTreeFind [<path>] *:NERDTreeFind*
- Without the optional argument, find and reveal the file for the active
- buffer in the NERDTree window. With the <path> argument, find and
- reveal the specified path.
- Focus will be shifted to the NERDTree window, and the cursor will be
- placed on the tree node for the determined path. If a NERDTree for the
- current tab does not exist, a new one will be initialized.
- :NERDTreeCWD *:NERDTreeCWD*
- Change the NERDTree root to the current working directory. If no
- NERDTree exists for this tab, a new one is opened.
- :NERDTreeRefreshRoot *:NERDTreeRefreshRoot*
- Refreshes the NERDTree root node.
- ------------------------------------------------------------------------------
- 2.2. Bookmarks *NERDTreeBookmarks*
- Bookmarks in the NERDTree 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: The following commands are only available within the NERDTree buffer.
- :Bookmark [<name>]
- Bookmark the current node as <name>. If there is already a <name>
- bookmark, it is overwritten. <name> must not contain spaces.
- If <name> is not provided, it defaults to the file or directory name.
- For directories, a trailing slash is present.
- :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 <name>
- The Bookmark named <name> is opened as if |NERDTree-o| was applied to
- its entry in the Bookmark table. If the Bookmark points to a directory,
- it is made the new root of the current NERDTree. If the Bookmark points
- to a file, that file is opened for editing in another window.
- :ClearBookmarks [<bookmarks>]
- Remove all the given bookmarks. If no bookmarks are given then remove all
- bookmarks on the current node.
- :ClearAllBookmarks
- Remove all bookmarks.
- :EditBookmarks
- Opens the bookmarks file for manual editing, e.g. for removing invalid
- 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 at 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>
- You can use the :EditBookmarks command to open the bookmarks file for editing.
- After you have corrected any invalid bookmarks, either restart vim, or run
- :ReadBookmarks from the NERDTree window.
- ------------------------------------------------------------------------------
- 2.3. NERDTree Mappings *NERDTreeMappings*
- Default~
- Key Description help-tag~
- o........Open files, directories and bookmarks......................|NERDTree-o|
- go.......Open selected file, but leave cursor in the NERDTree......|NERDTree-go|
- Find selected bookmark directory in current NERDTree
- 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|
- <CR>.....User-definable custom open action.......................|NERDTree-<CR>|
- 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 directory.................................|NERDTree-e|
- double-click....same as |NERDTree-o|.
- middle-click....same as |NERDTree-i| for files, and |NERDTree-e| for directories.
- 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 next sibling of the current directory.......|NERDTree-C-J|
- <C-K>....Jump up to previous sibling of the current directory.....|NERDTree-C-K|
- C........Change the tree root to the selected directory.............|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 NERDTree menu..................................|NERDTree-m|
- cd.......Change the CWD to the directory of the selected node......|NERDTree-cd|
- CD.......Change tree root to the CWD...............................|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 setting: 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 setting: NERDTreeMapPreview
- Applies to: files.
- If a file node or a bookmark that links to a file is selected, it is opened in
- the previous window, but the cursor does not move.
- If a bookmark that links to a directory is selected then that directory
- becomes the new root.
- The default key combo for this mapping is "g" + NERDTreeMapActivateNode (see
- |NERDTree-o|).
- ------------------------------------------------------------------------------
- *NERDTree-t*
- Default key: t
- Map setting: *NERDTreeMapOpenInTab*
- Applies to: files and directories.
- Opens the selected file in a new tab. If a directory is selected, a fresh
- NERDTree for that directory is opened in a new tab.
- If a bookmark which points to a directory is selected, open a NERDTree 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 setting: *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 setting: *NERDTreeMapOpenSplit*
- Applies to: files, and bookmarks pointing 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 setting: *NERDTreeMapPreviewSplit*
- Applies to: files, and bookmarks pointing to files.
- The same as |NERDTree-i| except that the cursor is not moved.
- The default key combo for this mapping is "g" + NERDTreeMapOpenSplit (see
- |NERDTree-i|).
- ------------------------------------------------------------------------------
- *NERDTree-s*
- Default key: s
- Map setting: *NERDTreeMapOpenVSplit*
- Applies to: files, and bookmarks pointing 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 setting: *NERDTreeMapPreviewVSplit*
- Applies to: files, and bookmarks pointing to files.
- The same as |NERDTree-s| except that the cursor is not moved.
- The default key combo for this mapping is "g" + NERDTreeMapOpenVSplit (see
- |NERDTree-s|).
- ------------------------------------------------------------------------------
- *NERDTree-<CR>*
- Default key: <CR>
- Map setting: *NERDTreeMapCustomOpen*
- Applies to: files, directories, and bookmarks
- Performs a customized open action on the selected node. This allows the user
- to define an action that behaves differently from any of the standard
- keys. See |NERDTreeCustomOpenArgs| for more details.
- ------------------------------------------------------------------------------
- *NERDTree-O*
- Default key: O
- Map setting: *NERDTreeMapOpenRecursively*
- Applies to: directories.
- Recursively opens the selected 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 setting: *NERDTreeMapCloseDir*
- Applies to: files and directories.
- Closes the parent of the selected node.
- ------------------------------------------------------------------------------
- *NERDTree-X*
- Default key: X
- Map setting: *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 setting: *NERDTreeMapOpenExpl*
- Applies to: files and directories.
- |:edit|s the selected directory, or the selected file's directory. This could
- result in a NERDTree or a netrw being opened, depending on
- |NERDTreeHijackNetrw|.
- ------------------------------------------------------------------------------
- *NERDTree-D*
- Default key: D
- Map setting: *NERDTreeMapDeleteBookmark*
- Applies to: lines in the bookmarks table
- Deletes the currently selected bookmark.
- ------------------------------------------------------------------------------
- *NERDTree-P*
- Default key: P
- Map setting: *NERDTreeMapJumpRoot*
- Applies to: no restrictions.
- Jump to the tree root.
- ------------------------------------------------------------------------------
- *NERDTree-p*
- Default key: p
- Map setting: *NERDTreeMapJumpParent*
- Applies to: files and directories.
- Jump to the parent node of the selected node.
- ------------------------------------------------------------------------------
- *NERDTree-K*
- Default key: K
- Map setting: *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 directory with children
- * go to the first child of that node
- ------------------------------------------------------------------------------
- *NERDTree-J*
- Default key: J
- Map setting: *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 directory with children
- * go to the last child of that node
- ------------------------------------------------------------------------------
- *NERDTree-C-J*
- Default key: <C-J>
- Map setting: *NERDTreeMapJumpNextSibling*
- Applies to: files and directories.
- Jump to the next sibling of the selected node.
- ------------------------------------------------------------------------------
- *NERDTree-C-K*
- Default key: <C-K>
- Map setting: *NERDTreeMapJumpPrevSibling*
- Applies to: files and directories.
- Jump to the previous sibling of the selected node.
- ------------------------------------------------------------------------------
- *NERDTree-C*
- Default key: C
- Map setting: *NERDTreeMapChangeRoot*
- Applies to: files and 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 setting: *NERDTreeMapUpdir*
- Applies to: no restrictions.
- Move the tree root up a directory (like doing a "cd ..").
- ------------------------------------------------------------------------------
- *NERDTree-U*
- Default key: U
- Map setting: *NERDTreeMapUpdirKeepOpen*
- Applies to: no restrictions.
- Like |NERDTree-u| except that the old tree root is kept open.
- ------------------------------------------------------------------------------
- *NERDTree-r*
- Default key: r
- Map setting: *NERDTreeMapRefresh*
- Applies to: files and directories.
- If a directory is selected, recursively refresh that directory, 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 setting: *NERDTreeMapRefreshRoot*
- Applies to: no restrictions.
- Recursively refresh the tree root.
- ------------------------------------------------------------------------------
- *NERDTree-m*
- Default key: m
- Map setting: *NERDTreeMapMenu*
- Applies to: files and directories.
- Display the NERDTree menu. See |NERDTreeMenu| for details.
- ------------------------------------------------------------------------------
- *NERDTree-cd*
- Default key: cd
- Map setting: *NERDTreeMapChdir*
- Applies to: files and directories.
- Change Vim's current working directory to that of the selected node.
- ------------------------------------------------------------------------------
- *NERDTree-CD*
- Default key: CD
- Map setting: *NERDTreeMapCWD*
- Applies to: no restrictions.
- Change the NERDTree root to Vim's current working directory.
- ------------------------------------------------------------------------------
- *NERDTree-I*
- Default key: I
- Map setting: *NERDTreeMapToggleHidden*
- Applies to: no restrictions.
- Toggles whether hidden files (i.e. "dot files") are displayed.
- ------------------------------------------------------------------------------
- *NERDTree-f*
- Default key: f
- Map setting: *NERDTreeMapToggleFilters*
- Applies to: no restrictions.
- Toggles whether file filters are used. See |NERDTreeIgnore| for details.
- ------------------------------------------------------------------------------
- *NERDTree-F*
- Default key: F
- Map setting: *NERDTreeMapToggleFiles*
- Applies to: no restrictions.
- Toggles whether file nodes are displayed.
- ------------------------------------------------------------------------------
- *NERDTree-B*
- Default key: B
- Map setting: *NERDTreeMapToggleBookmarks*
- Applies to: no restrictions.
- Toggles whether the bookmarks table is displayed.
- ------------------------------------------------------------------------------
- *NERDTree-q*
- Default key: q
- Map setting: *NERDTreeMapQuit*
- Applies to: no restrictions.
- Closes the NERDTree window.
- ------------------------------------------------------------------------------
- *NERDTree-A*
- Default key: A
- Map setting: *NERDTreeMapToggleZoom*
- Applies to: no restrictions.
- Maximize (zoom) and minimize the NERDTree window.
- ------------------------------------------------------------------------------
- *NERDTree-?*
- Default key: ?
- Map setting: *NERDTreeMapHelp*
- Applies to: no restrictions.
- Toggles whether the quickhelp is displayed.
- ------------------------------------------------------------------------------
- 2.3. The NERDTree menu *NERDTreeMenu*
- The NERDTree 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 directories. exec_menuitem.vim
- provides a menu item to execute executable files.
- Related tags: |NERDTree-m| |NERDTreeApi|
- ------------------------------------------------------------------------------
- *NERDTreeMenu-j*
- Default key: j
- Map option: *NERDTreeMenuDown*
- Applies to: The NERDTree menu.
- Moves the cursor down.
- ------------------------------------------------------------------------------
- *NERDTreeMenu-k*
- Default key: k
- Map option: *NERDTreeMenuUp*
- Applies to: The NERDTree menu.
- Moves the cursor up.
- ==============================================================================
- 3. Customisation *NERDTreeSettings*
- ------------------------------------------------------------------------------
- 3.1. Customisation summary *NERDTreeSettingsSummary*
- The plugin provides the following settings that can customise the behaviour
- the NERDTree. These settings should be set in your vimrc, using `:let`.
- |loaded_nerd_tree| Turns off the script.
- |NERDTreeAutoCenter| Controls whether the NERDTree 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 NERDTree whether to be case
- sensitive or not when sorting nodes.
- |NERDTreeNaturalSort| Tells the NERDTree whether to use natural sort
- order or not when sorting nodes.
- |NERDTreeSortHiddenFirst| Tells the NERDTree whether to take the dot at
- the beginning of the hidden file names into
- account when sorting nodes.
- |NERDTreeChDirMode| Tells the NERDTree if/when it should change
- vim's current working directory.
- |NERDTreeHighlightCursorline| Tell the NERDTree whether to highlight the
- current cursor line.
- |NERDTreeHijackNetrw| Tell the NERDTree whether to replace the netrw
- autocommands for exploring local directories.
- |NERDTreeIgnore| Tells the NERDTree which files to ignore.
- |NERDTreeRespectWildIgnore| Tells the NERDTree to respect `'wildignore'`.
- |NERDTreeBookmarksFile| Where the bookmarks are stored.
- |NERDTreeBookmarksSort| Control how the Bookmark table is sorted.
- |NERDTreeMarkBookmarks| Render bookmarked nodes with markers.
- |NERDTreeMouseMode| Manage the interpretation of mouse clicks.
- |NERDTreeQuitOnOpen| Closes the tree window or bookmark table after
- opening a file.
- |NERDTreeShowBookmarks| Tells the NERDTree whether to display the
- bookmarks table on startup.
- |NERDTreeShowFiles| Tells the NERDTree whether to display files in
- the tree on startup.
- |NERDTreeShowHidden| Tells the NERDTree whether to display hidden
- files on startup.
- |NERDTreeShowLineNumbers| Tells the NERDTree whether to display line
- numbers in the tree window.
- |NERDTreeSortOrder| Tell the NERDTree how to sort the nodes in the
- tree.
- |NERDTreeStatusline| Set a statusline for NERDTree windows.
- |NERDTreeWinPos| Tells the script where to put the NERDTree
- window.
- |NERDTreeWinSize| Sets the window size when the NERDTree is
- opened.
- |NERDTreeWinSizeMax| Sets the maximum window size when the NERDTree
- is zoomed.
- |NERDTreeMinimalUI| Disables display of the 'Bookmarks' label and
- 'Press ? for help' text.
- |NERDTreeMinimalMenu| Use a compact menu that fits on a single line
- for adding, copying, deleting, etc
- |NERDTreeCascadeSingleChildDir|
- Collapses on the same line directories that have
- only one child directory.
- |NERDTreeCascadeOpenSingleChildDir|
- Cascade open while selected directory has only
- one child that also is a directory.
- |NERDTreeAutoDeleteBuffer| Tells the NERDTree to automatically remove a
- buffer when a file is being deleted or renamed
- via a context menu command.
- |NERDTreeCreatePrefix| Specify a prefix to be used when creating the
- NERDTree window.
- |NERDTreeRemoveFileCmd| Specify a custom shell command to be used when
- deleting files. Note that it should include one
- space character at the end of the command and it
- applies only to files.
- |NERDTreeRemoveDirCmd| Specify a custom shell command to be used when
- deleting directories. Note that it should
- include one space character at the end of the
- command and it applies only to directories.
- |NERDTreeDirArrowCollapsible| These characters indicate when a directory is
- |NERDTreeDirArrowExpandable| either collapsible or expandable.
- |NERDTreeNodeDelimiter| A single character that is used to separate the
- file or directory name from the rest of the
- characters on the line of text.
- |NERDTreeCustomOpenArgs| A dictionary with values that control how a node
- is opened with the |NERDTree-<CR>| key.
- ------------------------------------------------------------------------------
- 3.2. Customisation details *NERDTreeSettingsDetails*
- To enable any of the below settings you should put an appropriate >
- let <setting>=<value>
- <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
- <
- ------------------------------------------------------------------------------
- *NERDTreeAutoCenter*
- Values: 0 or 1.
- Default: 1
- If set to 1, the NERDTree 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 setting controls the "sensitivity" of the NERDTree auto centering. See
- |NERDTreeAutoCenter| for details.
- ------------------------------------------------------------------------------
- *NERDTreeCaseSensitiveSort*
- Values: 0 or 1.
- Default: 0.
- By default the NERDTree 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 setting 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
- <
- ------------------------------------------------------------------------------
- *NERDTreeNaturalSort*
- Values: 0 or 1.
- Default: 0.
- By default the NERDTree does not sort nodes in natural sort order, i.e. nodes
- could appear like this: >
- z1.txt
- z10.txt
- z100.txt
- z11.txt
- z110.txt
- z2.txt
- z20.txt
- z3.txt
- <
- But if you set this setting to 1 then the natural sort order will be used. The
- above nodes would then be sorted like this: >
- z1.txt
- z2.txt
- z3.txt
- z10.txt
- z11.txt
- z20.txt
- z100.txt
- z110.txt
- <
- ------------------------------------------------------------------------------
- *NERDTreeUseTCD*
- Values: 0 or 1.
- Default: 0.
- By default, NERDTree will use the `:cd` command to change the current working
- directory. If this setting is turned on, and the `:tcd` command is available, it
- will be used instead.
- ------------------------------------------------------------------------------
- *NERDTreeChDirMode*
- Values: 0, 1, 2, or 3.
- Default: 0.
- Use this setting 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 NERDTree.
- If set to 1 then the CWD is changed when the NERDTree is first loaded to the
- directory it is initialized in. For example, if you start the NERDTree 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 NERDTree with a similar command.
- If the setting 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.
- If the set to 3, then it behaves the same as if set to 2, and the CWD is
- changed whenever changing tabs to whatever the tree root is on that tab.
- ------------------------------------------------------------------------------
- *NERDTreeHighlightCursorline*
- Values: 0 or 1.
- Default: 1.
- If set to 1, the current cursor line in the NERDTree buffer will be
- highlighted. This is done using the `'cursorline'` Vim option.
- ------------------------------------------------------------------------------
- *NERDTreeHijackNetrw*
- Values: 0 or 1.
- Default: 1.
- If set to 1, doing a >
- :edit <some directory>
- <
- will open up a window level NERDTree instead of a netrw in the target window.
- Window level trees behaves slightly 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 one tree per window - instead of per tab.
- ------------------------------------------------------------------------------
- *NERDTreeIgnore*
- Values: a list of regular expressions.
- Default: ['\~$'].
- This setting is used to specify which files the NERDTree should ignore. It
- must be a list of regular expressions. When the NERDTree is rendered, any
- files/directories that match any of the regex's in NERDTreeIgnore won't 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.
- There are 3 magic flags that can be appended to the end of each regular
- expression to specify that the regex should match only filenames, only lowest
- level directories, or a full path. These flags are "[[dir]]", "[[file]]", and
- "[[path]]". Example: >
- let NERDTreeIgnore=['\.d$[[dir]]', '\.o$[[file]]', 'tmp/cache$[[path]]']
- <
- This will cause all directories ending in ".d" to be ignored, all files ending
- in ".o" to be ignored, and the "cache" subdirectory of any "tmp" directory to
- be ignored. All other "cache" directories will be displayed.
- When using the "[[path]]" tag on Windows, make sure you use escaped
- backslashes for the separators in the regex, eg. 'Temp\\cache$[[path]]'
- Note: to tell the NERDTree 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.
- ------------------------------------------------------------------------------
- *NERDTreeRespectWildIgnore*
- Values: 0 or 1.
- Default: 0.
- If set to 1, the `'wildignore'` setting is respected.
- ------------------------------------------------------------------------------
- *NERDTreeBookmarksFile*
- Values: a path
- Default: $HOME/.NERDTreeBookmarks
- This is where bookmarks are saved. See |NERDTreeBookmarkCommands|.
- ------------------------------------------------------------------------------
- *NERDTreeBookmarksSort*
- Values: 0, 1, or 2
- Default: 1
- This setting controls the method by which the list of user bookmarks is
- sorted. When sorted, bookmarks will render in alphabetical order by name.
- If set to 0, the bookmarks list is not sorted.
- If set to 1, the bookmarks list is sorted in a case-insensitive manner.
- If set to 2, the bookmarks list is sorted in a case-sensitive manner.
- ------------------------------------------------------------------------------
- *NERDTreeMarkBookmarks*
- Values: 0 or 1
- Default: 1
- If set to 1, Bookmarks will be specially marked whenever the NERDTree is
- rendered. Users of the |NERDTreeMinimalUI| setting may prefer to disable
- this setting for even less visual clutter.
- ------------------------------------------------------------------------------
- *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,1,2 or 3.
- Default: 0
- This setting governs whether the NERDTree window or the bookmarks table closes
- after opening a file with the |NERDTree-o|, |NERDTree-i|, |NERDTree-t| and
- |NERDTree-T| mappings.
- Value | NERDTree Window Behavior
- -------+-------------------------------------------------------
- 0 | No change
- 1 | Closes after opening a file
- 2 | Closes the bookmark table after opening a bookmark
- 3(1+2) | Same as both 1 and 2
- ------------------------------------------------------------------------------
- *NERDTreeShowBookmarks*
- Values: 0 or 1.
- Default: 0.
- If this setting is set to 1 then the bookmarks table will be displayed.
- This setting can be toggled dynamically, per tree, with the |NERDTree-B|
- mapping.
- ------------------------------------------------------------------------------
- *NERDTreeShowFiles*
- Values: 0 or 1.
- Default: 1.
- If this setting is set to 1 then files are displayed in the NERDTree. If it
- is set to 0 then only directories are displayed.
- This setting 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 setting tells vim whether to display hidden files by default. This
- setting can be dynamically toggled, per tree, with the |NERDTree-I| mapping.
- Use one of the follow lines for this setting: >
- let NERDTreeShowHidden=0
- let NERDTreeShowHidden=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeShowLineNumbers*
- Values: 0 or 1.
- Default: 0.
- This setting tells vim whether to display line numbers for the NERDTree
- window. Use one of the follow lines for this setting: >
- let NERDTreeShowLineNumbers=0
- let NERDTreeShowLineNumbers=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeSortOrder*
- Values: a list of regular expressions.
- Default: ['\/$', '*', '\.swp$', '\.bak$', '\~$']
- This setting is a list of regular expressions which are used to group or sort
- the nodes under their parent.
- For example, if the setting is: >
- ['\.vim$', '\.c$', '\.h$', '*', 'foobar']
- <
- then all .vim files will be grouped 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
- doesn't match any of the other regexps should be placed here.
- If no star is present in NERDTreeSortOrder, then one is automatically
- appended to the end of the list.
- The regex '\/$' should be used to match directory nodes.
- Files can also be sorted by 1) the modification timestamp, 2) the size, or 3)
- the extension. Directories are always sorted by name. To accomplish this, the
- following special flags are used:
- [[timestamp]] [[-timestamp]] [[size]] [[-size]] [[extension]]
- The hyphen specifies a descending sort; extensions are sorted in ascending
- order only. If placed at the beginning of the list, files are sorted according
- to these flags first, and then grouped by the remaining items in the list. If
- the flags are in any other position of the list, this special sorting is done
- secondarily. See examples 4, 5, and 6 below.
- After this sorting is done, the files in each group are sorted alphabetically.
- Examples: >
- (1) ['*', '\/$']
- (2) []
- (3) ['\/$', '\.rb$', '\.php$', '*', '\.swp$', '\.bak$', '\~$']
- (4) ['[[-size]]']
- (5) ['\/$', '*', '[[timestamp]]']
- (6) ['foo','\/$','[[extension]]']
- <
- 1. Directories will appear last, everything else will appear above.
- 2. Everything will simply appear in alphabetical order.
- 3. Directories will appear first, then ruby and php. Swap files, bak files
- and vim backup files will appear last with everything else preceding them.
- 4. Everything is sorted by size, largest to smallest, with directories
- considered to have size 0 bytes.
- 5. Directories will appear first alphabetically, followed by files, sorted by
- timestamp, oldest first.
- 6. Files and directories matching 'foo' first, followed by other directories,
- then all other files. Each section of files is sorted by file extension.
- ------------------------------------------------------------------------------
- *NERDTreeStatusline*
- Values: Any valid `'statusline'` setting.
- Default: %{exists('b:NERDTree')?b:NERDTree.root.path.str():''}
- Defines the value for the `'statusline'` setting in NERDTree windows.
- Note: The setting is actually applied using |:let-&|, not |:set|, so
- escaping spaces is not necessary.
- Setting this to -1 will deactivate it so that your global `'statusline'`
- setting is used.
- ------------------------------------------------------------------------------
- *NERDTreeWinPos*
- Values: "left" or "right"
- Default: "left".
- This setting is used to determine where NERDTree window is placed on the
- screen.
- This setting 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 NERDTree on the right.
- ------------------------------------------------------------------------------
- *NERDTreeWinSize*
- Values: a positive integer.
- Default: 31.
- This setting is used to change the size of the NERDTree when it is loaded.
- ------------------------------------------------------------------------------
- *NERDTreeMinimalUI*
- Values: 0 or 1
- Default: 0
- This setting disables the 'Bookmarks' label 'Press ? for help' text. Use one
- of the following lines for this setting: >
- let NERDTreeMinimalUI=0
- let NERDTreeMinimalUI=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeMinimalMenu*
- Values: 0 or 1
- Default: 0
- This setting makes NERDTree use a smaller, more compact menu for adding,
- copying, deleting nodes. This menu fits on a single line so Vim doesn't need to
- scroll down to present it. This setting is recommended for users already
- familiar with the menu items. It will look similar to this:
- Menu: [ (a)dd ,m,d,r,o,q,c,l] (Use j/k/enter or shortcut):
- An action can be selected with its shortcut key or with the NERDTreeMenuUp and
- NERDTreeMenuDown keys, then pressing enter.
- Use one of the following lines for this setting: >
- let NERDTreeMinimalMenu=0
- let NERDTreeMinimalMenu=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeCascadeSingleChildDir*
- Values: 0 or 1
- Default: 1.
- When displaying directory nodes, this setting tells NERDTree to collapse
- directories that have only one child. Use one of the following lines for this
- setting: >
- let NERDTreeCascadeSingleChildDir=0
- let NERDTreeCascadeSingleChildDir=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeCascadeOpenSingleChildDir*
- Values: 0 or 1
- Default: 1.
- When opening directory nodes, this setting tells NERDTree to recursively open
- directories that have only one child which is also a directory. NERDTree will
- stop when it finds a directory that contains anything but another single
- directory. This setting also causes the |NERDTree-x| mapping to close
- directories in the same manner. This setting may be useful for Java projects.
- Use one of the following lines for this setting: >
- let NERDTreeCascadeOpenSingleChildDir=0
- let NERDTreeCascadeOpenSingleChildDir=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeAutoDeleteBuffer*
- Values: 0 or 1
- Default: 0.
- When using a context menu to delete or rename a file you may also want to
- delete the buffer which is no more valid. If the setting is not set you will
- see a confirmation if you really want to delete an old buffer. If you always
- press 'y' then it's worth it to set this setting to 1. Use one of the
- following lines for this setting: >
- let NERDTreeAutoDeleteBuffer=0
- let NERDTreeAutoDeleteBuffer=1
- <
- ------------------------------------------------------------------------------
- *NERDTreeCreatePrefix*
- Values: Any valid command prefix.
- Default: "silent".
- Internally, NERDTree uses the |:edit| command to create a buffer in which to
- display its tree view. You can augment this behavior by specifying a prefix
- string such as "keepalt" or similar. For example, to have NERDTree create its
- tree window using `silent keepalt keepjumps edit`: >
- let NERDTreeCreatePrefix='silent keepalt keepjumps'
- <
- ------------------------------------------------------------------------------
- *NERDTreeDirArrowCollapsible* *NERDTreeDirArrowExpandable*
- Values: Any single character.
- Defaults: Windows: ~ and + Others: ▾ and ▸
- These characters indicate whether a directory is collapsible or expandable.
- Example: >
- let NERDTreeDirArrowExpandable=">"
- let NERDTreeDirArrowCollapsible="v"
- <
- They can be set to "\u00a0" to replace the arrows with a non-breaking space.
- If you do this you may need to change the node delimiter. See
- |NERDTreeNodeDelimiter|. You cannot use the same character for both the arrows
- and the delimiter.
- Alternatively, they can be set to '' (an empty string). This removes the
- arrows and the single space that follows them, shifting the entire tree two
- character positions to the left.
- ------------------------------------------------------------------------------
- *NERDTreeNodeDelimiter*
- Values: Any single character.
- Default: varies (see below)
- This character is used to separate the file or directory name from the rest of
- the characters in the line of text. It allows filenames to contain special
- characters that are otherwise used in the NERDTree, such as square brackets,
- braces, trailing asterisk, and leading space. For more details, see the
- responsible pull request: https://github.com/preservim/nerdtree/pull/868.
- The default value of this variable depends on the features compiled into your
- vim and the values of |NERDTreeDirArrowCollapsible| and
- |NERDTreeDirArrowExpandable|.
- * If your vim is compiled with the +conceal feature, it is the "\x07"
- (BEL) character, and it is hidden by setting 'conceallevel' to 2. If you
- use autocommands, make sure none of them change that setting in the
- NERD_Tree_* buffers.
- * If your vim does NOT have the +conceal feature and you're using "\u00a0"
- (non-breaking space) to hide the directory arrows, "\u00b7" (middle dot)
- is used as the default delimiter.
- * If neither condition above applies, NERDTree uses "\u00a0" (non-breaking
- space) as the default delimiter.
- In the 2nd and 3rd cases, NERDTree will use the Ignore highlight group to
- "hide" the delimiter. It should appear as an empty space.
- Other plugins can interfere with these defaults, so if you need to change the
- delimiter, be sure to choose a character that won't appear in your filenames
- or any of the flags set by your installed NERDTree plugins. The suggestions
- below are but a few of the many possibilities. Remember to use double quotes
- when specifying by hex or Unicode. >
- let NERDTreeNodeDelimiter="\x07" "bell
- let NERDTreeNodeDelimiter="\u00b7" "middle dot
- let NERDTreeNodeDelimiter="\u00a0" "non-breaking space
- let NERDTreeNodeDelimiter="😀" "smiley face
- <
- ------------------------------------------------------------------------------
- *NERDTreeCustomOpenArgs*
- Values: A nested dictionary, as described below
- Default: {'file': {'reuse': 'all', 'where': 'p'}, 'dir': {}}
- This dictionary contains two keys, 'file' and 'dir', whose values each are
- another dictionary. The inner dictionary is a set of parameters used by
- |NERDTree-<CR>| to open a file or directory. Setting these parameters allows you
- to customize the way the node is opened. The default value matches what
- |NERDTree-o| does. To change that behavior, use these keys and
- values in the inner dictionaries:
- 'where': specifies whether the node should be opened in a new split ("h" or
- "v"), in a new tab ("t") or, in the last window ("p").
- 'reuse': if file is already shown in a window, jump there; takes values
- "all", "currenttab", or empty
- 'keepopen': boolean (0 or 1); if true, the tree window will not be closed
- 'stay': boolean (0 or 1); if true, remain in tree window after opening
- For example:
- To open files and directories (creating a new NERDTree) in a new tab, >
- {'file':{'where': 't'}, 'dir':{'where':'t'}}
- <
- To open a file always in the current tab, and expand directories in place, >
- {'file': {'reuse':'currenttab', 'where':'p', 'keepopen':1, 'stay':1}}
- <
- ==============================================================================
- 4. The NERDTree API *NERDTreeAPI*
- The NERDTree 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
- A number of API functions take a callback argument to call. The callback can
- be either a string with the name of a function to call, or a |Funcref| object
- which will be called directly.
- ------------------------------------------------------------------------------
- 4.1. Key map API *NERDTreeKeymapAPI*
- NERDTreeAddKeyMap({options}) *NERDTreeAddKeyMap()*
- Adds a new keymapping for all NERDTree 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-?|)
- "override" - if 1 then this new mapping will override whatever previous
- mapping was defined for the key/scope combo. Useful for overriding the
- default mappings.
- Additionally, a "scope" argument may be supplied. This constrains the
- mapping so that it is only activated if the cursor is on a certain object.
- That object is then passed into the handling method. Possible values are:
- "FileNode" .... a file node
- "DirNode" ..... a directory node
- "Node" ........ a file node OR a directory node
- "Bookmark" .... a bookmark
- "all" ......... global scope; handler receives no arguments (default)
- Example: >
- call NERDTreeAddKeyMap({
- \ 'key': 'foo',
- \ 'callback': 'NERDTreeEchoPathHandler',
- \ 'quickhelpText': 'echo full path of current node',
- \ 'scope': 'DirNode' })
- function! NERDTreeEchoPathHandler(dirnode)
- echo a:dirnode.path.str()
- endfunction
- <
- This code should sit in a file like ~/.vim/nerdtree_plugin/mymapping.vim.
- It adds a (redundant) mapping on 'foo' which changes vim's CWD to that of
- the current directory node. Note this mapping will only fire when the
- cursor is on a directory 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 NERDTree 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.
- ------------------------------------------------------------------------------
- 4.3 NERDTreeAddPathFilter(callback) *NERDTreeAddPathFilter()*
- Path filters are essentially a more powerful version of |NERDTreeIgnore|.
- If the simple regex matching in |NERDTreeIgnore| is not enough then use
- |NERDTreeAddPathFilter()| to add a callback function that paths will be
- checked against when the decision to ignore them is made. Example >
- call NERDTreeAddPathFilter('MyFilter')
- function! MyFilter(params)
- "params is a dict containing keys: 'nerdtree' and 'path' which are
- "g:NERDTree and g:NERDTreePath objects
- "return 1 to ignore params['path'] or 0 otherwise
- endfunction
- <
- ------------------------------------------------------------------------------
- 4.4 Path Listener API *NERDTreePathListenerAPI*
- Use this API if you want to run a callback for events on Path objects. E.G >
- call g:NERDTreePathNotifier.AddListener("init", "MyListener")
- "....
- function! MyListener(event)
- "This function will be called whenever a Path object is created.
- "a:event is an object that contains a bunch of relevant info -
- "including the affected path. See lib/nerdtree/event.vim for details.
- endfunction
- <
- Current events supported:
- init ~
- refresh ~
- refreshFlags ~
- ------------------------------------------------------------------------------
- NERDTreeRender() *NERDTreeRender()*
- Re-renders the NERDTree 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 NERDTree 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 ;)
- Martyzilla recruited two other unwitting accomplices to become his minions in
- his quest to conquer the Vim plugin world. While he may still love to receive
- your emails, the best way to send suggestions, bug reports, and questions is
- to submit an issue at http://github.com/preservim/nerdtree/issues.
- The latest stable and development versions are on Github.
- Stable: http://github.com/preservim/nerdtree (master branch)
- Development: http://github.com/preservim/nerdtree/branches
- Title Credit:
- * http://ascii.co.uk/art/tree
- * Patrick Gillespie's Text ASCII Art Generator
- http://patorjk.com/software/taag
- http://patorjk.com/software/taag/#p=display&f=Rozzo&t=the%20NERD%20Tree
- ==============================================================================
- 6. License *NERDTreeLicense*
- The NERDTree is released under the wtfpl.
- See http://sam.zoy.org/wtfpl/COPYING.
- ------------------------------------------------------------------------------
- vim:tw=78:ts=8:ft=help:noet:nospell
|