From 7b571fee2efea1e6316b5949118a6625c71233bf Mon Sep 17 00:00:00 2001 From: "Paul B. Kim" Date: Sat, 9 May 2026 00:14:57 +0900 Subject: [PATCH] add neovim field manual --- MANUAL.md | 341 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + init.lua | 9 +- 3 files changed, 351 insertions(+), 1 deletion(-) create mode 100644 MANUAL.md diff --git a/MANUAL.md b/MANUAL.md new file mode 100644 index 00000000..cc0b3992 --- /dev/null +++ b/MANUAL.md @@ -0,0 +1,341 @@ +# Neovim Field Manual + +This is a hands-on guide for this config. It focuses on the shortcuts, motions, +and working habits that are most useful day to day. + +Leader is ``. + +## First Moves + +| Goal | Keys | Notes | +| --- | --- | --- | +| See available leader groups | `` | `which-key` opens immediately. | +| Find files | `sf` | Telescope file picker. | +| Search text in project | `sg` | Uses ripgrep through Telescope. | +| Search current buffer | `/` | Compact in-buffer fuzzy search. | +| Switch buffers | `` | Telescope buffer picker. | +| Previous / next buffer | `` / `` | Bufferline navigation. | +| Reveal file tree | `\` | Neo-tree reveal. | +| Open Oil explorer | `eo` | Editable directory buffer. | +| Format buffer | `f` | Conform, with LSP fallback. | +| Exit terminal mode | `` | Easier than ``. | + +## Motions Worth Practicing + +### Cursor and file movement + +| Motion | Meaning | Practice | +| --- | --- | --- | +| `h j k l` | left, down, up, right | Use these before arrow keys. | +| `w` / `b` | next / previous word start | Move through identifiers quickly. | +| `e` / `ge` | next / previous word end | Useful before `c` and `d`. | +| `0` / `^` / `$` | line start, first nonblank, line end | Combine with `d`, `y`, `c`. | +| `gg` / `G` | file top / bottom | Prefix `G` with a line number. | +| `%` | matching pair | Parentheses, braces, brackets. | +| `{` / `}` | paragraph or block-ish movement | Good in Markdown and code blocks. | +| `` / `` | half-page down / up | Your `scrolloff=10` keeps context visible. | +| `` / `` | jump back / forward | `jumpoptions=clean,view` restores view better. | + +### Search movement + +| Motion | Meaning | +| --- | --- | +| `/text` | search forward | +| `?text` | search backward | +| `n` / `N` | next / previous match | +| `*` / `#` | search word under cursor forward / backward | +| `` | clear search highlight | + +Search is smart-case: lowercase searches are case-insensitive, mixed-case +searches become case-sensitive. + +### One-character targeting + +| Motion | Meaning | Example | +| --- | --- | --- | +| `f` | move to next char | `f)` | +| `F` | move to previous char | `F(` | +| `t` | move before next char | `dt,` deletes until comma. | +| `T` | move after previous char | `cT.` changes back to after dot. | +| `;` / `,` | repeat char search forward / backward | Works after `f`, `F`, `t`, `T`. | + +## Editing Grammar + +Vim editing is usually: + +```text +operator + motion +``` + +| Operator | Meaning | Example | +| --- | --- | --- | +| `d` | delete | `dw`, `d$`, `di"` | +| `c` | change | `ciw`, `cib`, `ct,` | +| `y` | yank | `yiw`, `yap`, `y$` | +| `>` / `<` | indent / unindent | `>ip`, `sh` | +| Keymaps | `sk` | +| Files | `sf` | +| Builtin pickers | `ss` | +| Word under cursor | `sw` | +| Live grep | `sg` | +| Diagnostics | `sd` | +| Resume last picker | `sr` | +| Recent files | `s.` | +| Commands | `sc` | +| Open-file grep | `s/` | +| Neovim config files | `sn` | +| Project search and replace | `sR` | + +Hands-on flow: + +1. Use `sg` to find a symbol or string. +2. Use `` in Telescope when you want a quickfix list. +3. Use `sR` for real project edits with preview. +4. Use `f` after edits to format. + +## LSP and Code Intelligence + +| Goal | Keys | +| --- | --- | +| Rename symbol | `grn` | +| Code action | `gra` | +| References | `grr` or `gr` | +| Implementation | `gri` or `gi` | +| Definition | `grd` or `gd` | +| Declaration | `grD` or `gD` | +| Document symbols | `gO` | +| Workspace symbols | `gW` | +| Type definition | `grt` or `gt` | +| Toggle inlay hints | `th` | + +This config also enables LSP CodeLens when the server supports it and linked +editing for servers that expose `textDocument/linkedEditingRange`. + +## Diagnostics + +| Goal | Keys | +| --- | --- | +| Previous diagnostic | `[d` | +| Next diagnostic | `]d` | +| Diagnostic details | `de` | +| Diagnostics location list | `q` | +| Yank diagnostic context | `dy` | +| Trouble all diagnostics | `xx` | +| Trouble workspace diagnostics | `xw` | +| Trouble current document | `xd` | +| Trouble quickfix | `xq` | +| Trouble loclist | `xl` | + +Diagnostic display is intentionally quieter: + +- Virtual text shows warnings and errors. +- Underlines are limited to errors. +- Diagnostic floats use rounded borders. +- Jumping diagnostics opens a focused-on-cursor float through `jump.on_jump`. + +## Git + +### Repository-level UI + +| Goal | Keys | +| --- | --- | +| Open Neogit | `Gg` | +| Open Diffview | `Gd` | +| Close Diffview | `GD` | +| Current file history | `Gf` | +| Repository history | `GF` | + +### Hunk-level work + +| Goal | Keys | +| --- | --- | +| Next / previous hunk | `]c` / `[c` | +| Stage hunk | `hs` | +| Reset hunk | `hr` | +| Stage buffer | `hS` | +| Undo staged hunk | `hu` | +| Reset buffer | `hR` | +| Preview hunk | `hp` | +| Preview hunk inline | `hi` | +| Blame current line | `hb` | +| Diff against index | `hd` | +| Diff against last commit | `hD` | +| All hunks to quickfix | `hQ` | +| Current buffer hunks to quickfix | `hq` | +| Toggle current-line blame | `tb` | +| Toggle word diff | `tw` | +| Toggle deleted lines | `tD` | + +In visual mode, `hs` and `hr` stage or reset the selected hunk +range. + +## Buffers, Windows, and Sessions + +| Goal | Keys | +| --- | --- | +| Previous / next buffer | `` / `` | +| Pick buffer | `bp` | +| Delete current buffer | `bd` | +| Delete all listed buffers | `bD` | +| Move left / right window | `wh` / `wl` | +| Move lower / upper window | `wj` / `wk` | +| Tmux-aware navigation | `` | +| Restore session | `wr` | +| Restore last session | `wl` | +| Stop session save | `wd` | + +Splits open to the right and below by default. + +## Files and AI-Friendly References + +| Goal | Keys | +| --- | --- | +| Neo-tree reveal | `\` | +| Oil explorer | `eo` | +| Harpoon add file | `a` | +| Harpoon menu | `hm` or `` | +| Harpoon previous / next | `` / `` | +| Yank absolute file location | `ya` | +| Yank relative file location | `yr` | +| Yank current file as `@path` | `yf` | +| Yank current directory as `@dir` | `yd` | + +The reference yanks include file, range, and symbol context when available. +They are useful for prompts, review comments, and issue descriptions. + +## Tests and Debugging + +### Neotest + +| Goal | Keys | +| --- | --- | +| Run nearest test | `nr` | +| Run current file | `nf` | +| Run suite from cwd | `ns` | +| Debug nearest test | `nd` | +| Toggle summary | `nn` | +| Open output | `no` | +| Toggle output panel | `nO` | +| Attach | `na` | +| Stop run | `nS` | + +### DAP + +| Goal | Keys | +| --- | --- | +| Continue / start | `` | +| Step into | `` | +| Step over | `` | +| Step out | `` | +| Toggle breakpoint | `b` | +| Conditional breakpoint | `B` | +| Toggle DAP UI | `` | + +Configured adapters include Go through `dap-go` when `dlv` exists, JS/TS through +`js-debug-adapter`, and C/C++ through `codelldb`. + +## CMake, Markdown, and Code Context + +| Goal | Keys | +| --- | --- | +| CMake generate | `cg` | +| CMake build | `cb` | +| CMake run | `cr` | +| CMake test | `ct` | +| CMake config | `cc` | +| Markdown preview | `mp` | +| Toggle Treesitter context | `tc` | +| Next function start | `jm` | +| Next function end | `jM` | +| Previous function start | `jk` | +| Previous function end | `jK` | +| Next class start | `jc` | +| Previous class start | `jC` | +| Open all folds | `zR` | +| Close all folds | `zM` | + +## Completion and Snippets + +Completion uses `blink.cmp` with LSP, paths, and snippets. + +| Goal | Keys | +| --- | --- | +| Open completion/docs | `` | +| Next / previous item | `` / `` | +| Accept completion | `` | +| Hide menu | `` | +| Toggle signature help | `` | + +Supermaven is active on insert: + +| Goal | Keys | +| --- | --- | +| Accept suggestion | `` | +| Clear suggestion | `` | +| Accept word | `` | + +## Config-Specific Habits + +- Use `` groups by memory shape: `s` for search, `g` for goto, `G` for + git UI, `h` for git hunks, `x` for Trouble, `n` for tests, `w` for windows + and sessions, `y` for reference yanks. +- Keep relative line numbers on. For example, `d5j` deletes five lines down, + and `y3k` yanks three lines up. +- Use `.` after focused edits. Example: `ciwnew_name` then jump and press + `.` to repeat. +- Prefer text objects over visual selection when possible: `ci"`, `di)`, + `yaf`, `dac`. +- Use `` after LSP jumps. Your jump list preserves view, so returning to + the previous context is less disorienting. +- Use `dy`, `yr`, and `yf` when copying context for AI + agents or code reviews. +- Do not rely on modelines for project settings. This config disables modelines + for safer project-local behavior. + +## Five-Minute Drill + +1. Open a project with `nvim .`. +2. Press `sf`, open a file. +3. Use `/`, `n`, `N`, `w`, `b`, `%`, ``, and `` to move without the mouse. +4. Change a word with `ciw`, repeat the edit elsewhere with `.`. +5. Select a function with `vaf`, then try `yaf` and `daf` in a scratch file. +6. Jump to definition with `gd`, return with ``. +7. Open diagnostics with `xx`, then jump with `[d` and `]d`. +8. Preview a git hunk with `hp`, then stage it with `hs`. +9. Run the nearest test with `nr`. +10. Copy an AI-friendly reference with `yr`. diff --git a/README.md b/README.md index 69cfdb92..19f022d5 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ Personal Neovim config based on `kickstart.nvim`, tuned for backend-heavy work in JavaScript/TypeScript, C/C++, Kubernetes, and server development. +For the hands-on shortcut and motion guide, start with [MANUAL.md](MANUAL.md). + This README is the working manual for what is configured, why it exists, and how to use it quickly. diff --git a/init.lua b/init.lua index e85335ca..d1fb928a 100644 --- a/init.lua +++ b/init.lua @@ -8,7 +8,7 @@ vim.g.mapleader = ' ' vim.g.maplocalleader = ' ' -- Set to true if you have a Nerd Font installed and selected in the terminal -vim.g.have_nerd_font = false +vim.g.have_nerd_font = true -- [[ Setting options ]] -- See `:help vim.o` @@ -513,6 +513,13 @@ require('lazy').setup({ completion = { callSnippet = 'Replace', }, + diagnostics = { + globals = { 'vim' }, + }, + workspace = { + checkThirdParty = false, + library = vim.api.nvim_get_runtime_file('', true), + }, }, }, },