mirror of
https://github.com/preservim/nerdtree.git
synced 2024-10-18 13:50:21 +03:00
Revamp the README file (#1193)
* Revamp the README to improve clarity and provide more information. * Verify correct behavior of suggested auto commands. * Add my tribute to Norm Abrams. Be careful with those plugin managers. * Other minor formatting and cleanup. * Fix typos, reorder some sections, and tidy up the README. * Give a better answer to the single NERDTree for all tabs question. * More reformatting of text. * Add basic installation instructions. Switch to single quotes. * Update version number in CHANGELOG.
This commit is contained in:
Phil Runninger
GitHub
parent
474d735b7d
commit
2406c456ee
@ -5,6 +5,7 @@
|
||||
- **.PATCH**: Pull Request Title (PR Author) [PR Number](Link to PR)
|
||||
-->
|
||||
#### 6.9
|
||||
- **.11**: Revamp the README. (buncis, PhilRunninger) [#1192](https://github.com/preservim/nerdtree/pull/1192), [#1193](https://github.com/preservim/nerdtree/pull/1193)
|
||||
- **.10**: Open a mirrored NERDTree with correct width (PhilRunninger) [#1177](https://github.com/preservim/nerdtree/pull/1177)
|
||||
- **.9**: Updated Readme, removed typo (H3RSKO) [#1167](https://github.com/preservim/nerdtree/pull/1167)
|
||||
- **.8**: Refactor sort comparison functions, removing redundancy (PhilRunninger) [#1166](https://github.com/preservim/nerdtree/pull/1166)
|
||||
|
||||
240
README.markdown
240
README.markdown
@ -1,171 +1,173 @@
|
||||
The NERDTree [](https://github.com/preservim/nerdtree/actions?workflow=Vint)
|
||||
=============
|
||||
# The NERDTree [](https://github.com/preservim/nerdtree/actions?workflow=Vint)
|
||||
|
||||
Introduction
|
||||
------------
|
||||
## Introduction
|
||||
|
||||
The NERDTree is a file system explorer for the Vim editor. Using this plugin,
|
||||
users can visually browse complex directory hierarchies, quickly open files for
|
||||
reading or editing, and perform basic file system operations.
|
||||
|
||||
This plugin can also be extended with custom mappings using a special API. The
|
||||
details of this API and of other NERDTree features are described in the
|
||||
included documentation.
|
||||
The NERDTree is a file system explorer for the Vim editor. Using this plugin, users can visually browse complex directory hierarchies, quickly open files for reading or editing, and perform basic file system operations.
|
||||
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
## Installation
|
||||
|
||||
Below are just some of the methods for installing NERDTree. Do not follow all of these instructions; just pick your favorite one. Other plugin managers exist, and NERDTree should install just fine with any of them.
|
||||
Use your favorite plugin manager to install this plugin. [tpope/vim-pathogen](https://github.com/tpope/vim-pathogen), [VundleVimVundle.vim](https://github.com/VundleVim/Vundle.vim), [junegunnvim-plug](https://github.com/junegunn/vim-plug), and [Shougo/dein.vim](https://github.com/Shougo/dein.vim) are some of the more popular ones. A lengthy discussion of these and other managers can be found on [vi.stackexchange.com](https://vi.stackexchange.com/questions/388/what-is-the-difference-between-the-vim-plugin-managers). Basic instructions are provided below, but please **be sure to read, understand, and follow all the safety rules that come with your ~~power tools~~ plugin manager.**
|
||||
|
||||
#### Vim 8+ packages
|
||||
If you have no favorite, or want to manage your plugins without 3rd-party dependencies, consider using Vim 8+ packages, as described in Greg Hurrell's excellent Youtube video: [Vim screencast #75: Plugin managers](https://www.youtube.com/watch?v=X2_R3uxDN6g).
|
||||
|
||||
If you are using VIM version 8 or higher you can use its built-in package management; see `:help packages` for more information. Just run these commands in your terminal:
|
||||
<details>
|
||||
<summary>Pathogen</summary>
|
||||
Pathogen is more of a runtime path manager than a plugin manager. You must clone the plugins' repositories yourself to a specific location, and Pathogen makes sure they are available in Vim.
|
||||
|
||||
|
||||
1. In the terminal,
|
||||
```bash
|
||||
git clone https://github.com/preservim/nerdtree.git ~/.vim/bundle/nerdtree
|
||||
```
|
||||
1. In your `vimrc`,
|
||||
```vim
|
||||
call pathogen#infect()
|
||||
syntax on
|
||||
filetype plugin indent on
|
||||
```
|
||||
1. Restart Vim, and run `:helptags ~/.vim/bundle/nerdtree/doc/` or `:Helptags`.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Vundle</summary>
|
||||
|
||||
1. Install Vundle, according to its instructions.
|
||||
1. Add the following text to your `vimrc`.
|
||||
```vim
|
||||
call vundle#begin()
|
||||
Plugin 'preservim/nerdtree'
|
||||
call vundle#end()
|
||||
```
|
||||
1. Restart Vim, and run the `:PluginInstall` statement to install your plugins.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Vim-Plug</summary>
|
||||
|
||||
1. Install Vim-Plug, according to its instructions.
|
||||
1. Add the following text to your `vimrc`.
|
||||
```vim
|
||||
call plug#begin()
|
||||
Plug 'preservim/nerdtree'
|
||||
call plug#end()
|
||||
```
|
||||
1. Restart Vim, and run the `:PlugInstall` statement to install your plugins.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Dein</summary>
|
||||
|
||||
1. Install Dein, according to its instructions.
|
||||
1. Add the following text to your `vimrc`.
|
||||
```vim
|
||||
call dein#begin()
|
||||
call dein#add('preservim/nerdtree')
|
||||
call dein#end()
|
||||
```
|
||||
1. Restart Vim, and run the `:call dein#install()` statement to install your plugins.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Vim 8+ packages</summary>
|
||||
|
||||
If you are using Vim version 8 or higher you can use its built-in package management; see `:help packages` for more information. Just run these commands in your terminal:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/preservim/nerdtree.git ~/.vim/pack/vendor/start/nerdtree
|
||||
vim -u NONE -c "helptags ~/.vim/pack/vendor/start/nerdtree/doc" -c q
|
||||
```
|
||||
</details>
|
||||
|
||||
Otherwise, these are some of the several 3rd-party plugin managers you can choose from. Be sure you read the instructions for your chosen plugin, as there typically are additional steps you need to take.
|
||||
## Getting Started
|
||||
After installing NERDTree, the best way to learn it is to turn on the Quick Help. Open NERDTree with the `:NERDTree` command, and press `?` to turn on the Quick Help, which will show you all the mappings and commands available in the NERDTree. Of course, your most complete source of information is the documentation: `:help NERDTree`.
|
||||
|
||||
#### [pathogen.vim](https://github.com/tpope/vim-pathogen)
|
||||
## NERDTree Plugins
|
||||
NERDTree can be extended with custom mappings and functions using its built-in API. The details of this API and are described in the included documentation. Several plugins have been written, and are available on Github for installation like any other plugin. The plugins in this list are maintained (or not) by their respective owners, and certain combinations may be incompatible.
|
||||
|
||||
In the terminal,
|
||||
```bash
|
||||
git clone https://github.com/preservim/nerdtree.git ~/.vim/bundle/nerdtree
|
||||
```
|
||||
In your vimrc,
|
||||
* [Xuyuanp/nerdtree-git-plugin](https://github.com/Xuyuanp/nerdtree-git-plugin): Shows Git status flags for files and folders in NERDTree.
|
||||
* [ryanoasis/vim-devicons](https://github.com/ryanoasis/vim-devicons): Adds filetype-specific icons to NERDTree files and folders,
|
||||
* [tiagofumo/vim-nerdtree-syntax-highlight](https://github.com/tiagofumo/vim-nerdtree-syntax-highlight): Adds syntax highlighting to NERDTree based on filetype.
|
||||
* [scrooloose/nerdtree-project-plugin](https://github.com/scrooloose/nerdtree-project-plugin): Saves and restores the state of the NERDTree between sessions.
|
||||
* [PhilRunninger/nerdtree-buffer-ops](https://github.com/PhilRunninger/nerdtree-buffer-ops): 1) Highlights open files in a different color. 2) Closes a buffer directly from NERDTree.
|
||||
* [PhilRunninger/nerdtree-visual-selection](https://github.com/PhilRunninger/nerdtree-visual-selection): Enables NERDTree to open, delete, move, or copy multiple Visually-selected files at once.
|
||||
|
||||
If any others should be listed, mention them in an issue or pull request.
|
||||
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
In the answers to these questions, you will see code blocks that you can put in your `vimrc` file.
|
||||
|
||||
### How can I map a specific key or shortcut to open NERDTree?
|
||||
|
||||
NERDTree doesn't create any shortcuts outside of the NERDTree window, so as not to overwrite any of your other shortcuts. Use the `nnoremap` command in your `vimrc`. You, of course, have many keys and NERDTree commands to choose from. Here are but a few examples.
|
||||
```vim
|
||||
call pathogen#infect()
|
||||
syntax on
|
||||
filetype plugin indent on
|
||||
nnoremap <leader>n :NERDTreeFocus<CR>
|
||||
nnoremap <C-n> :NERDTree<CR>
|
||||
nnoremap <C-t> :NERDTreeToggle<CR>
|
||||
nnoremap <C-f> :NERDTreeFind<CR>
|
||||
```
|
||||
|
||||
Then reload vim, run `:helptags ~/.vim/bundle/nerdtree/doc/` or `:Helptags`.
|
||||
### How do I open NERDTree automatically when Vim starts?
|
||||
Each code block below is slightly different, as described in the `" Comment lines`.
|
||||
|
||||
#### [Vundle.vim](https://github.com/VundleVim/Vundle.vim)
|
||||
```vim
|
||||
call vundle#begin()
|
||||
Plugin 'preservim/nerdtree'
|
||||
call vundle#end()
|
||||
" Start NERDTree and leave the cursor in it.
|
||||
autocmd VimEnter * NERDTree
|
||||
```
|
||||
|
||||
#### [vim-plug](https://github.com/junegunn/vim-plug)
|
||||
```vim
|
||||
call plug#begin()
|
||||
Plug 'preservim/nerdtree'
|
||||
call plug#end()
|
||||
```
|
||||
|
||||
#### [dein.vim](https://github.com/Shougo/dein.vim)
|
||||
```vim
|
||||
call dein#begin()
|
||||
call dein#add('preservim/nerdtree')
|
||||
call dein#end()
|
||||
```
|
||||
|
||||
#### [apt-vim](https://github.com/egalpin/apt-vim)
|
||||
```bash
|
||||
apt-vim install -y https://github.com/preservim/nerdtree.git
|
||||
```
|
||||
|
||||
F.A.Q. (here, and in the [Wiki](https://github.com/preservim/nerdtree/wiki))
|
||||
------
|
||||
|
||||
#### Is there any support for `git` flags?
|
||||
|
||||
Yes, install [nerdtree-git-plugin](https://github.com/Xuyuanp/nerdtree-git-plugin).
|
||||
|
||||
---
|
||||
#### Can I have the nerdtree on every tab automatically?
|
||||
|
||||
Nope. If this is something you want then chances are you aren't using tabs and
|
||||
buffers as they were intended to be used. Read this
|
||||
http://stackoverflow.com/questions/102384/using-vims-tabs-like-buffers
|
||||
|
||||
If you are interested in this behaviour then consider [vim-nerdtree-tabs](https://github.com/jistr/vim-nerdtree-tabs)
|
||||
|
||||
---
|
||||
#### How can I open a NERDTree automatically when vim starts up?
|
||||
|
||||
Stick this in your vimrc: `autocmd vimenter * NERDTree`
|
||||
|
||||
---
|
||||
#### How can I open a NERDTree automatically when vim starts up and autofocus on file?
|
||||
|
||||
Stick this in your vimrc: `autocmd vimenter * NERDTree | wincmd p`
|
||||
|
||||
---
|
||||
#### How can I open a NERDTree automatically when vim starts up if no files were specified?
|
||||
|
||||
Stick this in your vimrc:
|
||||
```vim
|
||||
" Start NERDTree and put the cursor back in the other window.
|
||||
autocmd VimEnter * NERDTree | wincmd p
|
||||
```
|
||||
---
|
||||
```vim
|
||||
" Start NERDTree when Vim is started without file arguments.
|
||||
autocmd StdinReadPre * let s:std_in=1
|
||||
autocmd VimEnter * if argc() == 0 && !exists("s:std_in") | NERDTree | endif
|
||||
autocmd VimEnter * if argc() == 0 && !exists('s:std_in') | NERDTree | endif
|
||||
```
|
||||
|
||||
Note: Now start vim with plain `vim`, not `vim .`
|
||||
|
||||
---
|
||||
#### How to autofocus on file and focus on NERDTREE when no files were specified?
|
||||
|
||||
Stick this in your vimrc:
|
||||
```vim
|
||||
" Start NERDTree. If a file is specified, move the cursor to its window.
|
||||
autocmd StdinReadPre * let s:std_in=1
|
||||
autocmd VimEnter * if argc() == 0 && !exists("s:std_in") | NERDTree | else | NERDTree | wincmd p | endif
|
||||
autocmd VimEnter * NERDTree | if argc() > 0 || exists("s:std_in") | wincmd p | endif
|
||||
```
|
||||
|
||||
---
|
||||
#### What if I'm also opening a saved session, for example `vim -S session_file.vim`? I don't want NERDTree to open in that scenario.
|
||||
```vim
|
||||
" Start NERDTree, unless a file or session is specified, eg. vim -S session_file.vim.
|
||||
autocmd StdinReadPre * let s:std_in=1
|
||||
autocmd VimEnter * if argc() == 0 && !exists("s:std_in") && v:this_session == "" | NERDTree | endif
|
||||
autocmd VimEnter * if argc() == 0 && !exists('s:std_in') && v:this_session == '' | NERDTree | endif
|
||||
```
|
||||
|
||||
---
|
||||
#### How can I open NERDTree automatically when vim starts up on opening a directory?
|
||||
```vim
|
||||
" Start NERDTree when Vim starts with a directory argument.
|
||||
autocmd StdinReadPre * let s:std_in=1
|
||||
autocmd VimEnter * if argc() == 1 && isdirectory(argv()[0]) && !exists("s:std_in") | exe 'NERDTree' argv()[0] | wincmd p | ene | exe 'cd '.argv()[0] | endif
|
||||
autocmd VimEnter * if argc() == 1 && isdirectory(argv()[0]) && !exists('s:std_in') |
|
||||
\ execute 'NERDTree' argv()[0] | wincmd p | enew | execute 'cd '.argv()[0] | endif
|
||||
```
|
||||
|
||||
This window is tab-specific, meaning it's used by all windows in the tab. This trick also prevents NERDTree from hiding when first selecting a file.
|
||||
### How can I close Vim automatically when NERDTree is the last window?
|
||||
|
||||
Note: Executing `vim ~/some-directory` will open NERDTree and a new edit window. `exe 'cd '.argv()[0]` sets the `pwd` of the new edit window to `~/some-directory`
|
||||
|
||||
---
|
||||
#### How can I map a specific key or shortcut to open NERDTree?
|
||||
|
||||
Stick this in your vimrc to open NERDTree with `Ctrl+n` (you can set whatever key you want):
|
||||
```vim
|
||||
map <C-n> :NERDTreeToggle<CR>
|
||||
" Exit Vim if NERDTree is the only window left.
|
||||
autocmd BufEnter * if tabpagenr('$') == 1 && winnr('$') == 1 && exists('b:NERDTree') && b:NERDTree.isTabTree() |
|
||||
\ quit | endif
|
||||
```
|
||||
|
||||
---
|
||||
#### How can I close vim if the only window left open is a NERDTree?
|
||||
### Can I have the same NERDTree on every tab automatically?
|
||||
|
||||
Stick this in your vimrc:
|
||||
```vim
|
||||
autocmd bufenter * if (winnr("$") == 1 && exists("b:NERDTree") && b:NERDTree.isTabTree()) | q | endif
|
||||
" Open the existing NERDTree on each new tab.
|
||||
autocmd BufWinEnter * silent NERDTreeMirror
|
||||
```
|
||||
|
||||
---
|
||||
#### Can I have different highlighting for different file extensions?
|
||||
### How can I change the default arrows?
|
||||
|
||||
See here: https://github.com/preservim/nerdtree/issues/433#issuecomment-92590696
|
||||
|
||||
---
|
||||
#### How can I change default arrows?
|
||||
|
||||
Use these variables in your vimrc. Note that below are default arrow symbols
|
||||
```vim
|
||||
let g:NERDTreeDirArrowExpandable = '▸'
|
||||
let g:NERDTreeDirArrowCollapsible = '▾'
|
||||
```
|
||||
You can remove the arrows altogether by setting these variables to empty strings, as shown below. This will remove not only the arrows, but a single space following them, shifting the whole tree two character positions to the left.
|
||||
```vim
|
||||
let g:NERDTreeDirArrowExpandable = ''
|
||||
let g:NERDTreeDirArrowCollapsible = ''
|
||||
```
|
||||
The preceding values are the non-Windows default arrow symbols. Setting these variables to empty strings will remove the arrows completely and shift the entire tree two character positions to the left. See `:h NERDTreeDirArrowExpandable` for more details.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user