m1ngsama/chopsticks
1
0
Fork 0
mirror of https://oauth2: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@github.com/m1ngsama/chopsticks.git synced 2026-05-10 19:10:59 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: comprehensive v1.0.0 documentation update

Browse source 
- README: full rewrite — updated language table (staticcheck, yamllint,
  hadolint, marksman via coc-settings.json), install.sh platform coverage,
  removed coc-marksman references, added CHANGELOG link
- QUICKSTART: rewrite to reflect automated install.sh, updated language
  workflows (staticcheck for Go, marksman for Markdown)
- CHANGELOG: new file documenting v1.0.0, v0.9.0, and v0.1.0 releases
- .gitignore: add *.swp, *.swo, .DS_Store, Session.vim
This commit is contained in:
m1ngsama 2026-03-29 18:05:51 +08:00
parent 3daf725ad8
commit 3236155b84
4 changed files with 420 additions and 282 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.gitignore vendored
View file

@ -1,2 +1,6 @@
*.json *.json
!coc-settings.json !coc-settings.json
*.swp
*.swo
.DS_Store
Session.vim

85
CHANGELOG.md Normal file
View file

@ -0,0 +1,85 @@
# Changelog
All notable changes to chopsticks are documented here.
---
## [1.0.0] - 2026-03-29
First stable release. Full-stack engineering environment out of the box — automatic
installation, tiered LSP, TTY fallback, and coverage for 14 languages.
### Added
- **Arch Linux support** in `install.sh` — pacman branch for all system tools
- **`hadolint`** added to system tools installation (Dockerfile linting)
- **`staticcheck`** added to Go tools (replaces archived `golint`)
- **`yamllint`** added to pip tools (YAML linting)
- **`coc-settings.json`** — configures `marksman` as Markdown LSP for CoC via
`languageserver` entry; symlinked automatically by `install.sh`
- **pip3 bootstrap** in `install.sh` — auto-installs pip3 when python3 is present
but pip3 is absent (common on Ubuntu minimal images)
- **9 named augroups** in `.vimrc` — all loose `autocmd` statements now wrapped
with `autocmd!` to prevent doubling on `:source $MYVIMRC`:
`ChopstickTabHistory`, `ChopstickResize`, `ChopstickStdin`, `CocHighlight`,
`ChopstickCleanup`, `ChopstickFiletype`, `ChopstickTTYLargeFile`,
`ChopstickWhichKey`, `ChopstickStartify`
- **TTY-safe plugin install** — `vim +PlugInstall +qall </dev/null` prevents
Vim from blocking in non-interactive/piped environments
### Changed
- SQL tooling unified to **`sqlfluff`** (pip) — `sqlfmt` removed from npm section
- Go linter changed from `golint` (archived 2023) to **`staticcheck`**
- Markdown LSP changed from broken `coc-marksman` (npm) to **`marksman`** binary
configured via `coc-settings.json`
### Fixed
- **vim-go startup hang** on Arch Linux — removed `:GoUpdateBinaries` post-install
hook; set `g:go_gopls_enabled = 0` to prevent conflict with `coc-go`
- **E495 errors** (`<afile>` in special buffers) — all `<afile>` usages guarded
with `!empty(expand('<afile>'))` and `empty(&buftype)` checks
- **`g:go_def_mode` conflict** — now conditional: uses `gopls` when CoC active,
`godef` when vim-lsp active (avoids error when gopls is disabled)
- **vim startup UX** — NERDTree + Startify layout for `vim .` and bare `vim`
- **`coc-marksman` silent failure** — package does not exist on npm; replaced with
native `languageserver` configuration in `coc-settings.json`
- **CoC startup warning** in no-node environments — `g:coc_start_at_startup = 0`
and `g:coc_disable_startup_warning = 1` set when `g:use_coc = 0`
---
## [0.9.0] - 2026-02-21
### Added
- **Full-stack language coverage** — LSP, lint, and format for: Python,
JavaScript, TypeScript, Go, Rust, Shell, YAML, HTML, CSS/SCSS, Less,
JSON, Markdown, SQL, Dockerfile
- **`install.sh` overhaul** — automated installation of system tools, npm tools,
pip tools, Go tools, and CoC language server extensions with platform detection
and interactive prompts; `--yes` flag for non-interactive mode
- **vim-startify** startup screen with dynamic header (version, cwd, git branch)
- **vim-which-key** keybinding popup on `,` + 500ms pause
- **Startup layout** — `vim .` opens NERDTree left + Startify right; bare `vim`
opens Startify with NERDTree alongside
- **Session management** via vim-obsession + vim-prosession
- **Large file handling** — syntax and undo disabled for files > 10 MB
- **Project-local config** — `.vimrc` in project root auto-loaded via `set exrc`
- **Persistent undo** — `~/.vim/.undo/` with `undolevels=1000`
### Changed
- Tiered LSP backend: CoC (Node.js) preferred, vim-lsp (no Node.js) as fallback
- All CoC and vim-lsp keybindings unified (`gd`, `K`, `[g`/`]g`, `,rn`, `,ca`)
- ALE `fix_on_save` disabled when vim-lsp active (prevents double-format)
- NERDTree autocmd wrapped in `augroup NERDTreeAutoClose`
### Fixed
- Multiple leader key conflicts resolved (`,ad`, `,cd`, `,cp`, `,sp`, `,t`)
- CtrlP removed (redundant with FZF)
- Duplicate `set` options cleaned up
- `<leader>A` dead mapping (no alternate-file plugin) removed
---
## [0.1.0] - 2024
Initial release — base Vim configuration with vim-plug, basic plugins, and
TTY/non-TTY detection.

151
QUICKSTART.md
View file

@ -2,6 +2,8 @@
Five minutes from zero to a working Vim engineering environment. Five minutes from zero to a working Vim engineering environment.
---
## Step 1: Install ## Step 1: Install
```bash ```bash
@ -9,8 +11,15 @@ git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
cd ~/.vim && ./install.sh cd ~/.vim && ./install.sh
``` ```
The script handles everything: symlinks, vim-plug, plugin download. The script handles everything: symlinks, vim-plug, plugins, and all tools.
No root access required. It detects your OS (macOS/Debian/Arch/Fedora) and installs what it can automatically.
**Non-interactive (CI / server):**
```bash
./install.sh --yes
```
---
## Step 2: Open Vim ## Step 2: Open Vim
@ -18,15 +27,23 @@ No root access required.
vim vim
``` ```
The startup screen shows recent files and sessions. Press `q` to dismiss The startup screen (vim-startify) shows recent files and sessions.
or just start typing a filename to open. Press `Ctrl+p` to find a file, or just type a path.
## Step 3: Install LSP (pick one path) To open a project:
```bash
vim . # NERDTree on left, Startify on right
vim myfile # opens file directly
```
### Path A: With Node.js (full CoC) ---
## Step 3: Set Up LSP (pick your path)
### Path A: With Node.js (CoC — full LSP)
```bash ```bash
node --version # confirm >= 14.14 node --version # must be >= 14.14
``` ```
Inside Vim, install language servers for your stack: Inside Vim, install language servers for your stack:
@ -35,48 +52,43 @@ Inside Vim, install language servers for your stack:
:CocInstall coc-pyright coc-tsserver coc-go coc-rust-analyzer :CocInstall coc-pyright coc-tsserver coc-go coc-rust-analyzer
``` ```
### Path B: Without Node.js (vim-lsp) Or let `install.sh` do it — it asks during setup.
Open a file of your language, then run: ### Path B: Without Node.js (vim-lsp — no dependencies)
Open a source file, then run:
```vim ```vim
:LspInstallServer :LspInstallServer
``` ```
This auto-detects and installs the correct language server binary. This auto-detects and installs the correct language server for the current filetype.
---
## The 10 Keys That Matter
```
, (pause 500ms) Show all shortcuts
Ctrl+p Fuzzy find file
Ctrl+n Toggle file tree
gd Go to definition
K Show documentation
[g / ]g Prev / next diagnostic
,rn Rename symbol
,rg Search project contents
,gs Git status
,w / ,q Save / Quit
```
--- ---
## Daily Use ## Daily Use
### The 10 keys that matter most ### Navigate Code
```
,w Save
,q Quit
Ctrl+n File tree
Ctrl+p Fuzzy find file
gd Go to definition
K Show docs
[g ]g Prev/next diagnostic
,rn Rename symbol
,gs Git status
, (pause 500ms) Show all shortcuts
```
### Open a project
```bash
cd ~/my-project && vim
```
NERDTree auto-opens when you launch Vim on a directory. Use `Ctrl+p` to
fuzzy-search files by name. Use `,rg` to search file contents.
### Navigate code
| Key | Action | | Key | Action |
|-------|---------------------------------| |-----|--------|
| `gd` | Go to definition | | `gd` | Go to definition |
| `gy` | Go to type definition | | `gy` | Go to type definition |
| `gi` | Go to implementation | | `gi` | Go to implementation |
@ -85,30 +97,30 @@ fuzzy-search files by name. Use `,rg` to search file contents.
| `Ctrl+o` | Jump back | | `Ctrl+o` | Jump back |
| `Ctrl+i` | Jump forward | | `Ctrl+i` | Jump forward |
### Edit code ### Edit Code
| Key | Action | | Key | Action |
|---------|-------------------------------------| |-----|--------|
| `Tab` | Select next completion item | | `Tab` | Select next completion item |
| `Enter` | Confirm completion | | `Enter` | Confirm completion |
| `gc` | Toggle comment (works in visual mode too) | | `gc` | Toggle comment (visual mode too) |
| `cs"'` | Change surrounding `"` to `'` | | `cs"'` | Change surrounding `"` to `'` |
| `ds(` | Delete surrounding `(` | | `ds(` | Delete surrounding `(` |
| `s`+2ch | EasyMotion: jump anywhere | | `s`+2ch | EasyMotion: jump anywhere |
### Manage errors ### Manage Errors
| Key | Action | | Key | Action |
|--------|-------------------------------| |-----|--------|
| `]g` | Jump to next diagnostic | | `]g` | Jump to next diagnostic |
| `[g` | Jump to previous diagnostic | | `[g` | Jump to previous diagnostic |
| `K` | Read the error message | | `K` | Read the error message |
| `,ca` | Apply code action / auto-fix | | `,ca` | Apply code action / auto-fix |
### Git workflow ### Git Workflow
``` ```
,gs git status (stage files with 's', commit with 'cc') ,gs git status (stage with 's', commit with 'cc')
,gd diff current file ,gd diff current file
,gb blame current file ,gb blame current file
,gc commit ,gc commit
@ -118,37 +130,45 @@ fuzzy-search files by name. Use `,rg` to search file contents.
--- ---
## Common Workflows ## Language Workflows
### Python project ### Python
```bash ```bash
# tools installed by install.sh; or manually:
pip install black flake8 pylint isort pip install black flake8 pylint isort
vim my_script.py
``` ```
Auto-formats with black on save. Lint errors show in the sign column as Auto-formats with `black` + `isort` on save. Lint errors show as `X`/`!` in the sign column.
`X` (error) and `!` (warning). Jump between them with `[g` / `]g`.
### JavaScript / TypeScript project ### JavaScript / TypeScript
```bash ```bash
npm install -g prettier eslint typescript npm install -g prettier eslint typescript
vim src/index.ts
``` ```
Auto-formats with prettier on save. Use `:CocInstall coc-tsserver` for Auto-formats with `prettier` on save.
full IntelliSense (requires Node.js).
### Go project ### Go
```bash ```bash
# tools installed by install.sh; or manually:
go install golang.org/x/tools/gopls@latest go install golang.org/x/tools/gopls@latest
vim main.go go install golang.org/x/tools/cmd/goimports@latest
go install honnef.co/go/tools/cmd/staticcheck@latest
``` ```
gofmt runs on save automatically. `gd` jumps to definitions even across `gofmt` + `goimports` run on save automatically.
package boundaries when gopls is running.
### Markdown
Install `marksman` for LSP support (completions, link checking):
```bash
brew install marksman # macOS
sudo pacman -S marksman # Arch
# or: ./install.sh (handles it automatically)
```
--- ---
@ -160,16 +180,26 @@ Edit config live:
,sv " reloads config without restarting ,sv " reloads config without restarting
``` ```
Per-project overrides: create `.vimrc` in your project root. Per-project settings: create `.vimrc` in your project root.
```vim
" project/.vimrc
set shiftwidth=2
let g:ale_python_black_options = '--line-length=100'
```
Change color scheme in `~/.vimrc`:
```vim
colorscheme dracula " or: gruvbox, solarized, onedark
```
--- ---
## Quick Reference ## Quick Reference Card
``` ```
FILES FILES
Ctrl+n File tree toggle Ctrl+n File tree toggle
Ctrl+p Fuzzy find file Ctrl+p Fuzzy find file (git-aware)
,b Search open buffers ,b Search open buffers
,rg Search file contents (ripgrep) ,rg Search file contents (ripgrep)
,w Save | ,q Quit | ,x Save+quit ,w Save | ,q Quit | ,x Save+quit
@ -198,8 +228,7 @@ WINDOWS
SEARCH SEARCH
/text Search forward /text Search forward
?text Search backward ?text Search backward
,<CR> Clear search highlight ,* Replace word under cursor (project-wide)
,* Replace word under cursor (project)
``` ```
--- ---

226
README.md
View file

@ -1,9 +1,10 @@
# chopsticks - Vim Configuration # chopsticks — Vim Configuration
A native Vim configuration optimized for engineering workflows. Designed for A native Vim configuration optimized for full-stack engineering workflows.
Vim 8.0+ with automatic fallbacks for minimal environments (TTY, no Node.js). Vim 8.0+ · Tiered LSP · TTY-aware · Zero icon fonts · 14 languages.
## Quick Install [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Vim 8.0+](https://img.shields.io/badge/Vim-8.0%2B-brightgreen.svg)](https://www.vim.org/)
```bash ```bash
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
@ -16,30 +17,31 @@ See [QUICKSTART.md](QUICKSTART.md) for the 5-minute guide.
## Design Principles ## Design Principles
- **KISS**: No icon fonts, no unicode glyphs, plain ASCII throughout - **KISS** — No icon fonts, no unicode glyphs, plain ASCII throughout
- **Tiered LSP**: CoC (full) with vim-lsp fallback - works with or without Node.js - **Tiered LSP** — CoC (full) with vim-lsp fallback; works with or without Node.js
- **TTY-aware**: Automatic detection and optimization for console environments - **TTY-aware** — Automatic detection and optimization for console/SSH environments
- **Engineering-first**: Git workflow, session management, project-local config - **Engineering-first** — Git workflow, session management, project-local config
- **Batteries included** — `install.sh` handles all dependencies automatically
--- ---
## Requirements ## Requirements
| Requirement | Minimum | Notes | | Requirement | Minimum | Notes |
|----------------|-------------|--------------------------------| |-------------|---------|-------|
| Vim | 8.0+ | vim9script not required | | Vim | 8.0+ | vim9script not required |
| git | any | For cloning and fugitive | | git | any | For cloning and fugitive |
| curl | any | For vim-plug auto-install | | curl | any | For vim-plug auto-install |
| Node.js | 14.14+ | Optional, enables CoC LSP | | Node.js | 14.14+ | Optional — enables CoC LSP |
| ripgrep (rg) | any | Optional, enables :Rg search | | ripgrep (rg) | any | Optional — enables `:Rg` search |
| fzf | any | Optional, enables :Files/:GFiles | | fzf | any | Optional — enables `Ctrl+p` fuzzy search |
| ctags | any | Optional, enables :TagbarToggle | | ctags | any | Optional — enables `F8` tag browser |
--- ---
## Installation ## Installation
### Automatic ### Automatic (recommended)
```bash ```bash
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
@ -47,22 +49,30 @@ cd ~/.vim
./install.sh ./install.sh
``` ```
The script: The installer:
1. Checks for a working Vim installation 1. Checks Vim version and detects OS / package managers
2. Backs up your existing `~/.vimrc` if present 2. Backs up any existing `~/.vimrc` (timestamped)
3. Creates a symlink: `~/.vimrc -> ~/.vim/.vimrc` 3. Creates symlinks: `~/.vimrc -> ~/.vim/.vimrc` and `~/.vim/coc-settings.json`
4. Installs vim-plug 4. Installs vim-plug and runs `:PlugInstall`
5. Runs `:PlugInstall` to download all plugins 5. Optionally installs system tools, language tools, and CoC extensions
6. Optionally installs CoC language servers (if Node.js is available)
Supported platforms: **macOS** (Homebrew), **Debian/Ubuntu** (apt), **Arch Linux** (pacman), **Fedora** (dnf).
Use `--yes` for non-interactive / CI environments:
```bash
./install.sh --yes
```
### Manual ### Manual
```bash ```bash
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
ln -sf ~/.vim/.vimrc ~/.vimrc ln -sf ~/.vim/.vimrc ~/.vimrc
ln -sf ~/.vim/coc-settings.json ~/.vim/coc-settings.json
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \ curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
vim +PlugInstall +qall vim +PlugInstall +qall </dev/null
``` ```
--- ---
@ -72,12 +82,12 @@ vim +PlugInstall +qall
Code intelligence is provided by one of two backends, selected automatically: Code intelligence is provided by one of two backends, selected automatically:
| Condition | Backend | Features | | Condition | Backend | Features |
|----------------------------------|----------------|-----------------------------------------------| |-----------|---------|----------|
| Vim 8.0.1453+ AND Node.js 14.14+ | **CoC** | Full LSP, snippets, extensions ecosystem | | Vim 8.0.1453+ AND Node.js 14.14+ | **CoC** | Full LSP, snippets, extensions ecosystem |
| Vim 8.0+ (no Node.js) | **vim-lsp** | LSP via language server binaries, asyncomplete | | Vim 8.0+ (no Node.js) | **vim-lsp** | LSP via language server binaries, asyncomplete |
| Any Vim | **ALE** | Linting and auto-fix (always active) | | Any Vim | **ALE** | Linting and auto-fix (always active) |
Both backends expose identical key mappings (`gd`, `K`, `[g`, `]g`, `<leader>rn`, `<leader>ca`). Both backends expose identical key mappings: `gd`, `K`, `[g`, `]g`, `<leader>rn`, `<leader>ca`.
### CoC setup (with Node.js) ### CoC setup (with Node.js)
@ -90,12 +100,16 @@ Install language server extensions from inside Vim:
:CocInstall coc-rust-analyzer " Rust :CocInstall coc-rust-analyzer " Rust
:CocInstall coc-json coc-yaml " JSON, YAML :CocInstall coc-json coc-yaml " JSON, YAML
:CocInstall coc-html coc-css " HTML, CSS :CocInstall coc-html coc-css " HTML, CSS
:CocInstall coc-marksman " Markdown :CocInstall coc-sh " Shell
:CocInstall coc-sql " SQL :CocInstall coc-sql " SQL
``` ```
`install.sh` installs all of the above automatically when prompted. `install.sh` installs all of the above automatically when prompted.
**Markdown LSP** — `marksman` is configured via `coc-settings.json` (not a CoC
extension — install `marksman` binary via `brew install marksman` or download from
[releases](https://github.com/artempyanykh/marksman/releases)).
### vim-lsp setup (without Node.js) ### vim-lsp setup (without Node.js)
Install language server binaries for your languages, then run: Install language server binaries for your languages, then run:
@ -104,8 +118,8 @@ Install language server binaries for your languages, then run:
:LspInstallServer " auto-installs the right server for the current filetype :LspInstallServer " auto-installs the right server for the current filetype
``` ```
Supported languages: Python, Go, Rust, TypeScript, JavaScript, Shell, Supported languages: Python, Go, Rust, TypeScript, JavaScript, Shell, HTML,
HTML, CSS/SCSS, JSON, YAML, Markdown, SQL — via `vim-lsp-settings`. CSS/SCSS, JSON, YAML, Markdown, SQL — via `vim-lsp-settings`.
--- ---
@ -118,10 +132,10 @@ Press `,` and wait 500ms for an interactive guide to all bindings (vim-which-key
### Files and Buffers ### Files and Buffers
| Key | Action | | Key | Action |
|------------|-------------------------------------| |-----|--------|
| `Ctrl+n` | Toggle file tree (NERDTree) | | `Ctrl+n` | Toggle file tree (NERDTree) |
| `,n` | Reveal current file in NERDTree | | `,n` | Reveal current file in NERDTree |
| `Ctrl+p` | Fuzzy file search (FZF) | | `Ctrl+p` | Fuzzy file search (FZF — git-aware) |
| `,b` | Search open buffers (FZF) | | `,b` | Search open buffers (FZF) |
| `,rg` | Project-wide search (ripgrep+FZF) | | `,rg` | Project-wide search (ripgrep+FZF) |
| `,rt` | Search tags (FZF) | | `,rt` | Search tags (FZF) |
@ -134,7 +148,7 @@ Press `,` and wait 500ms for an interactive guide to all bindings (vim-which-key
### Windows and Tabs ### Windows and Tabs
| Key | Action | | Key | Action |
|--------------|---------------------------------| |-----|--------|
| `Ctrl+h/j/k/l` | Navigate between windows | | `Ctrl+h/j/k/l` | Navigate between windows |
| `<Leader>=` | Increase window height | | `<Leader>=` | Increase window height |
| `<Leader>-` | Decrease window height | | `<Leader>-` | Decrease window height |
@ -147,7 +161,7 @@ Press `,` and wait 500ms for an interactive guide to all bindings (vim-which-key
### Code Intelligence (CoC / vim-lsp) ### Code Intelligence (CoC / vim-lsp)
| Key | Action | | Key | Action |
|-------------|---------------------------------| |-----|--------|
| `gd` | Go to definition | | `gd` | Go to definition |
| `gy` | Go to type definition | | `gy` | Go to type definition |
| `gi` | Go to implementation | | `gi` | Go to implementation |
@ -158,12 +172,12 @@ Press `,` and wait 500ms for an interactive guide to all bindings (vim-which-key
| `,rn` | Rename symbol | | `,rn` | Rename symbol |
| `,f` | Format selection | | `,f` | Format selection |
| `,ca` | Code action (cursor) | | `,ca` | Code action (cursor) |
| `,qf` | Quick-fix current line (CoC) |
| `,cl` | Run code lens (CoC) |
| `,o` | File outline | | `,o` | File outline |
| `,ws` | Workspace symbols | | `,ws` | Workspace symbols |
| `,cD` | Diagnostics list | | `,cD` | Diagnostics list |
| `,cr` | Resume last CoC list | | `,cr` | Resume last CoC list |
| `,qf` | Quick-fix current line (CoC) |
| `,cl` | Run code lens (CoC) |
| `Tab` | Next completion item | | `Tab` | Next completion item |
| `Shift+Tab` | Previous completion item | | `Shift+Tab` | Previous completion item |
| `Enter` | Confirm completion | | `Enter` | Confirm completion |
@ -173,7 +187,7 @@ Text objects (CoC only): `if`/`af` (function), `ic`/`ac` (class)
### Linting (ALE) ### Linting (ALE)
| Key | Action | | Key | Action |
|----------|-----------------------| |-----|--------|
| `[e` | Next error/warning | | `[e` | Next error/warning |
| `]e` | Previous error/warning | | `]e` | Previous error/warning |
| `,aD` | Show error details | | `,aD` | Show error details |
@ -183,7 +197,7 @@ Signs: `X` = error, `!` = warning
### Git Workflow (fugitive) ### Git Workflow (fugitive)
| Key | Action | | Key | Action |
|--------|---------------------------------| |-----|--------|
| `,gs` | Git status | | `,gs` | Git status |
| `,gc` | Git commit | | `,gc` | Git commit |
| `,gp` | Git push | | `,gp` | Git push |
@ -195,10 +209,10 @@ Signs: `X` = error, `!` = warning
### Engineering Utilities ### Engineering Utilities
| Key | Action | | Key | Action |
|----------|-------------------------------------| |-----|--------|
| `,ev` | Edit `~/.vimrc` | | `,ev` | Edit `~/.vimrc` |
| `,sv` | Reload `~/.vimrc` | | `,sv` | Reload `~/.vimrc` |
| `,F` | Format entire file (= indent) | | `,F` | Format entire file |
| `,W` | Strip trailing whitespace | | `,W` | Strip trailing whitespace |
| `,wa` | Save all open buffers | | `,wa` | Save all open buffers |
| `,wd` | Change CWD to current buffer's dir | | `,wd` | Change CWD to current buffer's dir |
@ -210,13 +224,13 @@ Signs: `X` = error, `!` = warning
| `,qo` | Open quickfix list | | `,qo` | Open quickfix list |
| `,qc` | Close quickfix list | | `,qc` | Close quickfix list |
| `,tv` | Open terminal (vertical split) | | `,tv` | Open terminal (vertical split) |
| `,th` | Open terminal (horizontal, 10r) | | `,th` | Open terminal (horizontal, 10 rows) |
| `Esc` | Exit terminal mode | | `Esc` | Exit terminal mode |
### Navigation and Editing ### Navigation and Editing
| Key | Action | | Key | Action |
|------------|---------------------------------------------| |-----|--------|
| `s`+2ch | EasyMotion jump to any location | | `s`+2ch | EasyMotion jump to any location |
| `Space` | Toggle code fold | | `Space` | Toggle code fold |
| `Y` | Yank to end of line (like `D`, `C`) | | `Y` | Yank to end of line (like `D`, `C`) |
@ -238,27 +252,23 @@ Signs: `X` = error, `!` = warning
## Features ## Features
### vim-startify: Startup Screen ### Startup Screen (vim-startify)
Opens when Vim is launched without a file argument. Shows: Opens when Vim is launched without a file argument. Shows:
- Session list for current directory
- Recently opened files - Recently opened files
- Sessions for the current directory
- Bookmarks - Bookmarks
Session auto-saves on quit. Auto-loads `Session.vim` if found in the current Session auto-saves on quit. Auto-loads `Session.vim` if found in the current
directory. Auto-changes to git root on file open. directory. Auto-changes to git root on file open.
### vim-which-key: Keybinding Guide **`vim .` layout** — NERDTree on the left, Startify on the right.
### Keybinding Guide (vim-which-key)
Press `,` and pause for 500ms. A popup lists all available leader bindings Press `,` and pause for 500ms. A popup lists all available leader bindings
organized by group. Useful for onboarding and discovering shortcuts. organized by group. Useful for onboarding and discovering shortcuts.
### indentLine: Indent Guides
Draws `|` characters at each indent level. Disabled automatically in TTY
environments and for filetypes where it causes display problems (JSON,
Markdown, help).
### Session Management ### Session Management
```vim ```vim
@ -266,8 +276,8 @@ Markdown, help).
:Obsess! " Stop tracking :Obsess! " Stop tracking
``` ```
Sessions are stored in `~/.vim/sessions/` and automatically resumed by Sessions stored in `~/.vim/sessions/` and automatically resumed by vim-prosession
vim-prosession on the next Vim launch in the same directory. on the next Vim launch in the same directory.
### Project-Local Config ### Project-Local Config
@ -288,86 +298,83 @@ to prevent Vim from freezing.
### TTY / Console Support ### TTY / Console Support
Detected automatically when `$TERM` is `linux` or `screen`, or when running Detected automatically when `$TERM` is `linux` or `screen`. In TTY mode:
on a basic built-in terminal. In TTY mode:
- True color and cursorline disabled - True color and cursorline disabled
- Powerline separators replaced with plain ASCII - Powerline separators replaced with plain ASCII
- FZF preview windows disabled - FZF preview windows disabled
- NERDTree auto-open skipped - NERDTree auto-open skipped
- Syntax column limit reduced to 120 - Syntax column limit reduced to 120
- Simpler status line used - Simpler status line
--- ---
## Language Support ## Language Support
| Language | Indent | Formatter | Linter | | Language | Indent | Formatter | Linter | LSP (CoC) |
|----------------|--------|------------------|--------------------------| |----------|--------|-----------|--------|-----------|
| Python | 4sp | black + isort | flake8, pylint | | Python | 4sp | black + isort | flake8, pylint | coc-pyright |
| JavaScript | 2sp | prettier | eslint | | JavaScript | 2sp | prettier | eslint | coc-tsserver |
| TypeScript | 2sp | prettier | eslint, tsserver | | TypeScript | 2sp | prettier | eslint, tsserver | coc-tsserver |
| Go | tab | gofmt, goimports | gopls, golint | | Go | tab | gofmt, goimports | staticcheck | coc-go |
| Rust | 4sp | rustfmt | cargo | | Rust | 4sp | rustfmt | cargo | coc-rust-analyzer |
| Shell | 2sp | - | shellcheck | | Shell | 2sp | — | shellcheck | coc-sh |
| YAML | 2sp | prettier | yamllint | | YAML | 2sp | prettier | yamllint | coc-yaml |
| HTML | 2sp | prettier | - | | HTML | 2sp | prettier | — | coc-html |
| CSS / SCSS | 2sp | prettier | stylelint | | CSS / SCSS | 2sp | prettier | stylelint | coc-css |
| Less | 2sp | prettier | - | | Less | 2sp | prettier | — | — |
| JSON | 2sp | prettier | - | | JSON | 2sp | prettier | — | coc-json |
| Markdown | 2sp | prettier | markdownlint | | Markdown | 2sp | prettier | markdownlint | marksman (coc-settings.json) |
| SQL | 4sp | sqlfmt | sqlfluff | | SQL | 4sp | sqlfluff | sqlfluff | — |
| Dockerfile | 2sp | - | hadolint | | Dockerfile | 2sp | — | hadolint | — |
Install linters separately — `install.sh` lists the exact commands. `install.sh` installs all linters and formatters automatically.
ALE runs them asynchronously on save (`ale_fix_on_save = 1` when using CoC). ALE runs them asynchronously; format-on-save active when using CoC.
--- ---
## Plugin List ## Plugin List
### Navigation ### Navigation
- **NERDTree** - File tree explorer - **NERDTree** — File tree explorer
- **fzf + fzf.vim** - Fuzzy finder - **fzf + fzf.vim** — Fuzzy finder (file, buffer, tag, ripgrep)
- **CtrlP** - Fallback fuzzy finder (no fzf dependency)
### Git ### Git
- **vim-fugitive** - Git commands inside Vim - **vim-fugitive** — Git commands inside Vim
- **vim-gitgutter** - Diff signs in the sign column - **vim-gitgutter** — Diff signs in the sign column
### LSP and Completion ### LSP and Completion
- **coc.nvim** - Full LSP + completion (requires Node.js 14.14+) - **coc.nvim** — Full LSP + completion (requires Node.js 14.14+)
- **vim-lsp** - Pure VimScript LSP client (fallback, no Node.js) - **vim-lsp** — Pure VimScript LSP client (fallback, no Node.js)
- **vim-lsp-settings** - Auto-configure language servers for vim-lsp - **vim-lsp-settings** — Auto-configure language servers for vim-lsp
- **asyncomplete.vim** - Async completion (used with vim-lsp) - **asyncomplete.vim** — Async completion (used with vim-lsp)
### Linting ### Linting
- **ALE** - Asynchronous Lint Engine (always active) - **ALE** — Asynchronous Lint Engine (always active)
### UI ### UI
- **vim-airline** - Status and tabline - **vim-airline** — Status and tabline
- **vim-startify** - Startup screen - **vim-startify** — Startup screen with sessions
- **vim-which-key** - Keybinding hint popup - **vim-which-key** — Keybinding hint popup
- **indentLine** - Indent guide lines (non-TTY) - **indentLine** — Indent guide lines (non-TTY)
- **undotree** - Undo history visualizer - **undotree** — Undo history visualizer
- **tagbar** - Code structure sidebar - **tagbar** — Code structure sidebar
### Editing ### Editing
- **vim-surround** - Change surrounding quotes, brackets, tags - **vim-surround** — Change surrounding quotes, brackets, tags
- **vim-commentary** - `gc` to toggle comments - **vim-commentary** — `gc` to toggle comments
- **auto-pairs** - Auto-close brackets and quotes - **auto-pairs** — Auto-close brackets and quotes
- **vim-easymotion** - Jump anywhere with 2 keystrokes - **vim-easymotion** — Jump anywhere with 2 keystrokes
- **vim-unimpaired** - Bracket shortcut pairs - **vim-unimpaired** — Bracket shortcut pairs
- **targets.vim** - Extra text objects - **targets.vim** — Extra text objects
- **vim-snippets** - Snippet library (used with CoC/UltiSnips) - **vim-snippets** — Snippet library (used with CoC/UltiSnips)
### Language Packs ### Language Packs
- **vim-polyglot** - Syntax for 100+ languages - **vim-polyglot** — Syntax for 100+ languages
- **vim-go** - Go development tools - **vim-go** — Go development tools (formatting + highlighting; LSP handled by coc-go)
### Session ### Session
- **vim-obsession** - Continuous session saving - **vim-obsession** — Continuous session saving
- **vim-prosession** - Project-level session management - **vim-prosession** — Project-level session management
### Color Schemes ### Color Schemes
- **gruvbox** (default), **dracula**, **solarized**, **onedark** - **gruvbox** (default), **dracula**, **solarized**, **onedark**
@ -400,6 +407,14 @@ True color is enabled automatically when the terminal supports it
node --version # must be >= 14.14 node --version # must be >= 14.14
``` ```
**Markdown LSP not starting:**
```bash
marksman --version # must be installed separately
brew install marksman # macOS
sudo pacman -S marksman # Arch
# or: ./install.sh (installs automatically)
```
**vim-lsp server not starting:** **vim-lsp server not starting:**
```vim ```vim
:LspInstallServer " install server for current filetype :LspInstallServer " install server for current filetype
@ -408,8 +423,7 @@ node --version # must be >= 14.14
**Colors look wrong:** **Colors look wrong:**
```bash ```bash
# Add to ~/.bashrc or ~/.zshrc export TERM=xterm-256color # add to ~/.bashrc or ~/.zshrc
export TERM=xterm-256color
``` ```
**ALE not finding linters:** **ALE not finding linters:**
@ -421,12 +435,18 @@ which flake8 black prettier eslint # confirm tools are on PATH
## References ## References
- [amix/vimrc](https://github.com/amix/vimrc)
- [vim-plug](https://github.com/junegunn/vim-plug) - [vim-plug](https://github.com/junegunn/vim-plug)
- [coc.nvim](https://github.com/neoclide/coc.nvim) - [coc.nvim](https://github.com/neoclide/coc.nvim)
- [vim-lsp](https://github.com/prabirshrestha/vim-lsp) - [vim-lsp](https://github.com/prabirshrestha/vim-lsp)
- [vim-lsp-settings](https://github.com/mattn/vim-lsp-settings) - [vim-lsp-settings](https://github.com/mattn/vim-lsp-settings)
- [amix/vimrc](https://github.com/amix/vimrc)
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md).
## License ## License
MIT [MIT](LICENSE) © m1ng