# Nixvim Configuration

A standalone Neovim configuration built with [nixvim](https://github.com/nix-community/nixvim) and Nix flakes.

## Installation

```bash
# First time — install to your Nix profile
./install.sh

# Update an existing installation
./update.sh
```

## Testing your configuration

```bash
# Try the config without installing
nix run .

# Verify nothing is broken
nix flake check .
```

## Configuring

Add or modify nix files in `./config`. The main entry point is [`config/default.nix`](./config/default.nix).

## Plugin Usage Guide

This configuration comes with a curated set of plugins. Here's how to get the most out of each one.

### Navigation

#### Telescope — fuzzy finder for everything
| Keymap | Action |
|---|---|
| `<leader>ff` | Find files in the project |
| `<leader>fg` | Live grep across all files (uses ripgrep) |
| `<leader>fb` | Browse open buffers |
| `<leader>fh` | Search help tags |

Type to filter results, `<CR>` to open, `<C-x>` to open in a split, `<C-v>` for a vertical split.

#### Hop — jump to any visible position
| Keymap | Action |
|---|---|
| `s` + two characters | Jump to any matching two-character sequence on screen |

Press `s`, type two characters, then press the hint letter to jump there instantly. Much faster than `f`/`F` or `/search` for medium-distance jumps.

#### fzf-lua — alternative fuzzy finder
| Command | Action |
|---|---|
| `:FzfLua files` | Find files |
| `:FzfLua grep` | Grep project |
| `:FzfLua buffers` | Switch buffers |

Faster than Telescope on very large codebases thanks to the native fzf algorithm.

### File Management

#### nvim-tree — sidebar file explorer
| Keymap | Action |
|---|---|
| `<C-n>` or `:NvimTreeToggle` | Toggle the file tree sidebar |
| `a` | Create a new file or directory (inside the tree) |
| `d` | Delete file (inside the tree) |
| `r` | Rename file (inside the tree) |
| `<CR>` | Open file or expand folder |

#### Oil — edit the filesystem like a buffer
| Command | Action |
|---|---|
| `:Oil` | Open the parent directory as an editable buffer |

Rename files by editing their names, delete by removing lines, create by adding new lines. Save the buffer (`:w`) to apply changes.

#### Bufferline — tab-style buffer bar
| Keymap | Action |
|---|---|
| `:bnext` / `:bprev` | Cycle through open buffers |
| `:bdelete` | Close the current buffer |

Click on tabs with the mouse or use buffer commands to switch between open files.

### Git

#### Fugitive — Git commands inside Neovim
| Command | Action |
|---|---|
| `:Git` | Open interactive git status (stage with `s`, commit with `cc`) |
| `:Git blame` | Inline blame annotations for the current file |
| `:Git diff` | View diff of current file |
| `:Git log` | Browse commit history |
| `:Gwrite` | Stage the current file |

#### Lazygit — full git UI in a floating terminal
| Command | Action |
|---|---|
| `:LazyGit` | Open the lazygit terminal UI |

A visual interface for staging, committing, branching, rebasing, and more. Navigate with arrow keys, press `?` inside lazygit for help.

### Editing

#### Commentary — toggle comments
| Keymap | Action |
|---|---|
| `gcc` | Toggle comment on the current line |
| `gc` + motion | Toggle comments over a motion (e.g. `gcap` for a paragraph) |
| `gc` in visual mode | Toggle comments on selected lines |

#### vim-surround — manage surrounding characters
| Keymap | Action |
|---|---|
| `cs"'` | Change surrounding `"` to `'` |
| `ds"` | Delete surrounding `"` |
| `ysiw]` | Surround the word with `[]` |
| `S"` in visual mode | Surround selection with `"` |

#### cmp — autocompletion
Completion popups appear automatically as you type. Use:
| Keymap | Action |
|---|---|
| `<C-n>` / `<C-p>` | Navigate completion items |
| `<CR>` | Accept the selected completion |
| `<C-e>` | Dismiss the completion menu |

Sources include buffer words, file paths, LSP, and more (all enabled automatically).

### UI & Visual Aids

#### which-key — keybinding discovery
Press `<leader>` (or any prefix key) and **wait** — a popup shows all available continuations. Great for learning and remembering mappings you don't use often.

#### indent-blankline — indentation guides
Visible automatically. Vertical lines show indentation levels so you can quickly see code structure and nesting depth.

#### illuminate — highlight word under cursor
Automatic — all occurrences of the word under your cursor are highlighted. Helps you quickly spot where a variable or function is used.

#### lualine — statusline
Always visible at the bottom. Shows the current mode, git branch, filename, file type, cursor position, and diagnostics.

### Terminal & Environment

#### toggleterm — embedded terminal
| Command | Action |
|---|---|
| `:ToggleTerm` | Toggle a persistent terminal at the bottom |

The terminal persists its state between toggles, so running processes stay alive.

#### direnv — automatic environment loading
Automatic — when you open a project with a `.envrc`, Neovim loads the environment variables and nix shell automatically. No action needed.

### Language Support

#### Treesitter — syntax-aware highlighting
Automatic — provides accurate syntax highlighting, indentation, and code folding for all supported languages. Much better than regex-based highlighting.

#### Nix — Nix language support
Automatic — syntax highlighting, error checking, and formatting for `.nix` files.

#### OpenSCAD — 3D modeling language support
Automatic — syntax highlighting for `.scad` files.

### AI

#### CodeCompanion — AI assistant
| Command | Action |
|---|---|
| `:CodeCompanionChat` | Open an AI chat buffer |
| `:CodeCompanionActions` | Browse available AI actions |

Use it for inline code suggestions, explanations, and refactoring help directly inside the editor.