Requirements

• Nerd Fonts (Optional with manual intervention: See Recipes/Customizing Icons)
• Neovim v0.8+ (Not including nightly) zTree-sitter CLI (Note: This is only necessary if you want to use auto_install feature with Treesitter)
• A clipboard tool is necessary for the integration with the system clipboard (see :help clipboard-tool for supported solutions)
• Terminal with true color support (for the default theme, otherwise it is dependent on the theme you are using)
• Optional Requirements:
  • ripgrep - live grep telescope search (fw)
  • lazygit - git ui toggle terminal (tl or gg)
  • Python - python repl toggle terminal (tp)
  • Node - Node is needed for a lot of the LSPs, and for the node repl toggle terminal (tn)
  • vim.opt.shell should be set to your current shell in system

Instalation

Make a backup of your current nvim folder

mv ~/.config/nvim ~/.config/nvim.bak

Clean neovim folders (Optional but recommended)

mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak

Clone the repository

git clone --depth 1 https://github.com/benms/neovim-bundle ~/.config/nvim

Testing

This configuration includes automated testing to ensure reliability across different platforms.

Continuous Integration

The repository uses GitHub Actions to automatically test the configuration on:

• Linux (Ubuntu latest) - with Neovim stable and nightly
• macOS (latest)
• Windows (latest)

Tests include:

• Configuration loading verification
• Plugin installation checks
• LSP setup validation
• Syntax validation for all Lua files
• Health check analysis
• Performance benchmarking

Running Tests Locally

You can run the test suite locally to verify your configuration:

# Run all tests
./test/run_tests.sh

# The test script will check:
# - Neovim version compatibility
# - Required dependencies
# - File structure integrity
# - Configuration loading
# - Plugin installation
# - LSP functionality
# - Lua syntax validity
# - Common issues (tabs, trailing whitespace)
# - Health check status
# - Startup performance

The test results will be displayed with color-coded output:

• ✓ Green: Test passed
• ✗ Red: Test failed
• ⚠ Yellow: Warning (non-critical issue)

Manual Testing

You can also manually test specific aspects:

# Check configuration loads without errors
nvim --headless -c "echo 'Config OK'" -c "qa"

# Run health check
nvim --headless -c "checkhealth" -c "qa"

# Sync plugins
nvim --headless -c "Lazy! sync" -c "qa"

# Check for Lua syntax errors
find . -name "*.lua" -exec luac -p {} \;

Plugins/Modules Used

Plugin Manager

• lazy.nvim - Modern plugin manager for Neovim

Core Plugins

• nvim-treesitter - Syntax highlighting and code parsing
• nvim-lspconfig - Quickstart configurations for the Neovim LSP client
• mason.nvim - Portable package manager for Neovim (LSP servers, DAP servers, linters, formatters)

Completion

• nvim-cmp - Completion engine
• cmp-nvim-lsp - LSP source for nvim-cmp
• cmp-buffer - Buffer source for nvim-cmp
• cmp-path - Path source for nvim-cmp
• cmp-cmdline - Command line source for nvim-cmp

Navigation & Search

• telescope.nvim - Fuzzy finder and picker
• hop.nvim - Neovim motions on speed
• neo-tree.nvim - File explorer

Git Integration

• gitsigns.nvim - Git decorations and hunks

UI Enhancements

• lualine.nvim - Fast and easy statusline
• bufferline.nvim - Snazzy buffer line
• nvim-web-devicons - File icons
• onedark.vim - OneDark color scheme

Utilities

• toggleterm.nvim - Terminal integration
• none-ls.nvim - Use Neovim as a language server (formatting, diagnostics)
• plenary.nvim - Lua utility functions (dependency for many plugins)
• nui.nvim - UI component library (dependency for neo-tree)
• lsp-progress.nvim - LSP progress indicator

Keyboard Shortcuts

General Navigation

• <leader> - Space key (default leader)

File Navigation (Telescope)

• <leader>ff - Find files
• <leader>fw - Live grep (search in files)
• <leader>fb - Browse buffers
• <leader>fh - Help tags
• * - Search for word under cursor
• <leader>ls - List document symbols

Git Integration

• <leader>gb - Git branches
• <leader>gc - Git commits
• <leader>gs - Git status
• <leader>gf - Git files
• <leader>gg - Open lazygit (if installed)

LSP (Language Server Protocol)

• gd - Go to definition
• gr - Go to references
• gD - Go to declaration
• K - Hover documentation
• gi - Go to implementation
• <C-k> - Signature help
• <leader>wa - Add workspace folder
• <leader>wr - Remove workspace folder
• <leader>wl - List workspace folders
• <leader>lr - Rename symbol
• <leader>la - Code actions
• <leader>lf - Format code
• [d - Go to previous diagnostic
• ]d - Go to next diagnostic
• <leader>e - Show diagnostic float
• <leader>q - Show diagnostics list

Hop Navigation

• f - Hop to character forward (current line)
• F - Hop to character backward (current line)
• t - Hop till character forward (current line)
• T - Hop till character backward (current line)
• <leader>hw - Hop to word
• <leader>hl - Hop to line
• <leader>hp - Hop to pattern
• <leader>ha - Hop anywhere
• <leader>hc - Hop to 2 characters

Autocompletion (nvim-cmp)

• <C-b> - Scroll docs up
• <C-f> - Scroll docs down
• <C-Space> - Trigger completion
• <C-e> - Abort completion
• <CR> - Confirm selection
• <Tab> - Next completion item
• <S-Tab> - Previous completion item

Terminal (ToggleTerm)

• <C-\> - Toggle terminal
• <leader>tl - Open lazygit terminal
• <leader>tp - Open Python REPL
• <leader>tn - Open Node REPL
• In terminal mode:
  • <Esc> or jk - Exit terminal mode
  • <C-h/j/k/l> - Navigate between windows
  • <C-w> - Window commands

Buffer Management

• Navigate between buffers using bufferline (mouse click or keyboard shortcuts can be configured)

Neo-tree File Explorer

• Can be toggled and navigated (default keybindings apply when focused)

Custom Mappings

• jj - Exit insert mode (mapped to <Esc>)
• :W - Save file (alias for :w)