coc-explorer

Explorer extension for coc.nvim

Note: This project is still under development and may be broken.

Screenshot

Requirements

>= vim 8.1.1418 or >= neovim 0.3.1

Usage

1. Install by coc.nvim command:

   :CocInstall coc-explorer

2. Configuration custom vim mapping

   :nmap <space>e <Cmd>CocCommand explorer<CR>

3. Open explorer

   <space>e

4. Press ? to show mappings help

More at Quickstart

Feature

• [x] Buffer source
  • [x] Highlight visible buffers in real time
• [x] File tree source
  • [x] Basic actions
    • [x] Open file in select / vsplit / tab explorer.openAction.strategy options:
      • select: Open action use selection UI
      • vsplit: Open action use vsplit
      • split: Open action use split
      • tab: Open action use tab
      • previousBuffer: Open action use last used buffer
      • previousWindow: Open action use last used window
      • sourceWindow: Open action use the window where explorer opened
    • [x] Selection
    • [x] Cut / Copy / Paste
    • [x] Delete action use trash by default
    • [x] Other actions, press ? in explorer to check out the all actions
  • [x] Git status
  • [x] Automatically reveal the current file
  • [x] Icons, use nerdfont
  • [x] Search files by Coc-list
  • [x] Preview file attributes by floating window
  • [ ] LSP
    • [x] diagnostic
    • [ ] file rename (won't support, use watchman)
  • [ ] Exrename, like defx
  • [ ] Archive file (use lsar / unar)
  • [ ] SSH
• [x] ~~Bookmark source (DEPRECATED) (require coc-bookmark)~~
• [ ] Git source
  • [ ] Git actions
• [x] Show help

Command

:CocCommand explorer [options] [root-uri]

User events

• CocExplorerOpenPre: triggered before open explorer
• CocExplorerOpenPost: triggered after open explorer
• CocExplorerQuitPre: triggered before quit explorer
• CocExplorerQuitPost: triggered after quit explorer

Example

:CocCommand explorer
    \ --toggle
    \ --sources=buffer+,file+
    \ /root/path

Reveal to current buffer for closest coc-explorer

nmap <Leader>er <Cmd>call CocAction('runCommand', 'explorer.doAction', 'closest', ['reveal:0'], [['relative', 0, 'file']])<CR>

Presets

let g:coc_explorer_global_presets = {
\   '.vim': {
\     'root-uri': '~/.vim',
\   },
\   'cocConfig': {
\      'root-uri': '~/.config/coc',
\   },
\   'tab': {
\     'position': 'tab',
\     'quit-on-open': v:true,
\   },
\   'tab:$': {
\     'position': 'tab:$',
\     'quit-on-open': v:true,
\   },
\   'floating': {
\     'position': 'floating',
\     'open-action-strategy': 'sourceWindow',
\   },
\   'floatingTop': {
\     'position': 'floating',
\     'floating-position': 'center-top',
\     'open-action-strategy': 'sourceWindow',
\   },
\   'floatingLeftside': {
\     'position': 'floating',
\     'floating-position': 'left-center',
\     'floating-width': 50,
\     'open-action-strategy': 'sourceWindow',
\   },
\   'floatingRightside': {
\     'position': 'floating',
\     'floating-position': 'right-center',
\     'floating-width': 50,
\     'open-action-strategy': 'sourceWindow',
\   },
\   'simplify': {
\     'file-child-template': '[selection | clip | 1] [indent][icon | 1] [filename omitCenter 1]'
\   },
\   'buffer': {
\     'sources': [{'name': 'buffer', 'expand': v:true}]
\   },
\ }

" Use preset argument to open it
nmap <space>ed <Cmd>CocCommand explorer --preset .vim<CR>
nmap <space>ef <Cmd>CocCommand explorer --preset floating<CR>
nmap <space>ec <Cmd>CocCommand explorer --preset cocConfig<CR>
nmap <space>eb <Cmd>CocCommand explorer --preset buffer<CR>

" List all presets
nmap <space>el <Cmd>CocList explPresets<CR>

Options

[root-uri]

Explorer root, default is use root-strategies

--root-strategies <root-strategies>

Strategies for root uri, types list of (keep | workspace | cwd | sourceBuffer | reveal | custom:name)

• keep: never change the root path
• workspace: workspace.root
• cwd: getcwd()
• sourceBuffer: directory of buffer
• reveal: directory of reveal path

default is: workspace,cwd,sourceBuffer,reveal or "explorer.root.strategies" of coc-settings

Custom root patterns settings

{
  "explorer.root.customRules": {
    "vcs": {
      "patterns": [".git", ".hg", ".projections.json"],
    },
    "vcs-r": {
      "patterns": [".git", ".hg", ".projections.json"],
      "bottomUp": true,
    },
  },
}

Using custom root patterns

{
  "explorer.root.strategies": ["workspace", "custom:vcs", "custom:vcs-r"],
}

or :CocCommand explorer --root-strategies workspace,custom:vcs,custom:vcs-r

--preset <name>

Open explorer use presets

--toggle | --no-toggle

Close the explorer if it exists, default: --toggle

--focus | --no-focus

Focus to explorer when opened, default: --focus

--open-action-strategy <strategy>

Strategy for open action, types: select | vsplit | split | tab | previousBuffer | previousWindow | sourceWindow, default: select

--quit-on-open | --no-quit-on-open

quit explorer when open action, default: --no-quit-on-open

--sources <sources>

Explorer sources, example: buffer+,file+, default: buffer-,file+

              expand
      collapsed │
          ↓     ↓
    buffer-,file+
    └──┬─┘  └─┬┘
buffer source │
          file source

--position <position>

Explorer position, supported position: left, right, tab, tab:0, tab:$, floating, default: left

--width <number>

Width of Explorer window for open in left or right side, default: 40

--content-width <number>

Content width, default: 0

--content-width-type <type>

Type of content width, types: win-width, vim-width, , default: vim-width

--floating-position <position>

Explorer position for floating window, positions:

• left-center
• center
• right-center
• center-top
• <number for left>,<number for top>

default: center

--floating-width <number>

Width of Explorer window when position is floating, use negative value or zero to as width - value, default: 0

--floating-height <number>

Height of Explorer window when position is floating, use negative value or zero to as height - value, default: 0

--floating-content-width <number>

Width of content when position is floating, use negative value or zero to as width - value, default: 0

--buffer-root-template <template>

Template for root node of buffer source

Columns:

• icon
• hidden
• title

default: [icon] [title] [hidden & 1]

--buffer-child-template <template>

Template for child node of buffer source

Columns:

• selection
• name
• bufname
• modified
• bufnr
• readonly
• fullpath
• relativePath

default: [selection | 1] [bufnr] [name][modified][readonly] [fullpath]

--buffer-child-labeling-template <template>

Labeling template for child node of buffer source, use for preview when previewAction is labeling

Columns: same with --buffer-child-template

default: [name][bufname][fullpath][modified][readonly]

--file-root-template <template>

Template for root node of file source

Columns:

• icon
• hidden
• title
• root
• fullpath

default: [icon] [title] [hidden & 1][root] [fullpath]

--file-root-labeling-template <template>

Labeling template for root node of file source, use for preview when previewAction is labeling

Columns: same with --file-root-template

default: [fullpath]

--file-child-template <template>

Template for child node file source

Columns:

• git
• selection
• icon
• filename
• linkIcon
• link
• fullpath
• indent
• clip
• size
• readonly
• modified
• timeModified
• timeCreated
• timeAccessed
• diagnosticError
• diagnosticWarning

default: [git | 2] [selection | clip | 1] [indent][icon | 1] [diagnosticError & 1][filename omitCenter 1][modified][readonly] [linkIcon & 1][link growRight 1 omitCenter 5][size]

--file-child-labeling-template <template>

Labeling template for child node of file source, use for preview when previewAction is labeling

Columns: same with --file-child-template

default: [fullpath][link][diagnosticWarning][diagnosticError][size][timeAccessed][timeModified][timeCreated][readonly][modified]

--bookmark-root-template <template>

Template for root node of bookmark source

Columns:

• icon
• hidden
• title

default: [icon] [title] [hidden & 1]

--bookmark-child-template <template>

Template for child node of bookmark source

Columns:

• selection
• position
• filename
• fullpath
• line
• annotation

default: [selection | 1] [filename] [position]

--bookmark-child-labeling-template <template>

Labeling template for child node of bookmark source, use for preview when previewAction is labeling

Columns: same with --bookmark-child-template

default: [filename][fullpath][position][line][annotation]

--reveal <filepath>

Explorer will expand to this filepath, default: current buffer

--reveal-when-open | --no-reveal-when-open

Explorer will automatically reveal to the current buffer when open explorer, default: "explorer.file.reveal.whenOpen"

Template grammar

Example:

[git | 2] [selection | clip | 1] [diagnosticError & 1][filename growRight 1 omitCenter 5]

• [git]
  • Display git.
• [git | 2]
  • If git is not empty, display git, otherwise display 2 spaces.
• [selection | clip | 1]
  • Checking selection and clip in turn, if one is not empty, display it, otherwise display 1 spaces.
• [diagnosticError & 1]
  • If diagnosticError is empty, display nothing. otherwise display diagnosticError and 1 space.
• [filename growRight 1 omitCenter 5]
  • Flexible to display filename, grow right column volume is 1, omit center volume is 5

Grammar:

                      block
         ┌──────────────┴───────────────┐
┌────────┴───────────┐ ┌────────────────┴────────────────┐
[selection | clip | 1] [filename growRight 1 omitCenter 5]
                      ↑
                 plain string

            column
     ┌─────────┴───────────┐
     │                     │   volume of modifier
     │         ┌────┬──────│──────────┴────┬────────────┐
 ┌───┴───┐   ┌─┴┐   ↓   ┌──┴───┐           ↓            ↓
[selection | clip | 1] [filename growRight 1 omitCenter 5]
           ↑      ↑              └───┬───┘   └────┬───┘
           └──────┴───────────┬──────┴────────────┘
                           modifier

Custom mappings example

You can use ? to view all actions of current source

// coc-settings.json
{
  "explorer.keyMappings.global": {
    "i": false, // cancel default mapkey
    "<c-o>": "noop",

    "*": "toggleSelection",
    "<tab>": "actionMenu",

    "gk": ["wait", "expandablePrev"],
    "gj": ["wait", "expandableNext"],
    "h": ["wait", "collapse"],
    "l": ["wait", "expandable?", "expand", "open"],
    "J": ["wait", "toggleSelection", "normal:j"],
    "K": ["wait", "toggleSelection", "normal:k"],
    "gl": ["wait", "expand:recursive"],
    "gh": ["wait", "collapse:recursive"],
    "<2-LeftMouse>": [
      "expandable?",
      ["expanded?", "collapse", "expand"],
      "open",
    ],
    "o": ["wait", "expanded?", "collapse", "expand"],
    "<cr>": ["wait", "expandable?", "cd", "open"],
    "e": "open",
    "s": "open:split",
    "E": "open:vsplit",
    "t": "open:tab",
    "<bs>": ["wait", "gotoParent"],
    "gs": ["wait", "reveal:select"],
    "il": "preview:labeling",
    "ic": "preview:content",
    "Il": "previewOnHover:toggle:labeling",
    "Ic": "previewOnHover:toggle:content",
    "II": "previewOnHover:disable",

    "yp": "copyFilepath",
    "yn": "copyFilename",
    "yy": "copyFile",
    "dd": "cutFile",
    "p": "pasteFile",
    "df": "delete",
    "dF": "deleteForever",

    "a": "addFile",
    "A": "addDirectory",
    "r": "rename",

    "zh": "toggleHidden",
    "g<dot>": "toggleHidden",
    "R": "refresh",

    "?": "help",
    "q": "quit",
    "<esc>": "esc",
    "X": "systemExecute",
    "gd": "listDrive",

    "f": "search",
    "F": "searchRecursive",

    "gf": "gotoSource:file",
    "gb": "gotoSource:buffer",

    "[[": ["wait", "sourcePrev"],
    "]]": ["wait", "sourceNext"],

    "[i": ["wait", "indentPrev"],
    "]i": ["wait", "indentNext"],

    "[m": ["wait", "markPrev:modified"],
    "]m": ["wait", "markNext:modified"],

    "[d": ["wait", "markPrev:diagnosticError:diagnosticWarning"],
    "]d": ["wait", "markNext:diagnosticError:diagnosticWarning"],
    "[D": ["wait", "markPrev:diagnosticError"],
    "]D": ["wait", "markNext:diagnosticError"],

    "[c": ["wait", "markPrev:git"],
    "]c": ["wait", "markNext:git"],
    "<<": "gitStage",
    ">>": "gitUnstage",
  },
}

WIKI

• https://github.com/weirongxu/coc-explorer/wiki

FAQ

• https://github.com/weirongxu/coc-explorer/wiki/FAQ
• https://github.com/weirongxu/coc-explorer/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3Aquestion

Example by Vim API and event hooks

function! s:explorer_cur_dir()
  let node_info = CocAction('runCommand', 'explorer.getNodeInfo', 0)
  return fnamemodify(node_info['fullpath'], ':h')
endfunction

function! s:exec_cur_dir(cmd)
  let dir = s:explorer_cur_dir()
  execute 'cd ' . dir
  execute a:cmd
endfunction

function! s:init_explorer()
  set winblend=10

  " Integration with other plugins

  " CocList
  nmap <buffer> <Leader>fg <Cmd>call <SID>exec_cur_dir('CocList -I grep')<CR>
  nmap <buffer> <Leader>fG <Cmd>call <SID>exec_cur_dir('CocList -I grep -regex')<CR>
  nmap <buffer> <C-p> <Cmd>call <SID>exec_cur_dir('CocList files')<CR>

  " vim-floaterm
  nmap <buffer> <Leader>ft <Cmd>call <SID>exec_cur_dir('FloatermNew --wintype=floating')<CR>
endfunction

function! s:enter_explorer()
  if &filetype == 'coc-explorer'
    " statusline
    setl statusline=coc-explorer
  endif
endfunction

augroup CocExplorerCustom
  autocmd!
  autocmd BufEnter * call <SID>enter_explorer()
  autocmd FileType coc-explorer call <SID>init_explorer()
augroup END

more API: https://github.com/weirongxu/coc-explorer/wiki/Vim-API

Settings

Commands

Configuration

Definitions

Inspired by

• VSCode Explorer
• Shougo/vimfiler.vim
• Shougo/defx.nvim
• lambdalisue/fern.vim