Carbon.nvim

<p align="center"> <strong>The simple directory tree viewer for Neovim written in Lua.</strong> </p>

Introduction

Carbon.nvim provides a simple tree view of the directory Neovim was opened with/in. Its main goal is to remain synchronized with the state of the current working directory. When files are added, moved/renamed, or removed, Carbon automatically updates its state to reflect these changes even if they were made external to Neovim.

Special file types such as symlinks, broken symlinks, and executables are highlighted differently and deeply nested files and folders are compressed as much as possible to reduce the need to manually traverse directories to be able to open files.

Carbon provides the ability to add, move/rename, and delete files and directories, supports mappings to view parent or child directories, settings to control Neovim's pwd (:h carbon-setting-sync-pwd) and lock Carbon's root to Neovim's pwd (:h carbon-setting-sync-on-cd) and much more!

Changelog

See the releases page for more information.

Installation

Install on Nightly Neovim (0.8.0+) using your favorite plugin manager:

| Name | Code | | :----------------------------------------------------------- | :-------------------------------------- | | Vundle.vim | Plugin 'SidOfc/carbon.nvim' | | vim-plug | Plug 'SidOfc/carbon.nvim' | | dein.vim | call dein#add('SidOfc/carbon.nvim') | | minpac | call minpac#add('SidOfc/carbon.nvim') | | packer.nvim | use 'SidOfc/carbon.nvim' | | paq-nvim | { 'SidOfc/carbon.nvim' } | | lazy.nvim | { 'SidOfc/carbon.nvim' } |

Usage and configuration

Depending on whether you use native vim packages or a plugin manager the way Carbon is set up will be slightly different. The most important part is that Carbon's setup method must be called somewhere in your init.lua / init.vim to initialize and use Carbon. It can be called like this:

require('carbon').setup()

Configuration can be supplied like this:

require('carbon').setup({ setting = 'value' })

These settings will be deep merged with the default settings. See :h carbon-settings-table for a list of available settings. An alternative option of calling this method also exists:

require('carbon').setup(function(settings)
  settings.setting = 'value'
end)

This option is more flexible as you have full control over the settings. You are free to modify them as you wish, no merging will occur.

See :h carbon-setup for a more detailed explanation on configuration. See :h carbon-carbon-setup for documentation about the .setup method.

Carbon comes with a few commands and mappings out of the box, each is described below:

Commands

See :h carbon-commands for more detailed information about commands and their customization options.

All commands also support bang (!) versions which will make Carbon expand the tree to reveal the current buffer path if possible. When successful, the cursor will be moved to the entry and it will be highlighted for a short time as well. See :h carbon-view-flash-bang for more information. This behavior can also be enabled by default by setting: :h carbon-setting-auto-reveal.

:Carbon / :Explore

The :Carbon command replaces the current buffer with a Carbon buffer. When :h carbon-setting-keep-netrw is false then NetRW's :Explore command is aliased to :Carbon.

:Lcarbon / :Lexplore / :Rcarbon / ':Rexplore

The :Lcarbon and :Rcarbon commands open a Carbon buffer in a vertical split left of the current buffer. When :h carbon-setting-keep-netrw is false then commands Lexplore and Rexplore are aliased to Lcarbon and Rcarbon respectively. Subsequent calls to :Lcarbon / Rcarbon will attempt to navigate to an existing window opened via these commands.

Additionally, there is a command called ToggleSidebarCarbon which opens the sidebar to the side determined by settings.sidebar_position.

:Fcarbon

The :Fcarbon command opens a Carbon buffer in a floating window. This window can be configured using :h carbon-setting-float-settings.

Mappings

See :h carbon-plugs for more detailed information about mappings and their customization options.

<kbd>[</kbd> Move root up

Moves Carbon's root directory up one level and rerender. See :h carbon-plug-up for more information and customization options. Accepts a count to go up multiple levels at once.

<kbd>]</kbd> Move root down

Moves Carbon's root directory down one level and rerender. See :h carbon-plug-down for more information and customization options. Accepts a count to go down multiple levels at once on compressed paths.

<kbd>u</kbd> Reset root

Resets Carbon's root directory back to the directory Neovim is opened with. See :h carbon-plug-reset for more information and customization options.

<kbd>enter</kbd> Edit file or toggle directory

When on a directory, expand or collapse that directory. When on a file, edit that file in the current buffer and hide Carbon. This mapping works differently when Carbon is opened with :Lcarbon. See :h carbon-plug-edit for more information and customization options.

<kbd>-</kbd> Close parent directories

Closes one or more parent directories of the entry which the cursor is on. Prepending a count will close one extra level of nesting. The cursor will be positioned on the last closed parent.

<kbd>!</kbd> Recursively toggle directories

When on a directory, expand or collapse that directory recursively. When on a file nothing will happen.

NOTE: This mapping is probably best remapped to <kbd>shift</kbd>+<kbd>enter</kbd>. The reason it is not the default is due to specific configuration required to make it work.

Some emulators send the same codes for <kbd>enter</kbd> and <kbd>shift</kbd>+<kbd>enter</kbd> which means Neovim cannot distinguish one from another. This can usually be fixed by setting them manually for your emulator. Included from this SO answer:

I managed to correct my terminal key-code for <kbd>Shift</kbd>+<kbd>Enter</kbd> by sending the key-code Vim apparently expects. Depending on your terminal, (Adding <kbd>Ctrl</kbd>+<kbd>Enter</kbd> as a bonus!)

iTerm2, open Preferences → Profiles → Keys → [+] (Add) →

• Keyboard shortcut: (Hit <kbd>Shift</kbd>+<kbd>Enter</kbd>)
• Action: Send Escape Sequence
• Esc+ [[13;2u Repeat for <kbd>Ctrl</kbd>+<kbd>Enter</kbd>, with sequence: [[13;5u

urxvt, append to your .Xresources file:

URxvt.keysym.S-Return:     \033[13;2u
URxvt.keysym.C-Return:     \033[13;5u

Alacritty, under key_bindings, add following to your ~/.config/alacritty/alacritty.yml:

- { key: Return,   mods: Shift,   chars: "\x1b[13;2u" }
- { key: Return,   mods: Control, chars: "\x1b[13;5u" }

<kbd>ctrl</kbd>+<kbd>x</kbd> Edit file in horizontal split

Does nothing when on a directory. Edit a file in a new horizontal split. See :h carbon-plug-split for more information and customization points.

<kbd>ctrl</kbd>+<kbd>v</kbd> or <kbd>ctrl</kbd>+<kbd>s</kbd> Edit file in vertical split

Does nothing when on a directory. Edit a file in a new vertical split. See :h carbon-plug-vsplit for more information and customization points.

<kbd>q</kbd> Close a Carbon buffer

Close a Carbon buffer, useful for closing Carbon buffers which were opened with Fcarbon or Lcarbon / Rcarbon.

<kbd>c</kbd> or <kbd>%