mirror of
https://oauth2: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@github.com/m1ngsama/chopsticks.git
synced 2026-05-10 19:10:59 +08:00
docs: rewrite README and QUICKSTART — clean, short, for geeks
Cut README from 330 to 124 lines. No fluff, no repeated tables. QUICKSTART is now a compact cheat sheet, not a tutorial. Both point to the wiki for deep dives.
This commit is contained in:
parent
6044fc5fcb
commit
fa59d5be8f
2 changed files with 138 additions and 472 deletions
276
QUICKSTART.md
276
QUICKSTART.md
|
|
@ -1,228 +1,96 @@
|
||||||
# Quick Start
|
# Quick Start
|
||||||
|
|
||||||
Five minutes from zero to a working Vim environment.
|
Five minutes from zero to a working Vim setup.
|
||||||
|
|
||||||
---
|
## Install
|
||||||
|
|
||||||
## Step 0: Vim Basics (2 minutes)
|
|
||||||
|
|
||||||
> **When confused, press `Esc` until things feel normal again.**
|
|
||||||
|
|
||||||
Vim is **modal** — the keyboard behaves differently depending on which mode you are in.
|
|
||||||
|
|
||||||
| Mode | Purpose | Enter | Leave |
|
|
||||||
|------|---------|-------|-------|
|
|
||||||
| **Normal** | Navigate and run commands | default on startup | — |
|
|
||||||
| **Insert** | Type text | `i` before / `a` after / `o` new line | `Esc` or `jk` |
|
|
||||||
| **Visual** | Select text | `v` char / `V` line | `Esc` |
|
|
||||||
|
|
||||||
### 4 commands that get you out of any jam
|
|
||||||
|
|
||||||
| Command | Action |
|
|
||||||
|---------|--------|
|
|
||||||
| `Esc` or `jk` | Exit insert / visual mode → Normal |
|
|
||||||
| `:q!` then `Enter` | Force quit without saving |
|
|
||||||
| `,x` | Save and quit |
|
|
||||||
| `,w` or `Ctrl+s` | Save |
|
|
||||||
|
|
||||||
Once in Normal mode, press `,?` to open the cheat sheet.
|
|
||||||
Run `:ChopsticksLearn` for a full interactive tutorial.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Step 1: Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
|
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
|
||||||
```
|
```
|
||||||
|
|
||||||
Traditional:
|
Open vim. Plugins install automatically on first launch (30-60s). Restart vim.
|
||||||
```bash
|
|
||||||
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
|
|
||||||
cd ~/.vim && ./install.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Non-interactive / CI:
|
## Modes
|
||||||
```bash
|
|
||||||
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash -s -- --yes
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
| Mode | Enter | Leave |
|
||||||
|
|------|-------|-------|
|
||||||
|
| Normal | startup default | — |
|
||||||
|
| Insert | `i` / `a` / `o` | `Esc` or `jk` |
|
||||||
|
| Visual | `v` / `V` | `Esc` |
|
||||||
|
|
||||||
## Step 2: Open Vim
|
## Survival
|
||||||
|
|
||||||
```bash
|
|
||||||
vim # startup dashboard (recent files + sessions)
|
|
||||||
vim . # startup dashboard, current directory listed
|
|
||||||
vim myfile # edit a specific file
|
|
||||||
```
|
|
||||||
|
|
||||||
> **First launch:** Vim will automatically install plugins on the first open
|
|
||||||
> (takes 30–60 seconds depending on network). This is normal — wait for it
|
|
||||||
> to finish, then restart Vim.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Step 3: Set Up LSP
|
|
||||||
|
|
||||||
Open a source file, then run:
|
|
||||||
|
|
||||||
```vim
|
|
||||||
:LspInstallServer
|
|
||||||
```
|
|
||||||
|
|
||||||
This auto-detects the filetype and installs the correct language server.
|
|
||||||
vim-lsp itself runs on pure VimScript — no Node.js required. However,
|
|
||||||
some language servers (JS/TS, HTML, CSS, JSON, YAML) are npm packages
|
|
||||||
that need Node.js to run. Python, Go, and Rust servers don't need it.
|
|
||||||
|
|
||||||
Check status:
|
|
||||||
```vim
|
|
||||||
:LspStatus
|
|
||||||
```
|
|
||||||
|
|
||||||
**Markdown LSP** (`marksman`) needs a standalone binary:
|
|
||||||
```bash
|
|
||||||
brew install marksman # macOS
|
|
||||||
sudo pacman -S marksman # Arch
|
|
||||||
# install.sh handles this automatically
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## The Keys That Matter
|
|
||||||
|
|
||||||
```
|
```
|
||||||
,? Open cheat sheet (all bindings in one place)
|
Esc / jk back to Normal
|
||||||
Esc / jk Exit insert mode → Normal
|
,w save
|
||||||
Ctrl+s Save
|
,x save + quit
|
||||||
Ctrl+p Fuzzy find file
|
:q! force quit
|
||||||
,e File browser (netrw)
|
Ctrl+s save from any mode
|
||||||
gd Go to definition
|
,? cheat sheet
|
||||||
K Show documentation
|
:ChopsticksLearn interactive tutorial
|
||||||
[g / ]g Prev / next LSP diagnostic
|
|
||||||
,rn Rename symbol
|
|
||||||
,rG Search word under cursor (ripgrep)
|
|
||||||
,gs Git status
|
|
||||||
,mp Markdown live preview in browser
|
|
||||||
,w / ,x Save / Save+quit
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## Find things
|
||||||
|
|
||||||
## Daily Use
|
|
||||||
|
|
||||||
### Navigate Code
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `gd` | Go to definition |
|
|
||||||
| `gy` | Go to type definition |
|
|
||||||
| `gi` | Go to implementation |
|
|
||||||
| `gr` | List references |
|
|
||||||
| `K` | Docs for symbol under cursor |
|
|
||||||
| `Ctrl+o` | Jump back |
|
|
||||||
| `Ctrl+i` | Jump forward |
|
|
||||||
|
|
||||||
### Edit Code
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `Tab` | Select next completion item |
|
|
||||||
| `Enter` | Confirm completion |
|
|
||||||
| `gc` | Toggle comment (visual mode too) |
|
|
||||||
| `cs"'` | Change surrounding `"` to `'` |
|
|
||||||
| `ds(` | Delete surrounding `(` |
|
|
||||||
| `s` + 2 chars | EasyMotion: jump anywhere |
|
|
||||||
|
|
||||||
### Manage Errors
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `]g` | Jump to next LSP diagnostic |
|
|
||||||
| `[g` | Jump to previous diagnostic |
|
|
||||||
| `K` | Read the error message |
|
|
||||||
| `,ca` | Apply code action / auto-fix |
|
|
||||||
| `,cr` | Run current file (auto-detects language) |
|
|
||||||
|
|
||||||
### Markdown & Writing
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `,mp` | Open live preview in browser |
|
|
||||||
| `,mt` | Table of contents (side window) |
|
|
||||||
| `,zen` | Zen mode (Goyo + Limelight) |
|
|
||||||
| `zr` / `zm` | Unfold / fold all headings |
|
|
||||||
|
|
||||||
Formatting in the buffer is live: `**bold**` renders as bold,
|
|
||||||
headings hide their `#` markers. Raw syntax reappears when
|
|
||||||
the cursor enters that line.
|
|
||||||
|
|
||||||
### Git Workflow
|
|
||||||
|
|
||||||
```
|
```
|
||||||
,gs git status (stage with 's', commit with 'cc')
|
Ctrl+p fuzzy find file (git-aware)
|
||||||
,gd diff current file
|
,rg ripgrep project
|
||||||
,gb blame
|
,b search buffers
|
||||||
,gc commit
|
,fh recent files
|
||||||
,gp push
|
,e file browser
|
||||||
,gl pull
|
,, last file
|
||||||
[x / ]x navigate conflict markers
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## Write code
|
||||||
|
|
||||||
## Quick Reference Card
|
|
||||||
|
|
||||||
```
|
```
|
||||||
BASICS
|
gd go to definition
|
||||||
Esc / jk Exit insert mode → Normal
|
K hover docs
|
||||||
Ctrl+s Save
|
,rn rename symbol
|
||||||
:q! + Enter Emergency quit
|
,ca code action
|
||||||
,? Open cheat sheet
|
,f format
|
||||||
|
,cr run current file
|
||||||
FILES
|
Tab / S-Tab cycle completions
|
||||||
Ctrl+p Fuzzy find file (git-aware)
|
|
||||||
,e File browser (netrw)
|
|
||||||
,b Search open buffers
|
|
||||||
,rg Search file contents (ripgrep)
|
|
||||||
,rG Ripgrep word under cursor
|
|
||||||
,w Save | ,q Quit | ,x Save+quit
|
|
||||||
,wa Save all buffers
|
|
||||||
,, Switch to last file
|
|
||||||
|
|
||||||
CODE
|
|
||||||
gd Definition | gy Type def | gi Impl | gr References
|
|
||||||
K Show documentation
|
|
||||||
[g / ]g Prev / next LSP diagnostic
|
|
||||||
[e / ]e Prev / next ALE error
|
|
||||||
,rn Rename ,ca Code action ,f Format
|
|
||||||
,cr Run current file
|
|
||||||
|
|
||||||
SEARCH
|
|
||||||
,rg Ripgrep ,rG Ripgrep word ,fh Recent files
|
|
||||||
,fl Lines in buffer ,fc Commands ,fm Marks
|
|
||||||
/text Forward | ?text Backward | n next | N prev
|
|
||||||
// Search visually selected text
|
|
||||||
,* Replace word under cursor (file-wide)
|
|
||||||
|
|
||||||
MARKDOWN
|
|
||||||
,mp Preview | ,mt TOC | ,zen Zen mode
|
|
||||||
|
|
||||||
GIT
|
|
||||||
,gs Status ,gd Diff ,gb Blame
|
|
||||||
,gc Commit ,gp Push ,gl Pull
|
|
||||||
[x / ]x Navigate conflict markers
|
|
||||||
|
|
||||||
WINDOWS
|
|
||||||
Ctrl+h/j/k/l Navigate splits and tmux panes
|
|
||||||
,z Maximize / restore window
|
|
||||||
,h / ,l Prev / next buffer
|
|
||||||
,tv / ,th Terminal (vertical / horizontal)
|
|
||||||
Esc Esc Exit terminal mode
|
|
||||||
]q / [q Next / prev quickfix entry
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
Install language servers with `:LspInstallServer` (auto-detects filetype).
|
||||||
|
|
||||||
See [README.md](README.md) for the complete reference.
|
## Git
|
||||||
|
|
||||||
|
```
|
||||||
|
,gs status (s=stage, cc=commit)
|
||||||
|
,gd diff
|
||||||
|
,gb blame
|
||||||
|
,gp push
|
||||||
|
]x / [x conflict markers
|
||||||
|
```
|
||||||
|
|
||||||
|
## Edit
|
||||||
|
|
||||||
|
```
|
||||||
|
s + 2 chars EasyMotion jump
|
||||||
|
gc toggle comment
|
||||||
|
cs"' change surrounding " to '
|
||||||
|
Alt+j / Alt+k move line
|
||||||
|
,u undo tree
|
||||||
|
,y clipboard yank
|
||||||
|
```
|
||||||
|
|
||||||
|
## Navigate
|
||||||
|
|
||||||
|
```
|
||||||
|
Ctrl+h/j/k/l splits + tmux panes
|
||||||
|
,h / ,l prev / next buffer
|
||||||
|
,z maximize window
|
||||||
|
,tv / ,th terminal
|
||||||
|
```
|
||||||
|
|
||||||
|
## Write prose
|
||||||
|
|
||||||
|
```
|
||||||
|
,zen zen mode (Goyo + Limelight)
|
||||||
|
,mp markdown preview in browser
|
||||||
|
,mt table of contents
|
||||||
|
```
|
||||||
|
|
||||||
|
See [README](README.md) for the full reference. See the [wiki](https://github.com/m1ngsama/chopsticks/wiki) for deep dives.
|
||||||
|
|
|
||||||
334
README.md
334
README.md
|
|
@ -1,329 +1,127 @@
|
||||||
# chopsticks
|
# chopsticks
|
||||||
|
|
||||||
> Flowing vim for any machine — SSH servers included.
|
Vim config for people who ship code on any machine. Pure VimScript. No Node.js. Works over SSH.
|
||||||
|
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
[](https://www.vim.org/)
|
[](https://www.vim.org/)
|
||||||
[](#installation)
|
[](#install)
|
||||||
[](https://github.com/m1ngsama/chopsticks/releases)
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
|
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## Why
|
||||||
|
|
||||||
## What You Get
|
You SSH into a box. You need to edit code. You want LSP, fuzzy find, git integration, format-on-save — not a 20-minute setup ritual.
|
||||||
|
|
||||||
**30 plugins. One command. Zero Node.js dependency.**
|
chopsticks gives you 30 plugins, 12 modules, and a sane config in one command. It degrades gracefully on TTY. It works the same on your MacBook and your Arch server.
|
||||||
|
|
||||||
| Feature | What it does |
|
## What's in the box
|
||||||
|---------|-------------|
|
|
||||||
| **LSP everywhere** | Completion, go-to-definition, hover docs, rename — pure VimScript, works over SSH |
|
|
||||||
| **Format on save** | ALE runs black, prettier, gofmt automatically. Errors show in statusline. |
|
|
||||||
| **Fuzzy everything** | Files, buffers, grep, tags, marks, command history — all via FZF with preview |
|
|
||||||
| **Zen mode** | Goyo + Limelight: distraction-free writing. `,zen` and the world disappears |
|
|
||||||
| **Run any file** | `,cr` detects filetype and runs it: Python, Go, Rust, JS, C, Shell, and more |
|
|
||||||
| **Smart indentation** | vim-sleuth auto-detects tabs vs spaces from existing files. No config needed. |
|
|
||||||
| **Yank highlight** | Yanked text flashes — instant visual feedback, never guess what you copied |
|
|
||||||
| **Search that clears** | Search highlights disappear after you stop moving. No more `,<cr>` spam. |
|
|
||||||
| **Git workflow** | Status, diff, blame, push, pull. Conflict marker navigation with `[x`/`]x`. |
|
|
||||||
| **Window maximize** | `,z` toggles current split to full screen and back. |
|
|
||||||
| **Sudo save** | `:w!!` when you forgot to open as root |
|
|
||||||
| **ALE in statusline** | Error and warning counts always visible — no surprises |
|
|
||||||
| **30+ key mappings** | Every common action is one or two keystrokes away. `,?` shows them all. |
|
|
||||||
| **TTY-aware** | SSH, console, slow connections — degrades gracefully, never breaks |
|
|
||||||
|
|
||||||
---
|
| | |
|
||||||
|
|-|-|
|
||||||
|
| **LSP** | completion, go-to-def, hover, rename, code actions — pure VimScript |
|
||||||
|
| **Lint + format** | ALE runs black, prettier, gofmt, rustfmt on save |
|
||||||
|
| **Fuzzy find** | files, buffers, grep, tags, marks, commands — FZF |
|
||||||
|
| **Git** | status, diff, blame, push, pull, conflict markers |
|
||||||
|
| **Zen mode** | `,zen` — Goyo + Limelight, distraction-free writing |
|
||||||
|
| **Run file** | `,cr` — auto-detects language, runs it |
|
||||||
|
| **TTY-aware** | degrades gracefully on SSH, console, slow links |
|
||||||
|
|
||||||
## Installation
|
## Install
|
||||||
|
|
||||||
### One command
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
|
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
|
||||||
```
|
```
|
||||||
|
|
||||||
### Git clone
|
Or manually:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
|
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
|
||||||
cd ~/.vim && ./install.sh
|
cd ~/.vim && ./install.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
### Non-interactive / CI
|
macOS (brew), Debian/Ubuntu (apt), Arch (pacman), Fedora (dnf).
|
||||||
|
|
||||||
```bash
|
Open vim. Plugins install on first launch. Restart when done.
|
||||||
curl -fsSL ... | bash -s -- --yes
|
|
||||||
```
|
|
||||||
|
|
||||||
**Supported:** macOS (Homebrew), Debian/Ubuntu (apt), Arch (pacman), Fedora (dnf).
|
## Keys
|
||||||
|
|
||||||
The installer detects your environment, installs vim-plug, plugins, and offers
|
Leader: `,` — press `,?` for the full cheat sheet.
|
||||||
system tools (ripgrep, fzf, ctags, shellcheck, marksman) plus language-specific
|
|
||||||
formatters and linters.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Mappings
|
|
||||||
|
|
||||||
**Leader key:** `,` (comma). Press `,?` to open the built-in cheat sheet.
|
|
||||||
|
|
||||||
### Files and Search
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `Ctrl+p` | Fuzzy file search — git-aware |
|
|
||||||
| `,b` | Search open buffers |
|
|
||||||
| `,rg` | Project-wide ripgrep search |
|
|
||||||
| `,rG` | Ripgrep word under cursor |
|
|
||||||
| `,fh` | Recent files history |
|
|
||||||
| `,fl` / `,fL` | Search lines in buffer / all buffers |
|
|
||||||
| `,fc` | Commands | `,fm` Marks |
|
|
||||||
| `,f/` / `,f:` | Search / command history |
|
|
||||||
| `,e` / `,E` | File browser / vertical split |
|
|
||||||
| `,,` | Switch to last file |
|
|
||||||
| `,cd` | Change CWD to current file's directory |
|
|
||||||
|
|
||||||
### Code Intelligence (vim-lsp)
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `gd` | Go to definition |
|
|
||||||
| `gy` | Type definition |
|
|
||||||
| `gi` | Implementation |
|
|
||||||
| `gr` | References |
|
|
||||||
| `K` | Hover documentation |
|
|
||||||
| `[g` / `]g` | Previous / next LSP diagnostic |
|
|
||||||
| `[e` / `]e` | Previous / next ALE error |
|
|
||||||
| `,rn` | Rename symbol |
|
|
||||||
| `,f` | Format buffer / selection |
|
|
||||||
| `,ca` | Code action |
|
|
||||||
| `,o` | File outline (symbols) |
|
|
||||||
| `,ws` | Workspace symbols |
|
|
||||||
| `,cr` | **Run current file** (auto-detects language) |
|
|
||||||
|
|
||||||
Install LSP servers on demand:
|
|
||||||
```vim
|
|
||||||
:LspInstallServer " auto-detects filetype
|
|
||||||
:LspStatus " check server status
|
|
||||||
```
|
|
||||||
|
|
||||||
| Language | Server |
|
|
||||||
|----------|--------|
|
|
||||||
| Python | pylsp |
|
|
||||||
| JS / TS | typescript-language-server |
|
|
||||||
| Go | gopls |
|
|
||||||
| Rust | rust-analyzer |
|
|
||||||
| C / C++ | clangd |
|
|
||||||
| Shell | bash-language-server |
|
|
||||||
| HTML / CSS / JSON / YAML | vscode-*-language-server |
|
|
||||||
| Markdown | marksman |
|
|
||||||
| SQL | sqls |
|
|
||||||
|
|
||||||
### Markdown and Writing
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `,zen` | **Zen mode** — Goyo + Limelight, distraction-free |
|
|
||||||
| `,mp` | Live browser preview (previm) |
|
|
||||||
| `,mt` | Table of contents |
|
|
||||||
| `zr` / `zm` | Unfold / fold all headings |
|
|
||||||
|
|
||||||
Markdown buffers automatically enable `wrap`, `spell`, and concealment
|
|
||||||
(bold renders as bold, headings hide `#` markers, raw syntax shows on cursor line).
|
|
||||||
|
|
||||||
### Git
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `,gs` | Status |
|
|
||||||
| `,gd` | Diff |
|
|
||||||
| `,gb` | Blame |
|
|
||||||
| `,gc` | Commit |
|
|
||||||
| `,gp` | Push |
|
|
||||||
| `,gl` | Pull |
|
|
||||||
| `[x` / `]x` | Navigate conflict markers |
|
|
||||||
|
|
||||||
### Editing
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `s` + 2 chars | EasyMotion — jump anywhere on screen |
|
|
||||||
| `gc` | Toggle comment (works in visual mode) |
|
|
||||||
| `Y` | Yank to end of line |
|
|
||||||
| `,y` / `,Y` | Yank to system clipboard |
|
|
||||||
| `Alt+j` / `Alt+k` | Move line down / up |
|
|
||||||
| `,u` | Undo tree (visual branch history) |
|
|
||||||
| `,F` | Re-indent entire file |
|
|
||||||
| `,W` | Strip trailing whitespace |
|
|
||||||
| `,*` | Search and replace word under cursor |
|
|
||||||
| `gV` | Reselect last paste |
|
|
||||||
| `//` | Search visual selection |
|
|
||||||
|
|
||||||
### Windows and Navigation
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `Ctrl+h/j/k/l` | Navigate Vim splits **and** tmux panes |
|
|
||||||
| `,z` | **Maximize / restore** current window |
|
|
||||||
| `,h` / `,l` | Previous / next buffer |
|
|
||||||
| `,bd` | Close buffer (keep window layout) |
|
|
||||||
| `,tv` / `,th` | Terminal (vertical / horizontal) |
|
|
||||||
| `Esc Esc` | Exit terminal mode |
|
|
||||||
| `]q` / `[q` | Next / previous quickfix entry |
|
|
||||||
| `Ctrl+d` / `Ctrl+u` | Half-page scroll, cursor centred |
|
|
||||||
|
|
||||||
### Quick Reference
|
|
||||||
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| `,?` | Open built-in cheat sheet |
|
|
||||||
| `jk` | Exit insert mode |
|
|
||||||
| `Ctrl+s` | Save (any mode) |
|
|
||||||
| `:w!!` | Sudo save |
|
|
||||||
| `,w` / `,x` / `,q` | Save / save+quit / quit |
|
|
||||||
| `,ev` / `,sv` | Edit / reload `~/.vimrc` |
|
|
||||||
| `,so` | Source current vim file |
|
|
||||||
| `F2` Paste | `F3` Line# | `F4` Relative# | `F6` Invisible chars |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
### Statusline
|
|
||||||
|
|
||||||
Native, hand-written. Solarized palette. Shows mode, file, git branch, filetype,
|
|
||||||
ALE error/warning count, and cursor position. Background matches tmux bar.
|
|
||||||
|
|
||||||
```
|
```
|
||||||
N ~/.vimrc [+] E:1 W:3 main [vim] 42:7 68%
|
Ctrl+p fuzzy find file gd go to definition
|
||||||
|
,rg ripgrep project K hover docs
|
||||||
|
,gs git status ,cr run current file
|
||||||
|
,zen zen mode ,f format
|
||||||
|
,w save ,q quit
|
||||||
|
jk exit insert mode ,? cheat sheet
|
||||||
```
|
```
|
||||||
|
|
||||||
Mode block changes colour: Normal=yellow, Insert=blue, Visual=magenta, Replace=red.
|
**Files** — `Ctrl+p` find / `,b` buffers / `,rg` grep / `,rG` grep word / `,fh` recent / `,e` browser / `,,` last file
|
||||||
|
|
||||||
### Smart Defaults
|
**Code** — `gd` def / `gy` type / `gi` impl / `gr` refs / `K` docs / `[g` `]g` diagnostics / `,rn` rename / `,ca` action / `,o` outline
|
||||||
|
|
||||||
- **vim-sleuth** auto-detects indentation from existing files
|
**Edit** — `s`+2ch jump / `gc` comment / `cs"'` surround / `Alt+j/k` move line / `,u` undo tree / `,y` clipboard / `,*` replace word
|
||||||
- **Yank highlight** flashes copied text for 150ms
|
|
||||||
- **Search highlight** auto-clears after cursor stops moving
|
|
||||||
- **QuickFix** auto-opens after `:grep`, `:make`, or `:Rg`
|
|
||||||
- **Format on save** via ALE (black, prettier, gofmt, rustfmt, etc.)
|
|
||||||
- **Auto-create directories** on save — write to `new/path/file.txt` without `mkdir` first
|
|
||||||
- **Cursor restore** — reopens files at the last cursor position
|
|
||||||
|
|
||||||
### Session Management
|
**Git** — `,gs` status / `,gd` diff / `,gb` blame / `,gc` commit / `,gp` push / `]x` `[x` conflict markers
|
||||||
|
|
||||||
|
**Windows** — `Ctrl+hjkl` navigate (+ tmux) / `,z` maximize / `,h` `,l` buffers / `,tv` `,th` terminal / `Esc Esc` exit terminal
|
||||||
|
|
||||||
|
## LSP
|
||||||
|
|
||||||
```vim
|
```vim
|
||||||
:Obsess " start tracking the current session
|
:LspInstallServer " auto-detects filetype
|
||||||
:Obsess! " stop tracking
|
:LspStatus " check what's running
|
||||||
```
|
```
|
||||||
|
|
||||||
Sessions auto-restore when you open Vim in the same directory.
|
pylsp, gopls, rust-analyzer, clangd, marksman — no Node.js. JS/TS servers need Node.
|
||||||
|
|
||||||
### TTY / SSH Support
|
ALE and vim-lsp coexist cleanly (`ale_disable_lsp=1`). ALE handles linting + formatting. vim-lsp handles everything else.
|
||||||
|
|
||||||
Detected automatically. In TTY mode:
|
|
||||||
- True colour and cursorline disabled
|
|
||||||
- FZF preview windows disabled
|
|
||||||
- IndentLine guides disabled
|
|
||||||
- Simplified statusline
|
|
||||||
- Syntax column limit reduced
|
|
||||||
|
|
||||||
### Large File Handling
|
|
||||||
|
|
||||||
Files over 10 MB: syntax highlighting, undo history, and linting automatically disabled.
|
|
||||||
|
|
||||||
### Project-Local Config
|
|
||||||
|
|
||||||
```vim
|
|
||||||
" my-project/.vimrc
|
|
||||||
set shiftwidth=2
|
|
||||||
let g:ale_python_black_options = '--line-length=100'
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Plugins (30)
|
|
||||||
|
|
||||||
| Category | Plugins |
|
|
||||||
|----------|---------|
|
|
||||||
| **Navigation** | fzf, fzf.vim |
|
|
||||||
| **Git** | vim-fugitive, vim-gitgutter |
|
|
||||||
| **LSP** | vim-lsp, vim-lsp-settings, asyncomplete.vim, asyncomplete-lsp.vim |
|
|
||||||
| **Lint/Format** | ALE |
|
|
||||||
| **Editing** | vim-surround, vim-commentary, vim-repeat, vim-unimpaired, vim-sleuth, targets.vim, auto-pairs, vim-easymotion |
|
|
||||||
| **Language** | vim-javascript, yats.vim, vim-markdown, vim-go |
|
|
||||||
| **Writing** | previm, goyo.vim, limelight.vim |
|
|
||||||
| **UI** | vim-solarized8, undotree, vim-startify, indentLine |
|
|
||||||
| **Session** | vim-obsession, vim-tmux-navigator |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Learn
|
|
||||||
|
|
||||||
New to chopsticks? Run the interactive tutorial:
|
|
||||||
|
|
||||||
```vim
|
|
||||||
:ChopsticksLearn
|
|
||||||
```
|
|
||||||
|
|
||||||
It walks you through every feature — file finding, LSP, git, zen mode,
|
|
||||||
and more — with exercises you can try in real time. (For Vim basics, run
|
|
||||||
`:Tutor` first.)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
chopsticks follows the Unix philosophy: each concern lives in its own file.
|
|
||||||
|
|
||||||
```
|
```
|
||||||
~/.vim/
|
~/.vim/
|
||||||
├── .vimrc ← thin loader (sources modules in order)
|
├── .vimrc thin loader
|
||||||
├── modules/
|
├── modules/
|
||||||
│ ├── env.vim ← environment detection (TTY, truecolor)
|
│ ├── env.vim TTY detection, truecolor
|
||||||
│ ├── plugins.vim ← vim-plug bootstrap + 30 plugin declarations
|
│ ├── plugins.vim vim-plug + 30 plugins
|
||||||
│ ├── core.vim ← general settings, keymaps, performance
|
│ ├── core.vim settings, keymaps, performance
|
||||||
│ ├── ui.vim ← colorscheme, statusline, startify
|
│ ├── ui.vim colorscheme, statusline, startify
|
||||||
│ ├── editing.vim ← EasyMotion, yank highlight, search auto-clear
|
│ ├── editing.vim easymotion, yank highlight
|
||||||
│ ├── navigation.vim ← FZF, netrw, window management, terminal
|
│ ├── navigation.vim fzf, netrw, windows, terminal
|
||||||
│ ├── lsp.vim ← vim-lsp + asyncomplete
|
│ ├── lsp.vim vim-lsp, asyncomplete
|
||||||
│ ├── lint.vim ← ALE linting and format-on-save
|
│ ├── lint.vim ale, format-on-save
|
||||||
│ ├── git.vim ← Fugitive, GitGutter, conflict navigation
|
│ ├── git.vim fugitive, gitgutter
|
||||||
│ ├── writing.vim ← Markdown, previm, goyo + limelight
|
│ ├── writing.vim markdown, previm, zen mode
|
||||||
│ ├── languages.vim ← vim-go, per-filetype settings
|
│ ├── languages.vim vim-go, filetype settings
|
||||||
│ └── tools.vim ← cheat sheet, run file, helpers
|
│ └── tools.vim cheat sheet, run file, helpers
|
||||||
└── tutor/
|
└── tutor/
|
||||||
└── chopsticks.tutor ← interactive tutorial
|
└── chopsticks.tutor
|
||||||
```
|
```
|
||||||
|
|
||||||
Each module is self-contained. Want to disable git integration? Remove
|
Each module is self-contained. Comment out `call s:load('git')` in `.vimrc` to disable git. Add `call s:load('mine')` to load your own.
|
||||||
`call s:load('git')` from `.vimrc`. Want to add your own module? Create
|
|
||||||
`modules/mine.vim` and add `call s:load('mine')`.
|
|
||||||
|
|
||||||
---
|
## Learn
|
||||||
|
|
||||||
## Customization
|
```vim
|
||||||
|
:ChopsticksLearn " interactive tutorial — 10 lessons
|
||||||
Edit `~/.vimrc` directly (`,ev` opens it, `,sv` reloads), or edit individual
|
:Tutor " vim basics (if needed first)
|
||||||
modules under `modules/`. Per-project overrides go in a `.vimrc` at your
|
,? " cheat sheet
|
||||||
project root.
|
```
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
| Problem | Solution |
|
| Problem | Fix |
|
||||||
|---------|----------|
|
|---------|-----|
|
||||||
| Plugins not loading | `:PlugInstall` then `:PlugUpdate` |
|
| Plugins not loading | `:PlugInstall` then `:PlugUpdate` |
|
||||||
| LSP not starting | `:LspInstallServer` for current filetype |
|
| LSP not starting | `:LspInstallServer` for current filetype |
|
||||||
| Colors look wrong | `export COLORTERM=truecolor` in your shell rc |
|
| Colors wrong | `export COLORTERM=truecolor` in shell rc |
|
||||||
| ALE linters missing | `which flake8 black prettier eslint` to verify PATH |
|
| `Ctrl+s` freezes | `stty -ixon` in shell rc |
|
||||||
| `Ctrl+s` freezes terminal | Add `stty -ixon` to `~/.bashrc` or `~/.zshrc` |
|
| Everything slow | Large file? Check `:echo &syntax` — auto-disabled >10MB |
|
||||||
| Markdown preview broken | Ensure `open` (macOS) or `xdg-open` (Linux) works |
|
|
||||||
|
|
||||||
---
|
More in the [wiki](https://github.com/m1ngsama/chopsticks/wiki).
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue