🌿 vim-fern
Fern (furn) is a general purpose asynchronous tree viewer written in pure Vim script.
Concept
- Supports both Vim and Neovim without any external dependencies
- Support split windows and project drawer explained in
this article - Provide features as actions so that user don't have to remember mappings
- Make operation asynchronous as much as possible to keep latency
- User experience is more important than simplicity (maintainability)
- Customizability is less important than simplicity (maintainability)
- Easy to create 3rd party plugins to support any kind of trees
Installation
vim-fern has no extra dependencies so use your favorite Vim plugin manager or see How to install page for detail.
- If you use Neovim < 0.8, you SHOULD add
antoinemadec/FixCursorHold.nvim
(See #120)
Usage
Command (Split windows)
Open fern on a current working directory by:
:Fern .
Or open fern on a parent directory of a current buffer by:
:Fern %:h
Or open fern on a current working directory with a current buffer focused by:
:Fern . -reveal=%
The following options are available for fern viewer.
| Option | Default | Description |
|---|---|---|
-opener |
edit |
An opener to open the buffer. See :help fern-opener for detail. |
-reveal |
Recursively expand branches and focus the node. See :help fern-reveal for detail. |
|
-stay |
Stay focus on the window where the command has called. | |
-wait |
Wait synchronously until the fern viewer become ready. |
:Fern {url} [-opener={opener}] [-reveal={reveal}] [-stay] [-wait]
Command (Project drawer)
All usage above open fern as split windows style. To
open fern as project drawer style, use -drawer
option like:
:Fern . -drawer
A fern window with project drawer style always appeared to the most left side of Vim and behaviors of some mappings/actions are slightly modified (e.g. a buffer in the next window will be used as an anchor buffer in a project drawer style to open a new buffer.)
Note that additional to the all options available for split windows style, project drawer style enables the following options:
| Option | Default | Description |
|---|---|---|
-width |
30 |
The width of the project drawer window |
-keep |
Disable to quit Vim when there is only one project drawer buffer | |
-toggle |
Close existing project drawer rather than focus |
:Fern {url} -drawer [-opener={opener}] [-reveal={reveal}] [-stay] [-wait] [-width=30] [-keep] [-toggle]
Actions
To execute actions, hit a on a fern buffer and input an action to perform. To
see all actions available, hit ? or execute help action then all available
actions will be listed.
Window selector
The open:select action open a prompt to visually select window to open a node.
This feature is strongly inspired by t9md/vim-choosewin.
Renamer action (A.k.a exrename)
The rename action open a new buffer with path of selected nodes. Users can
edit that buffer and :w applies the changes. This feature is strongly inspired
by shougo/vimfiler.vim.
Plugins
Users
Most of functionalities are provided as plugins in fern. So visit
Github topics of fern-vim-plugin
or Plugins page to find
fern plugins to satisfy your wants.
For example, following features are provided as official plugins
- Netrw hijack (Use fern as a default file explorer)
- Nerd Fonts integration
- Git integration (show status, touch index, ...)
- Bookmark feature
And lot more!
Developers
Please add fern-vim-plugin topic to your fern plugin. The topic is used to
list up 3rd party fern plugins.
Then please add a following badge to indicate that your plugin is for fern.
[](https://github.com/lambdalisue/vim-fern)
Customize
Use FileType fern autocmd to execute initialization scripts for fern buffer
like:
function! s:init_fern() abort
" Use 'select' instead of 'edit' for default 'open' action
nmap <buffer> <Plug>(fern-action-open) <Plug>(fern-action-open:select)
endfunction
augroup fern-custom
autocmd! *
autocmd FileType fern call s:init_fern()
augroup END
The FileType autocmd will be invoked AFTER a fern buffer has initialized but
BEFORE contents of a buffer become ready. So avoid accessing actual contents in
the above function.
See Tips pages to find tips, or write pages to share your tips ;-)
Contribution
Any contribution including documentations are welcome.
Contributors who change codes should install thinca/vim-themis to run tests before complete a PR. PRs which does not pass tests won't be accepted.
License
The code in vim-fern follows MIT license texted in LICENSE. Contributors need to agree that any modifications sent in this repository follow the license.
