# nvim

## What is Neovim?
**Neovim** (`nvim`) is a modal text editor forked from Vim, built to be a more extensible and embeddable base for the same editing model. Modal editing means the keyboard behaves differently depending on the current mode, normal mode keys are commands (move, delete, change), insert mode keys are literal text, which lets almost every key on the keyboard act as an editing command without ever touching the mouse.

The appeal for terminal-heavy work (HPC, embedded, remote development over [[ssh]]) is that Neovim runs entirely inside a terminal, needs no display server, and is fast to start even on a resource-constrained remote node. Combined with [[tmux]], it forms a complete development environment that works identically whether you're on a laptop or SSH'd into a compute cluster.

Neovim's main departure from Vim is a built-in Lua runtime and a stable plugin API (LSP client, Treesitter parser integration, a proper async job control API), which turned the editor from something configured with a large ad hoc Vimscript file into something configured and extended with a real scripting language.

## Install
On Debian and Ubuntu:

```bash
sudo apt install neovim
```

Distro packages often lag behind upstream releases significantly. To get a current release directly:

```bash
curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz
tar xzf nvim-linux-x86_64.tar.gz
sudo mv nvim-linux-x86_64 /usr/local/nvim
sudo ln -s /usr/local/nvim/bin/nvim /usr/local/bin/nvim
```

Configuration lives at `~/.config/nvim/init.lua` (or `init.vim` for the legacy Vimscript format).

## Practice
The core interaction model has three modes reached from normal mode:

```
i      -- enter insert mode before the cursor
Esc    -- return to normal mode
v      -- enter visual mode (character selection)
:      -- enter command-line mode
```

Normal-mode commands compose a verb with a motion: `dw` deletes a word, `d$` deletes to end of line, `3dd` deletes three lines. This compositional grammar, rather than a fixed set of keyboard shortcuts, is what makes Vim-style editing scale to complex edits without ever leaving the home row.

```
dw     -- delete word
ciw    -- change inner word
3dd    -- delete 3 lines
/foo   -- search for "foo"
:%s/a/b/g  -- substitute a -> b on every line
```

## Concepts

### The LSP client
Neovim ships a built-in Language Server Protocol client, which means features like go-to-definition, hover documentation, and inline diagnostics come from a separate `clangd`-style language server process rather than being implemented inside the editor itself. Configuring a language for Neovim means telling it which LSP server to launch for that filetype, not writing editor-specific completion logic.

```lua
vim.lsp.start({
  name = 'clangd',
  cmd = {'clangd'},
  root_dir = vim.fs.dirname(vim.fs.find({'compile_commands.json', '.git'}, { upward = true })[1]),
})
```

See [[clangd]] for the C/C++ language server side of this connection.

### Treesitter
Treesitter is an incremental parsing library that builds an actual syntax tree of the buffer as you type, rather than the regex-based highlighting Vim traditionally used. This is what makes syntax highlighting, indentation, and text objects (like "select the enclosing function") accurate even in languages with complex grammars.

```lua
require('nvim-treesitter.configs').setup({
  ensure_installed = { "c", "cpp", "python", "lua" },
  highlight = { enable = true },
})
```

### Plugin managers
Neovim has no built-in package manager beyond a minimal `:packadd` mechanism, so a dedicated plugin manager (`lazy.nvim` is the current standard) handles fetching, updating, and lazily loading plugins:

```lua
require("lazy").setup({
  { "neovim/nvim-lspconfig" },
  { "nvim-treesitter/nvim-treesitter", build = ":TSUpdate" },
})
```

### Remote editing over SSH
Because Neovim is a terminal application with no GUI dependency, editing a file on a remote HPC node is just `ssh` into the node and running `nvim` there, no file syncing, no remote-editing protocol needed. Pairing this with a [[tmux]] session means the editing session survives a dropped connection.

```bash
ssh cluster-node
tmux new -s work
nvim my_kernel.cu
```