README.md

🌿 fern.vim

General purpose asynchronous tree viewer written in Pure Vim script.

WARNING: This project is in beta stage. Any changes are applied without announcements.

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. Available value is one of select, edit, split, vsplit, tabedit, or those values with modifiers (e.g. topleft vsplit) -reveal

Recursively expand branches and focus the node. It must be a relative path from the root node of the tree. Otherwise the value is ignored.

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

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}] [-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.

Mappings

The following mappings/actions are available among any fern buffer

Mapping Action Description a

Open a prompt to input an action name to perform .

Repeat previous action invoked from a prompt ? help Output mappings/actions to a pseudo buffer as help <C-c> cancel Cancel any operation under processing <C-l> redraw Redraw content of the buffer

debug Show a debug informatin of a node under the cursor <F5> reload Reload node itself and descendent nodes of a node under the cursor

expand Expand (open) a node under the cursor h collapse Collapse (close) a node under the cursor i reveal Reveal (recursively focus and expand) a node which input by user

enter Enter a new tree which root node is a node under the cursor <BS>, <C-h> leave Leave to a new tree which root is the parent node of a current root node s open:select Select window to open a node under the cursor (like t9md/vim-choosewin) e open An alias of open:edit action E open:side Open a node under the cursor on right side of the fern buffer

open:edit Open a node under the cursor with edit

open:split Open a node under the cursor with split

open:vsplit Open a node under the cursor with vsplit t open:tabedit Open a node under the cursor with tabedit

open:above Open a node under the cursor with leftabove split

open:left Open a node under the cursor with leftabove vsplit

open:below Open a node under the cursor with rightbelow split

open:right Open a node under the cursor with rightbelow vsplit

open:top Open a node under the cursor with topleft split

open:leftest Open a node under the cursor with topleft vsplit

open:bottom Open a node under the cursor with botright split

open:rightest Open a node under the cursor with botright vsplit <Return>, <C-m>

Invoke open whe a node under the cursor is leaf. Otherwise invoke enter l

Invoke open whe a node under the cursor is leaf. Otherwise invoke expand z zoom An alias of zoom:half action

zoom:half Temporary increase the width of a project drawer. It does nothing on split windows

zoom:full Temporary increase the width of a project drawer. It does nothing on split windows

And the following mappings/actions are available in builtin file scheme

Mapping Action Description

cd Chnage directory to the root node of the tree with cd command

lcd Chnage directory to the root node of the tree with lcd command

tcd Chnage directory to the root node of the tree with tcd command x open:system Open a node under the cursor with a system program N new-file Create a new file under a node under the cursor K new-dir Create a new directory under a node under the cursor c copy Copy files/directories of selected nodes to new locations sequentially m move Move files/directories of selected nodes to new locations sequentially C clipboard-copy Save files/directories of selected nodes to the internal clipboard to copy M clipboard-move Save files/directories of selected nodes to the internal clipboard to move P clipboard-pate Paste files/directories to a node under the cursor from the internal clipboard

clipboard-clear Clear the internal clipboard D trash Move files/directries of selected nodes to the system trash-bin

remove Remove files/directries of selected nodes R rename Start renamer to rename multiple files/directories by using Vim buffer (like exrename in Shougo/vimfiler.vim)

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.

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 ;-)

Plugins

The fern.vim supports 3rd party plugin system for scheme and mappings. See Plugins pages to find 3rd party plugins of fern.vim.

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.