README.md

Carbon.nvim

The simple directory tree viewer for Neovim written in Lua.

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.

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

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

u 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.

enter 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.

- 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.

! 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 shift+enter. The reason it is not the default is due to specific configuration required to make it work.

Some emulators send the same codes for enter and shift+enter 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 Shift+Enter by sending the key-code Vim apparently expects. Depending on your terminal, (Adding Ctrl+Enter as a bonus!)

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

• Keyboard shortcut: (Hit Shift+Enter)
• Action: Send Escape Sequence
• Esc+ [[13;2u Repeat for Ctrl+Enter, 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" }

ctrl+x 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.

ctrl+v or ctrl+s 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.

q Close a Carbon buffer

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

c or % Creating files and directories

Enters an interactive mode in which a path can be entered. When done typing, press enter to confirm or escape to cancel. Prepending a count to c will select the countnth directory from the left as base. See :h carbon-view-create for more details.

m Moving files and directories

Prompts to enter a new destination of the current entry under the cursor. Will throw an error when the new destination already exists. Prepending a count to c will select the countnth directory from the left as base. See :h carbon-view-move for more details.

d Deleting files and directories

Prompts confirmation to delete the current entry under the cursor. Press enter to confirm the currently highlighted option, D to confirm deletion directly, or escape to cancel. Prepending a count to c will select the countnth directory from the left as base. See :h carbon-view-delete for more details.

File icons

Carbon provides builtin support for nvim-tree/nvim-web-devicons. See :h carbon-setting-file-icons for more information.

Development

The following dependencies must be installed before you can work on carbon.nvim:

• git
• make
• neovim
• stylua
• luacheck

Running tasks

The make command is used to perform various tasks such as running the tests or linting the code. The Makefile defines the following tasks:

• all
• test
• lint
• format-check

Run make to execute all tasks. To execute a specific task run make {task} where {task} is one of the tasks listed above.

Formatting

stylua is used to format code. Please make sure it is installed and integrated into your editor or run make format-check and fix any errors before committing the code.

Linting

luacheck is used for linting. Please make sure it is installed and integrated into your editor or run make lint and fix any errors before committing the code.

Testing

plenary.nvim is used to run tests. You do not need to have it installed. If it is not installed the test bootstrap process will handle installing it. Run make test and ensure tests pass before committing the code.

The tests can be found in the test/specs directory.

Github Actions

carbon.nvim uses Github Actions to run tests, lint, and validate formatting of the code. Pull requests must pass these checks before they will be considered. See ci.yml for more details about the workflow.