mirror of
https://github.com/preservim/nerdtree.git
synced 2024-11-26 02:10:12 +08:00
5e77fb2fef
* Fix example code for the NERDTreeAddKeyMap function. The quickhelpText didn't match what the statement in the callback function actually did. * Update version number in change log.
1529 lines
65 KiB
Plaintext
1529 lines
65 KiB
Plaintext
*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 dir 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|
|
|
Open selected bookmark dir 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 dir.......................................|NERDTree-e|
|
|
|
|
double-click....same as |NERDTree-o|.
|
|
middle-click....same as |NERDTree-i| for files, and |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 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 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 NERDTree menu..................................|NERDTree-m|
|
|
cd.......Change the CWD to the dir 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, that directory is found
|
|
in the current NERDTree. If the directory couldn't be found, a new NERDTree is
|
|
created.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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 dir 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 dir 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 dir (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 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 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 dirs. 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/dirs 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 2 magic flags that can be appended to the end of each regular
|
|
expression to specify that the regex should match only files or only dirs.
|
|
These flags are "[[dir]]" and "[[file]]". Example: >
|
|
let NERDTreeIgnore=['\.d$[[dir]]', '\.o$[[file]]']
|
|
<
|
|
This will cause all dirs ending in ".d" to be ignored and all files ending in
|
|
".o" to be ignored.
|
|
|
|
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. Dirs 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 dir nodes, this setting tells NERDTree to collapse dirs 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 dir nodes, this setting tells NERDTree to recursively open dirs
|
|
that have only one child which is also a dir. NERDTree will stop when it finds
|
|
a dir that contains anything but another single dir. This setting also causes
|
|
the |NERDTree-x| mapping to close dirs 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" (BELL)
|
|
character, and it is hidden by setting 'conceallevel' to 3. If you use
|
|
autocommands, make sure none of them change that setting in the NERDTree_*
|
|
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 dir 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
|