Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sidofc/carbon.nvim
The simple directory tree viewer for Neovim written in Lua.
https://github.com/sidofc/carbon.nvim
file-explorer lua neovim plugin
Last synced: 12 days ago
JSON representation
The simple directory tree viewer for Neovim written in Lua.
- Host: GitHub
- URL: https://github.com/sidofc/carbon.nvim
- Owner: SidOfc
- License: mit
- Created: 2021-12-14T12:15:37.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-08-19T20:15:32.000Z (3 months ago)
- Last Synced: 2024-10-12T19:26:56.805Z (about 1 month ago)
- Topics: file-explorer, lua, neovim, plugin
- Language: Lua
- Homepage:
- Size: 20.4 MB
- Stars: 177
- Watchers: 2
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Carbon.nvim
[](https://github.com/SidOfc/carbon.nvim/releases)
[](https://opensource.org/licenses/MIT)
[](https://github.com/SidOfc/carbon.nvim/issues)
[](https://github.com/SidOfc/carbon.nvim/commits)
[](https://github.com/SidOfc/carbon.nvim/actions/workflows/ci.yml)
===========
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](#c-or--creating-files-and-directories),
[move/rename](#m-moving-files-and-directories), and [delete](#d-deleting-files-and-directories)
files and directories, supports mappings to view [parent](#-move-root-up) or [child](#-move-root-down)
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](https://github.com/SidOfc/carbon.nvim/releases) page for more information.
# Installation
Install on Nightly Neovim (0.8.0+) using your favorite plugin manager:
| Name | Code |
| :----------------------------------------------------------- | :-------------------------------------- |
| **[Vundle.vim](https://github.com/VundleVim/Vundle.vim)** | `Plugin 'SidOfc/carbon.nvim'` |
| **[vim-plug](https://github.com/junegunn/vim-plug)** | `Plug 'SidOfc/carbon.nvim'` |
| **[dein.vim](https://github.com/Shougo/dein.vim)** | `call dein#add('SidOfc/carbon.nvim')` |
| **[minpac](https://github.com/k-takata/minpac)** | `call minpac#add('SidOfc/carbon.nvim')` |
| **[packer.nvim](https://github.com/wbthomason/packer.nvim)** | `use 'SidOfc/carbon.nvim'` |
| **[paq-nvim](https://github.com/savq/paq-nvim)** | `{ 'SidOfc/carbon.nvim' }` |
| **[lazy.nvim](https://github.com/folke/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:
```lua
require('carbon').setup()
```
Configuration can be supplied like this:
```lua
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:
```lua
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](https://stackoverflow.com/a/42461580/2224331):
> 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](https://www.iterm2.com/)**, 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](http://software.schmorp.de/pkg/rxvt-unicode.html)**, append to your `.Xresources` file:
>
> URxvt.keysym.S-Return: \033[13;2u
> URxvt.keysym.C-Return: \033[13;5u
>
> **[Alacritty](https://github.com/jwilm/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`](#fcarbon) or [`Lcarbon` / `Rcarbon`](#lcarbon--lexplore--rcarbon--rexplore).
### 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](https://github.com/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](https://git-scm.com/)
- [make](https://www.gnu.org/software/make/)
- [neovim](https://github.com/neovim/neovim)
- [stylua](https://github.com/JohnnyMorganz/StyLua)
- [luacheck](https://github.com/mpeterv/luacheck)
## Running tasks
The `make` command is used to perform various tasks such as running the tests or
linting the code. The [Makefile](/Makefile) defines the following tasks:
- [`all`](/Makefile#L1-L5)
- [`test`](/Makefile#L7-L9)
- [`lint`](/Makefile#L11-L13)
- [`format-check`](/Makefile#L15-L17)
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](https://github.com/JohnnyMorganz/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](https://github.com/mpeterv/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](https://github.com/nvim-lua/plenary.nvim) is used to run tests.
You do not need to have it installed. If it is not installed the test [bootstrap](https://github.com/SidOfc/carbon.nvim/blob/master/test/config/bootstrap.lua#L7-L12)
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`](/test/specs) directory.
## Github Actions
carbon.nvim uses Github Actions to run [tests](#testing), [lint](#linting), and
[validate formatting](#formatting) of the code. Pull requests must pass these
checks before they will be considered. See [ci.yml](/.github/workflows/ci.yml) for
more details about the workflow.