A personal Neovim configuration built on LazyVim, tuned for Python / Airflow development, with AI assistance via Claude Code.

• English
• 台灣漢語

# Back up existing config
mv ~/.config/nvim ~/.config/nvim.bak

# Clone
git clone https://github.com/Lee-W/nvim-config.git ~/.config/nvim

# Launch — lazy.nvim bootstraps itself on first run
nvim

Install the tools that this config expects outside Mason:

uv tool install basedpyright
uv tool install rumdl

Ensure these executables are on PATH. BasedPyright explicitly bypasses Mason; Markdown formatting calls rumdl. Python debugging starts the adapter through uv, which may download debugpy on first use. Install pytest and your project dependencies in the project's virtualenv. Rust formatting requires rustfmt.

The optional Claude panel requires the claude CLI, and RiNG integration requires the ring CLI. Use :checkhealth and :ConformInfo to diagnose missing tools.

<leader> is Space; <localleader> is \. Unless noted, these are normal-mode keys. Buffer-local mappings (for example, in Diffview) take precedence.

Commenting uses Neovim's built-in gc mappings, enhanced by ts-comments.nvim. For example, gcap comments a paragraph, 3gcc comments three lines, and Vjjgc comments a three-line selection. gco / gcO insert a comment below / above. The backtick is a native mark jump again: `a jumps to mark a's exact position, while 'a jumps to its line.

Use <leader>sk to search active keymaps, or :verbose nmap <Space>cn to find which mapping owns a key. For visual-mode mappings, use :verbose xmap gc.

<leader> is Space. For everyday searching, use Snacks:

1. Press <Space>/.
2. Type the text to search for.
3. Select a result with <C-N> / <C-P> and press <Enter> to open it.

Append ripgrep options after -- to limit the files being searched (do not quote the glob):

windowCreationCommand -- -g=*.lua
useEffect -- -g=*.{ts,tsx}
TODO -- -g=!**/tests/**

Inside the picker, <A-R> toggles regular expressions, <A-H> includes hidden files, and <C-Q> sends the results to the quickfix list.

Use <Space>sr only when a persistent search panel or cross-file replacement is needed. Grug Far opens in a full-page tab and has these inputs:

• Search: text or regular expression to find.
• Replacement: replacement text; leave it empty for search only.
• Files Filter: file glob such as *.lua or *.{ts,tsx}. LazyVim initially fills this with the current file's extension; delete it to search all files.
• Flags: additional ripgrep flags such as -i or -w.
• Paths: directory to search, such as lua/.

Press <Esc> to run the search, <Tab> / <S-Tab> in normal mode to move between inputs, and <Enter> on a result to open it. Press \c to close the panel. If replacement text is present, \r applies the replacement.

Key shortcuts (<leader>a):

In NvimTree, <leader>as adds the file under the cursor to Claude's context.

Diffview workflow:

<leader>gvb tries upstream/HEAD, origin/HEAD, origin/main, then origin/master. If none exists, it warns and falls back to HEAD~1. This branch comparison uses --imply-local, so the HEAD side shows editable working-tree files with LSP support. <leader>gvv compares the index with the working tree. File history opens historical revisions; use gf on a diff to open the local file when you want to edit it.

<leader>gvp requires an authenticated gh CLI. It queries the PR base in the background and fetches from upstream, then origin, if that commit is missing. Each command has a 30-second timeout; the diff opens only after the exact base commit is available. gw returns to its native behavior after closing Diffview.

Enabled via LazyVim extras:

• Python, Rust, TypeScript, SQL, CMake
• Docker, Git, Markdown, JSON, TOML

Jinja2, Handlebars, YAML, and Just have additional local configuration.

Indentation defaults to four spaces; web/template filetypes use two. Makefiles keep literal tabs. Autoformat is enabled by LazyVim; :ConformInfo shows the formatters selected for the current buffer.

Background plugin update checks are disabled. Use :Lazy update deliberately, review lazy-lock.json, then run :TSUpdate after a Treesitter update. To reproduce the checked-in plugin versions, use :Lazy restore (also used in CI).

Run these checks from this repository after changing configuration:

stylua --check .
nvim --clean --headless -l scripts/check_lua.lua
nvim --headless "+lua local ok, err = pcall(dofile, 'scripts/check_config.lua'); if not ok then vim.api.nvim_err_writeln(err); vim.cmd('cquit 1') end" +qa

The smoke checks require installed plugins and check effective keymaps, virtualenv options, filetype loading, formatter configuration, Python workspace initialization, and Diffview mapping cleanup. PR lookup and fetch responses are simulated; the checks do not contact GitHub or run external language servers, project tests, or Claude sessions end to end.

# 備份現有設定
mv ~/.config/nvim ~/.config/nvim.bak

# 下載設定
git clone https://github.com/Lee-W/nvim-config.git ~/.config/nvim

# 啟動 Neovim，lazy.nvim 會自動初始化並安裝所有 plugin
nvim

另外安裝這份配置預期由 Mason 以外提供的工具：

uv tool install basedpyright
uv tool install rumdl

請確認執行檔都在 PATH 上。BasedPyright 已明確停用 Mason 安裝；Markdown 格式化使用 rumdl。Python 除錯透過 uv 啟動 adapter，第一次使用時可能下載 debugpy。pytest 與專案依賴請裝在專案的虛擬環境中；Rust 格式化需要 rustfmt。

Claude 面板需要另外安裝 claude CLI，RiNG 整合需要 ring CLI。 可用 :checkhealth 與 :ConformInfo 確認缺少哪些工具。

<leader> 是空白鍵，<localleader> 是 \。未特別註明時皆為 normal mode 快捷鍵；Diffview 等 buffer 的專用快捷鍵優先。

註解使用 Neovim 內建的 gc 系列快捷鍵，搭配 ts-comments.nvim 改善語法判斷。 例如 gcap 註解一個段落、3gcc 註解三行、Vjjgc 註解選取的三行。 gco／gcO 在下方／上方插入註解。反引號已恢復原生 mark 跳轉： `a 跳到 mark a 的精確位置，'a 則跳到該行。

可用 <leader>sk 搜尋目前快捷鍵，或用 :verbose nmap <Space>cn 查出按鍵由誰設定； visual mode 的快捷鍵則用 :verbose xmap gc 查詢。

<leader> 是空白鍵。平常搜尋請使用 Snacks：

1. 按 <Space>/。
2. 輸入要搜尋的文字。
3. 用 <C-N> / <C-P> 選擇結果，再按 <Enter> 開啟。

若要限制搜尋的檔案，請在 -- 後面附加 ripgrep 選項（glob 不要加引號）：

windowCreationCommand -- -g=*.lua
useEffect -- -g=*.{ts,tsx}
TODO -- -g=!**/tests/**

在 picker 裡，<A-R> 可切換正規表示式、<A-H> 可包含隱藏檔，<C-Q> 則會把結果送到 quickfix list。

只有需要保留搜尋面板或進行跨檔取代時，才使用 <Space>sr。Grug Far 會在 獨立的全頁 tab 開啟，欄位用途如下：

• Search：要尋找的文字或正規表示式。
• Replacement：取代文字；只搜尋時留白。
• Files Filter：檔案 glob，例如 *.lua 或 *.{ts,tsx}。LazyVim 一開始會 自動填入目前檔案的副檔名；刪除即可搜尋所有檔案。
• Flags：額外的 ripgrep 選項，例如 -i 或 -w。
• Paths：搜尋目錄，例如 lua/。

按 <Esc> 執行搜尋；在 normal mode 用 <Tab> / <S-Tab> 切換欄位；移到 搜尋結果後按 <Enter> 開啟。按 \c 關閉面板；有填取代文字時，按 \r 執行取代。

快捷鍵（<leader>a 命名空間）：

在 NvimTree 中，<leader>as 會將游標所在的檔案加入 Claude 的上下文。

Diffview 操作：

<leader>gvb 依序嘗試 upstream/HEAD、origin/HEAD、origin/main、origin/master； 都不存在時會顯示警告並退回 HEAD~1。這個 branch 比較入口帶有 --imply-local， HEAD 那一側會顯示可編輯的工作目錄檔案，並保留 LSP。 <leader>gvv 比較 index 與工作目錄；檔案歷史則開啟歷史版本，需要編輯時可在 diff 中 按 gf 開啟本機檔案。

<leader>gvp 需要已登入的 gh CLI。它會在背景查詢 PR base；若本機缺少該 commit， 會依序嘗試從 upstream、origin fetch。每個命令的逾時為 30 秒，確認指定的 base commit 存在後才開啟 diff。關閉 Diffview 後，gw 會恢復原生行為。

透過 LazyVim extras 啟用：

• Python、Rust、TypeScript、SQL、CMake
• Docker、Git、Markdown、JSON、TOML

Jinja2、Handlebars、YAML 與 Just 另有本機配置。

預設使用四格空白縮排，網頁／模板使用兩格；Makefile 保留 tab。 LazyVim 預設啟用自動格式化，可用 :ConformInfo 查看目前 buffer 選用的 formatter。

已停用背景外掛更新檢查。需要更新時執行 :Lazy update，檢查 lazy-lock.json 的變更， 並在更新 Treesitter 後執行 :TSUpdate。要還原至版本控制內的外掛版本，使用 :Lazy restore（CI 也使用這個命令）。

修改配置後，在 repo 根目錄執行：

stylua --check .
nvim --clean --headless -l scripts/check_lua.lua
nvim --headless "+lua local ok, err = pcall(dofile, 'scripts/check_config.lua'); if not ok then vim.api.nvim_err_writeln(err); vim.cmd('cquit 1') end" +qa

冒煙測試需要先安裝外掛，會檢查實際生效的快捷鍵、虛擬環境選項、filetype 載入、 formatter 配置、Python workspace 初始化，以及關閉 Diffview 後的快捷鍵清理。 PR 查詢與 fetch 回應使用模擬資料；不會連線至 GitHub，也不會完整執行外部 LSP、 專案測試或 Claude session。