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 count
nth
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 count
nth 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 count
nth 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:
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:
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.