dots/nvim
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

remove oil and plan neovim 0.12 upgrade

Browse source
This commit is contained in:
Ray Elliott 2026-10-27 15:01:42 +00:00
commit 0e257cc231
8 changed files with 184 additions and 195 deletions
Download patch file Download diff file Expand all files Collapse all files

176
MIGRATION_PLAN.md
View file

@ -114,8 +114,7 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
- [x] Decision: Skip Neo-tree in favor of netrw for navigation/visual context
- [x] Decision: Use netrw for project structure visualization and file preview
- [x] Decision: Telescope as primary "find file" tool
- [x] Decision: Add Oil.nvim for file manipulation (handles buffer sync on rename/move/delete)
- [x] Note: Oil.nvim is for evaluation; alternative is mini.files if too heavy
- [x] Decision: Evaluate Oil.nvim for file manipulation (later removed in Phase 4.5)
## Phase 4.2 — Configure netrw
- [x] Configure netrw with tree view, preview split, and basic settings (no banner, sensible defaults)
@ -144,7 +143,7 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
- `<leader>fS` - Workspace symbols (LSP)
- [x] Minimal UI: dropdown theme for files/buffers, no previewer for quick selection
## Phase 4.4 — Oil.nvim for file manipulation
## Phase 4.4 — Oil.nvim evaluation (retired)
- [x] Add `stevearc/oil.nvim` for filesystem operations (rename, create, delete, copy, move)
- [x] Configure to handle buffer name sync on file operations
- [x] Keep minimal - use only when shell operations would cause buffer issues
@ -156,6 +155,11 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
- [x] Floating window preview direction: `preview_split = "right"`
- [x] Note: Evaluate practicality; can switch to `mini.files` if preferred
## Phase 4.5 — Return to a netrw-only explorer workflow
- [x] Remove Oil.nvim after workflow evaluation
- [x] Use netrw as the sole tree browser and file explorer for consistency on remote systems
- [x] Keep Telescope as a fuzzy finder rather than a file explorer
## Phase 5 — Treesitter
## Phase 5.1 — Confirm scope and priorities
@ -427,7 +431,6 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
- [x] Add Telescope highlights (TelescopeNormal, TelescopeBorder, TelescopeSelection)
- [x] Add Gitsigns highlights (GitSignsAdd, GitSignsChange, GitSignsDelete)
- [x] Add nvim-cmp highlights (CmpItemKind*, CmpItemMenu, etc.)
- [x] Add Oil.nvim highlights if needed
**Notes**:
- LSP diagnostics use red (error), orange (warn), blue (info), green (hint)
@ -436,7 +439,6 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
- Telescope uses neutral colors with primary accent for matching and selection
- Gitsigns uses status colors: green (add), blue (change), red (delete)
- nvim-cmp uses primary tones for kinds, bold for matching text
- Oil.nvim uses bold for directories, status colors for permissions and operations
- indent-blankline and ufo use subtle grays for non-intrusive UI
## Phase 11.9 — Update plugin configuration
@ -481,7 +483,7 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
## Phase 12.4 — Navigation validation
- [ ] Validate Telescope navigation + LSP jumps
- [ ] Validate netrw browsing and preview splits
- [ ] Validate Oil.nvim file operations
- [x] Remove Oil.nvim and its keymaps, lockfile entry, highlights, and active documentation
- [x] Fix working directory behavior (disabled autochdir, locked Telescope to project root)
- [x] Make alternate-buffer jumps skip netrw explorer buffers when returning to the last real file
- [x] Guard alternate-buffer tracking against unset or invalid buffer numbers
@ -500,6 +502,166 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
- [x] Update LOG.md with final architecture and usage
- [ ] Clean up any remaining debug code or temporary comments
## Phase 13 — Controlled Neovim 0.12 Upgrade
## Phase 13.1 — Confirm scope and upgrade policy
- [ ] Confirm scope and priorities for this phase
- [x] Target the current stable release: Neovim 0.12.6
- [x] Continue using the official standalone Linux archive; do not hand Neovim management to pacman
- [x] Keep Neovim 0.11.5 available until the upgraded setup has passed normal-use validation
- [x] Separate the Neovim upgrade, plugin update, and Mason tool update into independently testable steps
## Phase 13.2 — Create a clean rollback checkpoint
- [x] Commit the completed Oil.nvim removal before beginning the upgrade
- [x] Record the current Neovim version, plugin lockfile, parser state, and startup result
- [x] Confirm the existing 0.11.5 configuration still passes its automated checks
- [x] Do not remove or overwrite the working 0.11.5 installation
## Phase 13.3 — Audit 0.12 compatibility before switching
- [ ] Review the Neovim 0.12 breaking changes against the active configuration
- [ ] Replace deprecated `vim.loop` usage with `vim.uv`
- [ ] Replace deprecated diagnostic navigation APIs with the current diagnostic jump API
- [ ] Revalidate native `exrc` behavior now that 0.12 searches parent directories
- [ ] Verify `vim.secure.read()` behavior in the project-local LSP settings loader
- [ ] Determine how Neovim 0.12's built-in directory buffers interact with opt-in legacy netrw
- [ ] Explicitly load netrw with `:packadd netrw` from Lua if 0.12 no longer loads it automatically
- [ ] Check for conflicts or redundancy with Neovim 0.12's built-in `:Undotree`; do not remove the plugin without a separate decision
## Phase 13.4 — Install Neovim 0.12.6 alongside 0.11.5
- [ ] Download the official `nvim-linux-x86_64.tar.gz` release archive
- [ ] Verify the archive against the SHA-256 digest published with the release
- [ ] Install into a versioned directory without replacing 0.11.5
- [ ] Introduce an explicit `current` symlink (or equivalent atomic selector) for the active version
- [ ] Update the external PATH configuration only after both versioned binaries are verified
- [ ] Document the one-command rollback to 0.11.5
Proposed layout:
```text
/opt/neovim/nvim-0.11.5/
/opt/neovim/nvim-0.12.6/
/opt/neovim/current -> nvim-0.11.5
```
## Phase 13.5 — Test 0.12 with the existing plugin lockfile
- [ ] Use isolated `XDG_DATA_HOME`, `XDG_CACHE_HOME`, and `XDG_STATE_HOME` directories
- [ ] Install the currently locked plugin revisions into the isolated data directory
- [ ] Keep the production plugin and Mason directories untouched
- [ ] Validate headless startup and capture startup time
- [ ] Run `:checkhealth` and review every relevant warning/error
- [ ] Verify netrw can be loaded and `:Explore` opens the expected tree browser
- [ ] Fix core/config compatibility issues before updating plugins
## Phase 13.6 — Update plugins in isolation
- [ ] Use a temporary branch or worktree based on the rollback checkpoint
- [ ] Run lazy.nvim updates only inside the isolated 0.12 test environment
- [ ] Review every lockfile change before adopting it
- [ ] Prioritize lazy.nvim, nvim-lspconfig, Treesitter, Telescope, Mason integration, completion, formatting, linting, UFO, and Copilot compatibility
- [ ] Rebuild or update Treesitter parsers for the 0.12 runtime and verify custom queries
- [ ] Keep Mason-managed language servers, formatters, and linters pinned during this step
- [ ] Adopt the tested lockfile only after all plugin-level regressions are resolved
## Phase 13.7 — Validate the complete 0.12 candidate
- [ ] Validate startup, lazy loading, commands, and keymaps
- [ ] Validate netrw tree browsing, previews, alternate-buffer behavior, and file operations
- [ ] Validate Telescope files, grep, buffers, and LSP symbol pickers
- [ ] Validate LSP attachment, `gd`, `gr`, `K`, diagnostics, and project-local `.nvim.lua` settings
- [ ] Validate nvim-cmp, LuaSnip, and Copilot completion
- [ ] Validate conform format-on-save and nvim-lint/Ruff diagnostics
- [ ] Validate Treesitter highlighting, text objects, autotag, folding, and custom HTML/CSS queries
- [ ] Validate the Paper Tonic colorscheme, plugin highlights, sessions, persistent undo, and shell templates
- [ ] Perform interactive smoke tests in the PHP validation workspace
## Phase 13.8 — Activate with rollback available
- [ ] Switch the active-version selector from 0.11.5 to 0.12.6
- [ ] Repeat a short smoke test through the normal shell/PATH entrypoint
- [ ] Keep 0.11.5 and its rollback instructions available during a settling period
- [ ] Update AGENTS.md, README.md, and LOG.md with the final supported version and upgrade procedure
- [ ] Remove 0.11.5 only after an explicit later decision
## Phase 13.9 — Update external tools separately
- [ ] Review Mason package updates only after Neovim and plugin revisions are stable
- [ ] Update language servers, formatters, and linters in small groups
- [ ] Revalidate PHP, JavaScript/TypeScript, HTML/CSS, Markdown, Lua, and Python after each group
## Phase 14 — Netrw Live Preview and Directory Summaries
## Phase 14.1 — Confirm the final interaction model
- [ ] Confirm scope and priorities for this phase after the 0.12 upgrade
- [x] Keep netrw as the sole tree browser and file explorer
- [x] Keep `p` as the preview entry point so stock-netrw muscle memory remains useful on remote systems
- [x] Once a native preview window exists, update it automatically as the netrw cursor moves
- [x] Close the preview automatically when a file is opened for editing or netrw is left
- [x] Treat the existence of the preview window as state; avoid a separate global preview-mode flag
Target workflow:
```text
p on file/directory open preview and begin live updates
j / k replace preview with the selected entry
<CR>, o, v, t open the file and close the preview
:pclose / <C-w>z close the preview and stop live updates
```
## Phase 14.2 — Revalidate netrw integration on Neovim 0.12
- [ ] Confirm the netrw version and its documented `netrw#Call()` bridge
- [ ] Confirm `NetrwGetWord`, `NetrwBrowseChgDir`, and `NetrwPreview` remain available
- [ ] Confirm tree paths, symlinks, directory markers, local paths, and URI paths are classified correctly
- [ ] Resolve any interaction with Neovim 0.12's built-in `filetype=directory` buffers
- [ ] Keep a graceful stock-netrw fallback if enhanced preview setup cannot be installed
## Phase 14.3 — Implement live preview lifecycle
- [ ] Extend netrw's buffer-local `p` behavior without changing its familiar purpose
- [ ] Add a narrowly scoped, buffer-local `CursorMoved` autocmd
- [ ] Debounce preview updates by approximately 75–100 ms
- [ ] Update only when a preview window exists in the current tab
- [ ] Continue using netrw's native preview machinery for regular files
- [ ] Close the preview when leaving the netrw buffer to edit a file
- [ ] Cancel and close pending timers when the netrw buffer is wiped out
- [ ] Avoid focus changes: keep the cursor in the tree while previews update
## Phase 14.4 — Add read-only directory summaries
- [ ] Show an informational scratch-buffer preview when the selected entry is a directory
- [ ] List immediate children only; do not calculate recursive directory sizes
- [ ] Sort directories first and files second, alphabetically within each group
- [ ] Show entry type, human-readable file size, modification time, and name
- [ ] Show a summary count and total size for immediate files
- [ ] Cap output at approximately 200 entries and show a truncation notice
- [ ] Handle empty, missing, unreadable, and rapidly changing directories without errors
- [ ] Display symlinks distinctly without recursively following directory links
- [ ] Mirror netrw's hidden-file visibility where practical
- [ ] Support local filesystems when Neovim itself is running over SSH
- [ ] Fall back to native behavior for remote netrw URI schemes if directory enumeration is unavailable
Example directory preview:
```text
lua/plugins/
Type Size Modified Name
dir — 2026-10-27 11:42 helpers/
file 4.8K 2026-10-27 13:10 lsp.lua
file 3.2K 2026-10-27 12:55 telescope.lua
1 directory, 2 files, 8.0K
```
## Phase 14.5 — Test preview behavior
- [ ] Test file → file, file → directory, directory → file, and directory → directory movement
- [ ] Test directory expand/collapse while a preview exists
- [ ] Test manual preview closure and confirm cursor movement no longer previews
- [ ] Test `<CR>`, horizontal split, vertical split, and tab selection cleanup
- [ ] Test separate preview windows across tabpages
- [ ] Test spaces, Unicode, symlinks, unreadable entries, deleted entries, and large directories
- [ ] Test rapid cursor movement for flicker, stale timers, and excess filesystem work
- [ ] Test the workflow in an actual SSH session
- [ ] Confirm stock netrw remains understandable when this configuration is unavailable
## Phase 14.6 — Document and finalize
- [ ] Update README.md and `:KeymapsGuide` with the enhanced `p` lifecycle
- [ ] Record implementation decisions and limitations in LOG.md
- [ ] Mark Phase 12.4 netrw preview validation complete after interactive use
---
Notes:
@ -518,4 +680,4 @@ Decisions & Changes:
- **Project config format**: `.nvim.lua` files return `{ lsp = { [server_name] = { settings = {...} } } }`.
- **Security model**: `secure` mode prompts user to trust `.nvim.lua` files before execution (one-time per file hash).
- **Settings loading**: An `LspAttach` callback securely reads project settings from the client's actual `root_dir` (not cwd), ensuring correct behavior across different workspace structures.
- **Phase 4 Navigation Strategy**: Skipped Neo-tree in favor of built-in netrw for visual context and project structure browsing. Telescope for fuzzy finding. Oil.nvim for file manipulation (evaluation phase; alternative is mini.files). Rationale: User needs visual context and preview, not per-tab roots or complex tree features. File manipulation primarily done in shell, but Oil.nvim handles buffer sync issues when renaming/moving files.
- **Phase 4 Navigation Strategy**: Use built-in netrw as the sole tree browser and file explorer so the workflow transfers to remote systems. Telescope remains the fuzzy finder. Oil.nvim was evaluated and removed because maintaining a second explorer split muscle memory without providing the preferred tree view.