🌿 fern.vim

General purpose asynchronous tree viewer written in Pure Vim script.

Split windows

Project drawer

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)
• Custamizability is less important than simplicity (maintainability)
• Easy to create 3rd party plugins to support any kind of trees

Installation

fern.vim has no extra dependencies so use your favorite Vim plugin manager or see How to install page for detail.

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.

:Fern {url} [-opener={opener}] [-reveal={reveal}] [-stay]

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 addtional to the all options available for split windows style, project drawer style enables the follwoing 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] [-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.

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 Wiki pages to find tips, or write pages to share your tips ;-)

Plugins

Fern supports the following types of plugins:

Type	Description
Renderer	Renderer is used to display a tree in a fern buffer. Changing it affect the visual looks of fern. e.g. lambdalisue/fern-renderer-devicons.vim
Comparator	Comparator is used to compare nodes. Changing it affect the order of nodes in a tree. e.g. lambdalisue/fern-comparator-lexical.vim
Mapping	Mapping is used to provide extra mappings. Adding it to provide extra mappings. e.g. lambdalisue/fern-mapping-project-top.vim
Scheme provider	Scheme provider is used to generate a tree from URI. Adding it to support extra scheme. e.g. lambdalisue/fern-bookmark.vim
Scheme mapping	Scheme mapping is used to provide scheme sepcific mappings. Adding it to provide extra scheme mappings. e.g. lambdalisue/fern-bookmark.vim

Please add a following badge to indicate that your plugin is for fern.

[![fern plugin](https://img.shields.io/badge/🌿%20fern-plugin-yellowgreen)](https://github.com/lambdalisue/fern.vim)

See Wiki pages to find more 3rd-party plugins or share yours ;-)

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 fern.vim follows MIT license texted in LICENSE. Contributors need to agree that any modifications sent in this repository follow the license.