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

Align docs with expert Vim workflow

Browse source
This commit is contained in:
m1ngsama 2026-05-23 23:29:56 +08:00
parent a6a101a286
commit d3a137a36e
10 changed files with 113 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
.github/demo.gif vendored
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 949 KiB

After

Width:  |  Height:  |  Size: 1.1 MiB

28
.github/demo.tape vendored
View file

@ -1,5 +1,6 @@
# chopsticks demo — the project loop stock Vim does not assemble for you:
# visible jump → file finder → run file → project grep → active key help.
# chopsticks demo — for people who already know Vim:
# show the project workflow layer Vim does not assemble by default.
# project loop: visible jump → files → run → grep → git → active key help.
# Rule: NEVER use Escape to close FZF — always Enter (deterministic).
# Pacing: hold each scene long enough for the viewer to read.
@ -30,15 +31,18 @@ Type "cd $CHOPSTICKS_DEMO_PROJECT"
Enter
Type "git init -q && git symbolic-ref HEAD refs/heads/main && git add ."
Enter
Type `clear && printf "%s\n" "chopsticks: a long-term Vim efficiency kit" "" "For experienced Vim users who already know how to edit." "Keep Vim's language. Standardize the project loop:" "" " s + 2 chars visible jump on the current screen" " SPC SPC project-aware file switcher" " SPC rr run the current file" " SPC / ripgrep the project" " SPC gs git status, with no push/pull hotkeys" " SPC ? active keys explained inside Vim"`
Enter
Show
Sleep 6s
Type "clear"
Enter
Type `vim -Nu "$CHOPSTICKS_ROOT/.vimrc" server.py`
Enter
Wait+Screen /server.py/
Show
Sleep 1s
# ── 1. Pain: moving inside a dense screen should not mean counting hjkl ────
# ── 1. Screen-local motion: stop counting hjkl across dense code ───────────
Type "s"
Sleep 0.5s
Type "di"
@ -46,7 +50,7 @@ Sleep 2s
Ctrl+C
Sleep 1s
# ── 2. Pain: project files should be one habit, not :find/:edit plumbing ───
# ── 2. Project files: one habit for git-aware file switching ───────────────
Space 2
Sleep 1.5s
Type "report"
@ -54,14 +58,14 @@ Sleep 2s
Enter
Sleep 3s
# ── 3. Pain: edit→run should be one repeatable project loop ────────────────
# ── 3. Edit-run loop: run the current file without leaving Vim ─────────────
Space
Type "rr"
Sleep 4s
Enter
Sleep 1s
# ── 4. Pain: project search should not leave Vim or require remembering rg ─
# ── 4. Project grep: ripgrep as part of the same muscle-memory layer ───────
Space
Type "/"
Sleep 1s
@ -70,7 +74,15 @@ Sleep 2.5s
Enter
Sleep 3s
# ── 5. Pain: custom keymaps must explain themselves in the editor ──────────
# ── 5. Git boundary: status is fast; push/pull stay explicit commands ──────
Space
Type "gs"
Sleep 3s
Type ":bd!"
Enter
Sleep 1s
# ── 6. Self-documenting config: no private wiki required ───────────────────
Space
Type "?"
Sleep 5.5s

9
BETA.md
View file

@ -1,6 +1,8 @@
# Beta Testing
This branch is the v3 beta candidate. Do not tag or publish it as `v3.0.0`
This branch is the v3 beta candidate. The goal is to prove that the Space
layout can serve as a long-term project loop for experienced Vim users, not
just that the mappings work in isolation. Do not tag or publish it as `v3.0.0`
until the checklist below is closed.
Inside Vim, run `:ChopsticksBeta` for the compact checklist,
@ -40,7 +42,9 @@ reloads chopsticks after saving it.
## Daily test loop
Use the beta for real editing, not only demos. For each session, record:
Use the beta for real editing, not only demos. A session should exercise the
trained loop until it either feels automatic or exposes friction. For each
session, record:
- The task: project navigation, code edit, grep, git, LSP, Markdown, SSH.
- The first key you tried when you got stuck.
@ -74,6 +78,7 @@ file, edit Markdown, and use a machine with missing optional tools.
- No high-frequency action requires remembering an undocumented key.
- README, QUICKSTART, `:help chopsticks`, `SPC ?`, and `:ChopsticksTutor`
teach the same layout.
- No private wiki or external note is needed to remember the daily loop.
- `scripts/test.sh quick` and `scripts/test.sh vim` pass locally.
- The README GIF has been regenerated from `.github/demo.tape` after any public
key change.

26
QUICKSTART.md
View file

@ -1,6 +1,11 @@
# Quick Start
Five minutes from zero to a working Vim setup.
Five minutes to understand the chopsticks project loop.
This guide assumes you already know Vim's editing language. chopsticks keeps
that language intact and gives you one stable layer for the work around it:
jump on the visible screen, switch project files, grep, run, inspect code,
check git, and ask Vim which keys are active.
## Install
@ -35,13 +40,20 @@ To switch later without reinstalling anything:
cd ~/.vim && ./install.sh --configure-only --profile=full
```
## Modes
## Daily loop
| Mode | Enter | Leave |
| ------ | --------------- | ------------- |
| Normal | startup default | — |
| Insert | `i` / `a` / `o` | `Esc` |
| Visual | `v` / `V` | `Esc` |
Train this first. It is the core reason to use chopsticks instead of assembling
the same pieces yourself:
```
SPC SPC open a project file
s + 2 chars jump to visible text
gd / gr / K inspect definition, references, docs
SPC rr run the current file
SPC / grep the project
SPC gs check git status
SPC ? show the active keymap
```
## Survival

18
README.md
View file

@ -1,13 +1,13 @@
<p align="center">
<img src=".github/demo.gif" alt="chopsticks demo" width="720">
<br>
<sub>One project loop: jump on screen, find a file, run it, grep the codebase, then ask Vim what keys are active.</sub>
<sub>For Vim users who already know how to edit: one trained project loop for jump, files, run, grep, git, and active key help.</sub>
</p>
<h1 align="center">chopsticks</h1>
<p align="center">
<strong>A project-work Vim setup: find, jump, run, grep, git, LSP, and self-documenting keys over SSH.</strong>
<strong>A long-term Vim efficiency kit: find, jump, run, grep, git, LSP, and self-documenting keys over SSH.</strong>
</p>
<p align="center">
@ -34,7 +34,11 @@ keymap before promotion.
## Why
Stock Vim is a great editor core, but it does not ship a complete project
chopsticks is for experienced Vim users who want one stable, ergonomic working
set they can train once and keep for years. It does not replace Vim's editing
language; it standardizes the project loop around it.
Stock Vim is a great editor core, but it does not ship that complete project
workflow. You still have to assemble fuzzy finding, project grep, git, LSP,
diagnostics, formatters, runners, terminal behavior, and a keymap that will not
collapse over SSH.
@ -145,10 +149,10 @@ Git push/pull are intentionally not bound to default hotkeys. Normal-mode `s`
is a screen-local EasyMotion jump; use `cl` for native `s` substitute and `cc`
for native `S`.
For onboarding, use `:ChopsticksHelp` / `:help chopsticks` for full native Vim
help, `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active
keymap, `:ChopsticksConfig` for local preferences, and `:ChopsticksStatus` for
tool/LSP health.
For learning the kit, use `:ChopsticksTutor` to train the core loop, `SPC ?`
for the active keymap, `:ChopsticksHelp` / `:help chopsticks` for full native
Vim help, `:ChopsticksConfig` for local preferences, and `:ChopsticksStatus`
for tool/LSP health.
`QUICKSTART.md` is the 5-minute path; this README is the full reference.
During the beta, `:ChopsticksBeta` opens the in-editor test checklist,
`:ChopsticksBetaLog` opens editable local notes, and `:ChopsticksBetaSession`

9
doc/chopsticks.txt
View file

@ -1,4 +1,4 @@
*chopsticks.txt* *chopsticks* A project-work Vim setup
*chopsticks.txt* *chopsticks* A long-term Vim efficiency kit
==============================================================================
CONTENTS *chopsticks-contents*
@ -14,9 +14,10 @@ CONTENTS *chopsticks-contents
==============================================================================
WHAT CHOPSTICKS SOLVES *chopsticks-why*
Chopsticks is a complete Vim project loop for people who edit locally and over
SSH. It connects fuzzy find, project grep, git, LSP, linting, formatting,
runners, quickfix navigation, and self-documenting keys.
Chopsticks is for experienced Vim users who want one stable, ergonomic working
set they can train once and keep for years. It connects fuzzy find, project
grep, git, LSP, linting, formatting, runners, quickfix navigation, and
self-documenting keys for people who edit locally and over SSH.
It is meant to supplement stock Vim, not replace Vim muscle memory. Native
motions and well-known conventions stay where they are useful: gd, gr, K,

5
modules/beta.vim
View file

@ -19,8 +19,8 @@ function! s:OpenBetaGuide() abort
\ ' ─────────────────────────────',
\ '',
\ ' goal',
\ ' Prove the v3 Space layout in real editing before release.',
\ ' Record friction, not opinions in the abstract.',
\ ' Prove this can be a long-term project loop.',
\ ' Record real editing friction, not abstract taste.',
\ '',
\ ' daily loop',
\ ' SPC SPC find file',
@ -44,6 +44,7 @@ function! s:OpenBetaGuide() abort
\ ' s as jump still feels worth the native override',
\ ' no high-frequency action needs an undocumented key',
\ ' README, QUICKSTART, SPC ?, and tutor teach the same layout',
\ ' no private wiki is needed to remember the daily loop',
\ ' quick/vim tests pass locally and over SSH',
\ '',
\ ' files',

8
modules/cheatsheet.vim
View file

@ -29,6 +29,10 @@ function! s:CheatSheet() abort
\ ' chopsticks <Space>? close',
\ ' ─────────────────────────────────',
\ '',
\ ' trained loop:',
\ ' files → s jump → gd/K',
\ ' run → grep → git',
\ '',
\ ' ── fast path ─────────────',
\ ' SPC SPC files',
\ ' SPC , buffers',
@ -166,6 +170,10 @@ function! s:CheatSheet() abort
\ ' chopsticks ,? close',
\ ' ─────────────────────────────',
\ '',
\ ' trained loop:',
\ ' files → jump → inspect',
\ ' run → grep → git',
\ '',
\ ' ── files ──────────────────',
\ ' ,ff files',
\ ' ,b buffers',

28
modules/tutor.vim
View file

@ -23,9 +23,20 @@ function! s:ChopsticksTutor() abort
\ ' chopsticks tutor q close',
\ ' ───────────────────────────────',
\ '',
\ ' 1. survival',
\ ' Esc Normal mode',
\ ' Goal: train one long-term project loop around Vim.',
\ ' Keep Vim editing habits; standardize the surrounding work.',
\ '',
\ ' 1. trained loop',
\ ' SPC SPC open a project file',
\ ' s + 2 chars jump to visible text',
\ ' gd / gr / K inspect definition / refs / docs',
\ ' SPC rr run current file',
\ ' SPC / grep project',
\ ' SPC gs check git status',
\ ' SPC ? active cheat sheet',
\ '',
\ ' 2. survival',
\ ' Esc Normal mode',
\ ' SPC w save',
\ ' SPC qx save and quit',
\ ' SPC fc edit local config',
@ -38,42 +49,43 @@ function! s:ChopsticksTutor() abort
\ ' :ChopsticksBetaLog beta notes',
\ ' :ChopsticksBetaSession new note',
\ '',
\ ' 2. find and switch',
\ ' 3. find and switch',
\ ' SPC SPC find files',
\ ' SPC / grep project',
\ ' SPC , buffers',
\ ' SPC Tab alternate buffer',
\ ' SPC e/E sidebar cwd / file dir',
\ '',
\ ' 3. jump and edit',
\ ' 4. jump and edit',
\ ' s + 2 chars visible jump',
\ ' SPC S same jump fallback',
\ ' cl / cc native s / S substitute',
\ ' gc comment',
\ ' SPC U undo tree',
\ '',
\ ' 4. code loop',
\ ' 5. code loop',
\ ' gd / gr / K definition / refs / docs',
\ ' gI / gy implementation / type',
\ ' [d ]d LSP diagnostics',
\ ' SPC ca/cr/cf action / rename / format',
\ ' SPC rr run current file',
\ '',
\ ' 5. git and windows',
\ ' 6. git and windows',
\ ' SPC gs/gd/gb status / diff / blame',
\ ' SPC gl log graph',
\ ' <C-w>hjkl split navigation',
\ ' SPC z maximize split',
\ '',
\ ' daily drill',
\ ' Open a project, run SPC SPC, jump with s, inspect with gd/K,',
\ ' edit with gc/SPC cf, check SPC gs, then save with SPC w.',
\ ' Repeat: SPC SPC, s, gd/K, edit, SPC rr, SPC /, SPC gs.',
\ ]
else
let l:lines = [
\ ' chopsticks tutor q close',
\ ' ───────────────────────────────',
\ '',
\ ' Goal: train one long-term project loop around Vim.',
\ '',
\ ' classic layout',
\ ' ,? active cheat sheet',
\ ' ,w / ,x save / save and quit',

21
scripts/test-vim.sh
View file

@ -268,11 +268,15 @@ check_vim() {
XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
-c 'call feedkeys("\<Space>?", "xt")' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
-c "redir! > $TMP_ROOT/cheat-default.txt" \
-c 'silent %print' \
-c 'redir END' \
-c 'qa!' 2>&1
grep -Fq ':ChopsticksStatus check LSP setup' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'trained loop:' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'files → s jump → gd/K' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'run → grep → git' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'SPC SPC files' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'gd definition' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'K hover docs' "$TMP_ROOT/cheat-default.txt"
@ -296,6 +300,7 @@ check_vim() {
XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
-c 'ChopsticksCheatSheet' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
-c "redir! > $TMP_ROOT/cheat-command.txt" \
-c 'silent %print' \
-c 'redir END' \
@ -307,11 +312,15 @@ check_vim() {
-c 'let g:chopsticks_keymap_style = "classic"' \
-c 'source .vimrc' \
-c 'normal ,?' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
-c "redir! > $TMP_ROOT/cheat-classic.txt" \
-c 'silent %print' \
-c 'redir END' \
-c 'qa!' 2>&1
grep -Fq ',ff files' "$TMP_ROOT/cheat-classic.txt"
grep -Fq 'trained loop:' "$TMP_ROOT/cheat-classic.txt"
grep -Fq 'files → jump → inspect' "$TMP_ROOT/cheat-classic.txt"
grep -Fq 'run → grep → git' "$TMP_ROOT/cheat-classic.txt"
grep -Fq ',dd definition' "$TMP_ROOT/cheat-classic.txt"
grep -Fq ',dk hover docs' "$TMP_ROOT/cheat-classic.txt"
grep -Fq ',dp ,dn LSP diagnostics' "$TMP_ROOT/cheat-classic.txt"
@ -326,6 +335,7 @@ check_vim() {
-c 'let g:chopsticks_profile = "minimal"' \
-c 'source .vimrc' \
-c 'call feedkeys("\<Space>?", "xt")' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
-c "redir! > $TMP_ROOT/cheat.txt" \
-c 'silent %print' \
-c 'redir END' \
@ -340,6 +350,7 @@ check_vim() {
-c 'let g:chopsticks_keymap_style = "space"' \
-c 'source .vimrc' \
-c 'call feedkeys("\<Space>?", "xt")' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
-c "redir! > $TMP_ROOT/cheat-space.txt" \
-c 'silent %print' \
-c 'redir END' \
@ -356,11 +367,14 @@ check_vim() {
XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
-c 'ChopsticksTutor' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \
-c "redir! > $TMP_ROOT/tutor-default.txt" \
-c 'silent %print' \
-c 'redir END' \
-c 'qa!' 2>&1
grep -Fq 'chopsticks tutor' "$TMP_ROOT/tutor-default.txt"
grep -Fq 'Goal: train one long-term project loop around Vim.' "$TMP_ROOT/tutor-default.txt"
grep -Fq '1. trained loop' "$TMP_ROOT/tutor-default.txt"
grep -Fq 'SPC ? active cheat sheet' "$TMP_ROOT/tutor-default.txt"
grep -Fq 'SPC fc edit local config' "$TMP_ROOT/tutor-default.txt"
grep -Fq ':ChopsticksHelp full help' "$TMP_ROOT/tutor-default.txt"
@ -373,23 +387,28 @@ check_vim() {
-c 'let g:chopsticks_keymap_style = "classic"' \
-c 'source .vimrc' \
-c 'ChopsticksTutor' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \
-c "redir! > $TMP_ROOT/tutor-classic.txt" \
-c 'silent %print' \
-c 'redir END' \
-c 'qa!' 2>&1
grep -Fq 'classic layout' "$TMP_ROOT/tutor-classic.txt"
grep -Fq 'Goal: train one long-term project loop around Vim.' "$TMP_ROOT/tutor-classic.txt"
grep -Fq ',? active cheat sheet' "$TMP_ROOT/tutor-classic.txt"
grep -Fq ',ec edit local config' "$TMP_ROOT/tutor-classic.txt"
grep -Fq ',S + 2 chars EasyMotion jump' "$TMP_ROOT/tutor-classic.txt"
XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
-c 'ChopsticksBeta' \
-c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \
-c "redir! > $TMP_ROOT/beta-guide.txt" \
-c 'silent %print' \
-c 'redir END' \
-c 'qa!' 2>&1
grep -Fq 'chopsticks beta' "$TMP_ROOT/beta-guide.txt"
grep -Fq 'Prove the v3 Space layout in real editing before release.' "$TMP_ROOT/beta-guide.txt"
grep -Fq 'Prove this can be a long-term project loop.' "$TMP_ROOT/beta-guide.txt"
grep -Fq 'Record real editing friction, not abstract taste.' "$TMP_ROOT/beta-guide.txt"
grep -Fq 'no private wiki is needed to remember the daily loop' "$TMP_ROOT/beta-guide.txt"
grep -Fq 'SPC ? active cheat sheet' "$TMP_ROOT/beta-guide.txt"
grep -Fq 'BETA.md full beta checklist and rollback' "$TMP_ROOT/beta-guide.txt"
grep -Fq ':ChopsticksBetaLog editable local beta notes' "$TMP_ROOT/beta-guide.txt"