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

Add native Vim help entrypoint

Browse source
This commit is contained in:
m1ngsama 2026-05-23 19:48:15 +08:00
parent a4ea56525f
commit 0b1c8d94d7
14 changed files with 278 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -5,5 +5,6 @@ __pycache__/
Session.vim
autoload/
plugged/
doc/tags
.swap/
.undo/

4
.vimrc
View file

@ -1,6 +1,9 @@
set nocompatible
let g:chopsticks_dir = fnamemodify(resolve(expand('<sfile>')), ':h')
if index(split(&runtimepath, ','), g:chopsticks_dir) < 0
let &runtimepath = g:chopsticks_dir . ',' . &runtimepath
endif
let s:xdg_config_home = !empty($XDG_CONFIG_HOME) && $XDG_CONFIG_HOME =~# '^/'
\ ? $XDG_CONFIG_HOME
\ : '~/.config'
@ -38,4 +41,5 @@ call s:load('status')
call s:load('cheatsheet')
call s:load('tutor')
call s:load('beta')
call s:load('help')
call s:load('tools')

6
BETA.md
View file

@ -5,7 +5,8 @@ until the checklist below is closed.
Inside Vim, run `:ChopsticksBeta` for the compact checklist,
`:ChopsticksBetaLog` for editable local notes, and `:ChopsticksBetaSession`
to append a new session block.
to append a new session block. Run `:ChopsticksHelp` or `:help chopsticks`
for the native Vim reference.
## Install the beta
@ -67,7 +68,8 @@ file, edit Markdown, and use a machine with missing optional tools.
- `s` as the default visible jump still feels worth the native override after
real editing.
- No high-frequency action requires remembering an undocumented key.
- README, QUICKSTART, `SPC ?`, and `:ChopsticksTutor` teach the same layout.
- README, QUICKSTART, `:help chopsticks`, `SPC ?`, and `:ChopsticksTutor`
teach the same layout.
- `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.

6
CHANGELOG.md
View file

@ -23,8 +23,12 @@
`[d`, and `]d`
- `:ChopsticksTutor` guided practice buffer for learning the final keymap
- `:ChopsticksCheatSheet` command, with `SPC ?` as the discoverable default
- `:ChopsticksHelp` and native `:help chopsticks` documentation for in-editor
support without a separate wiki
- `:ChopsticksBeta`, `:ChopsticksBetaLog`, and `:ChopsticksBetaSession` for
guided beta testing and local session notes
- Dedicated modules for buffers, utilities, files, runner, quickfix, status,
cheat sheet, and tutor
cheat sheet, tutor, beta testing, and help
- Split test runner: `scripts/test.sh` now dispatches to
`scripts/test-quick.sh` and `scripts/test-vim.sh`

8
QUICKSTART.md
View file

@ -51,6 +51,7 @@ SPC w save
SPC qx save + quit
:q! force quit
SPC ? cheat sheet (toggle sidebar)
:ChopsticksHelp full native help
```
Classic layout equivalents:
@ -61,6 +62,7 @@ Esc back to Normal
,x save + quit
:q! force quit
,? cheat sheet (toggle sidebar)
:ChopsticksHelp full native help
```
## Find things
@ -137,6 +139,7 @@ syntax. Enable the heavier Markdown tools only when you want them.
## Health check
```
:ChopsticksHelp full native Vim help
:ChopsticksTutor guided practice for the final keymap
:ChopsticksStatus see what's installed and what's missing
```
@ -144,5 +147,6 @@ syntax. Enable the heavier Markdown tools only when you want them.
The `SPC ?` cheat sheet follows your active profile, so `minimal` users only see
keys for features that are actually loaded.
See [README](README.md) for the full reference. For beta testing and rollback,
see [BETA.md](BETA.md).
Inside Vim, `:help chopsticks` opens the same reference after helptags are
available. See [README](README.md) for the full reference. For beta testing and
rollback, see [BETA.md](BETA.md).

60
README.md
View file

@ -48,9 +48,9 @@ That assembly work is the pain chopsticks removes:
`gd`, `gr`, `K`, `<C-w>hjkl`, `cl`, `cc`.
- **Remote editing is fragile.** It is built to degrade on TTY, slow SSH, and
headless machines instead of assuming a GUI desktop.
- **Custom configs are hard to onboard.** `SPC ?`, `:ChopsticksTutor`, and
`:ChopsticksStatus` make the active keymap and missing tools visible inside
Vim.
- **Custom configs are hard to onboard.** `:ChopsticksHelp`, `SPC ?`,
`:ChopsticksTutor`, and `:ChopsticksStatus` make the active keymap, full
help, and missing tools visible inside Vim.
You SSH into a server. You need to edit code. You want LSP, fuzzy find, git
integration, format-on-save — not a 20-minute setup.
@ -142,8 +142,9 @@ 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 `:ChopsticksTutor` for a guided practice page, `SPC ?` for
the active keymap, and `:ChopsticksStatus` for tool/LSP health.
For onboarding, use `:ChopsticksHelp` / `:help chopsticks` for full native Vim
help, `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active
keymap, 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`
@ -199,7 +200,7 @@ Esc exit insert mode SPC ? cheat sheet
### Survival
`SPC w` save | `SPC W` save all | `SPC qq` quit | `SPC qx` save and quit | `SPC ?` cheat sheet | `:ChopsticksTutor` practice | `:ChopsticksStatus` diagnostics
`SPC w` save | `SPC W` save all | `SPC qq` quit | `SPC qx` save and quit | `SPC ?` cheat sheet | `:ChopsticksHelp` full help | `:ChopsticksTutor` practice | `:ChopsticksStatus` diagnostics
</details>
@ -283,27 +284,30 @@ For Markdown LSP, install or select `marksman` first.
```
~/.vim/
├── .vimrc thin loader
├── modules/
│ ├── env.vim TTY detection, truecolor, skip built-in plugins
│ ├── plugins.vim vim-plug + 23–25 plugins
│ ├── core.vim settings, keymaps, performance
│ ├── ui.vim solarized, statusline, startify
│ ├── editing.vim easymotion, yank highlight, blank lines
│ ├── navigation.vim fzf, netrw sidebar, windows, terminal
│ ├── lsp.vim vim-lsp, asyncomplete
│ ├── lint.vim ale, format-on-save
│ ├── git.vim fugitive, gitgutter, conflict nav
│ ├── languages.vim vim-go, markdown, filetype settings
│ ├── buffers.vim buffer commands
│ ├── utilities.vim reindent, trim, clipboard, vimrc helpers
│ ├── files.vim auto mkdir, large-file protection
│ ├── runner.vim run current file
│ ├── quickfix.vim quickfix and location-list helpers
│ ├── status.vim :ChopsticksStatus diagnostics
│ ├── cheatsheet.vim SPC ? and :ChopsticksCheatSheet
│ ├── tutor.vim :ChopsticksTutor guided practice
│ ├── beta.vim :ChopsticksBeta test guide
│ └── tools.vim compatibility placeholder
├── doc/
│ └── chopsticks.txt :help chopsticks
└── modules/
├── env.vim TTY detection, truecolor, skip built-in plugins
├── plugins.vim vim-plug + 23–25 plugins
├── core.vim settings, keymaps, performance
├── ui.vim solarized, statusline, startify
├── editing.vim easymotion, yank highlight, blank lines
├── navigation.vim fzf, netrw sidebar, windows, terminal
├── lsp.vim vim-lsp, asyncomplete
├── lint.vim ale, format-on-save
├── git.vim fugitive, gitgutter, conflict nav
├── languages.vim vim-go, markdown, filetype settings
├── buffers.vim buffer commands
├── utilities.vim reindent, trim, clipboard, vimrc helpers
├── files.vim auto mkdir, large-file protection
├── runner.vim run current file
├── quickfix.vim quickfix and location-list helpers
├── status.vim :ChopsticksStatus diagnostics
├── cheatsheet.vim SPC ? and :ChopsticksCheatSheet
├── tutor.vim :ChopsticksTutor guided practice
├── beta.vim :ChopsticksBeta test guide
├── help.vim :ChopsticksHelp native Vim help
└── tools.vim compatibility placeholder
```
Each module is self-contained. Comment out one line in `.vimrc` to disable it. Add your own with `call s:load('mine')`.
@ -329,7 +333,7 @@ Each module is self-contained. Comment out one line in `.vimrc` to disable it. A
| What's installed? | `:ChopsticksStatus` shows tools, LSP, linters |
For deeper checks, start with `:ChopsticksStatus`, `SPC ?`,
`:ChopsticksTutor`, and [QUICKSTART.md](QUICKSTART.md).
`:ChopsticksTutor`, `:ChopsticksHelp`, and [QUICKSTART.md](QUICKSTART.md).
## Contributing

162
doc/chopsticks.txt Normal file
View file

@ -0,0 +1,162 @@
*chopsticks.txt* *chopsticks* A project-work Vim setup
==============================================================================
CONTENTS *chopsticks-contents*
1. What chopsticks solves...............|chopsticks-why|
2. First five minutes...................|chopsticks-start|
3. Canonical Space layout...............|chopsticks-v3-space|
4. Commands.............................|chopsticks-commands|
5. Profiles and local config............|chopsticks-profiles|
6. Beta testing.........................|chopsticks-beta|
7. Troubleshooting......................|chopsticks-troubleshooting|
==============================================================================
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.
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,
<C-w>hjkl, cl, cc, quickfix, and normal Vim commands.
==============================================================================
FIRST FIVE MINUTES *chopsticks-start*
Inside Vim:
>
:ChopsticksTutor guided practice page
SPC ? active keymap cheat sheet
:ChopsticksStatus tool, plugin, and LSP diagnostics
:ChopsticksHelp this help page
<
Daily loop:
>
SPC SPC find file SPC / grep project
s + 2ch jump on screen gd / gr definition / references
K hover docs SPC rr run current file
SPC gs git status SPC cf format
SPC w save SPC qq quit
<
==============================================================================
CANONICAL SPACE LAYOUT *chopsticks-v3-space*
Default layout: Space leader, comma localleader.
This layout assumes a QWERTY keyboard and CapsLock mapped at the system layer
to tap-Esc / hold-Ctrl. Vim keeps <C-w>hjkl for windows and standard LSP
motions for code.
Normal-mode s is a visible EasyMotion jump. This is intentionally different
from stock Vim because screen-local jumping is higher value in project editing.
Use cl for native s substitute and cc for native S substitute.
High-frequency keys:
>
SPC SPC files SPC , buffers
SPC / grep project SPC Tab alternate file
SPC e/E file sidebar SPC rr run file
SPC gs git status SPC gl git log graph
SPC ca code action SPC cr rename
SPC cf format SPC ? cheat sheet
<
Classic comma mappings remain available:
>
let g:chopsticks_keymap_style = 'classic'
<
==============================================================================
COMMANDS *chopsticks-commands*
User-facing commands:
>
:ChopsticksHelp open this help
:ChopsticksTutor guided practice
:ChopsticksCheatSheet active keymap reference
:ChopsticksStatus health diagnostics
:ChopsticksBeta beta checklist
:ChopsticksBetaLog editable beta notes
:ChopsticksBetaSession append a timestamped beta note block
<
LSP commands come from vim-lsp:
>
:LspInstallServer install a server for the current filetype
:LspStatus inspect attached servers
<
==============================================================================
PROFILES AND LOCAL CONFIG *chopsticks-profiles*
Keep personal choices outside the managed .vimrc:
>
" ${XDG_CONFIG_HOME:-~/.config}/chopsticks.vim
let g:chopsticks_profile = 'engineer'
let g:chopsticks_keymap_style = 'space'
<
Profiles:
minimal Core navigation, editing, git, Markdown. No LSP/ALE/completion.
engineer Default. LSP, ALE, completion, syntax extras.
full Engineer plus heavier Markdown feedback.
Optional habits:
>
let g:chopsticks_enable_jk_escape = 1
let g:chopsticks_enable_ctrl_s_save = 1
let g:chopsticks_enable_auto_pairs = 1
let g:chopsticks_enable_terminal_keymaps = 1
<
==============================================================================
BETA TESTING *chopsticks-beta*
For the v3 beta candidate, record real editing friction instead of abstract
opinions:
>
:ChopsticksBeta compact beta checklist
:ChopsticksBetaLog open editable local notes
:ChopsticksBetaSession append a new session block
<
Default beta log:
>
${XDG_CONFIG_HOME:-~/.config}/chopsticks-beta.md
<
Exit criteria before a stable release:
- s as jump still feels worth the native override.
- No high-frequency action needs an undocumented key.
- README, QUICKSTART, :help chopsticks, SPC ?, and :ChopsticksTutor agree.
- quick and Vim smoke tests pass locally and over SSH.
- The README GIF matches the public keymap.
==============================================================================
TROUBLESHOOTING *chopsticks-troubleshooting*
Start with:
>
:ChopsticksStatus
SPC ?
:ChopsticksTutor
:ChopsticksHelp
<
Common fixes:
Plugins missing :PlugInstall
LSP missing Open that filetype, then :LspInstallServer
Need active keys SPC ?
Need full docs :help chopsticks
Need beta notes :ChopsticksBetaSession
Slow large file Syntax, undo, swap, and ALE are auto-reduced
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

15
install.sh
View file

@ -719,6 +719,21 @@ if [[ $_plug_count -eq 0 ]]; then
fi
ok "Plugins installed ($_plug_count)"
step "Installing Vim help"
if [[ -d "$SCRIPT_DIR/doc" ]]; then
# shellcheck disable=SC2016 # $CHOPSTICKS_HELP_DIR is expanded by Vim.
if CHOPSTICKS_HELP_DIR="$SCRIPT_DIR/doc" \
"$VIM_BIN" -Nu NONE -i NONE -n -es -N \
-c 'execute "silent! helptags " . fnameescape($CHOPSTICKS_HELP_DIR)' \
-c 'qa!' >/dev/null 2>&1; then
ok ":help chopsticks"
else
warn "Could not generate Vim help tags. Inside Vim, run: :ChopsticksHelp"
fi
else
skip "Vim help docs not found"
fi
# ============================================================================
# 4. Module Selection
# ============================================================================

2
modules/cheatsheet.vim
View file

@ -147,6 +147,7 @@ function! s:CheatSheet() abort
\ ' Esc exit insert',
\ ' SPC fv edit vimrc',
\ ' SPC fV reload vimrc',
\ ' :ChopsticksHelp full help',
\ ' :ChopsticksTutor practice',
\ ' :ChopsticksStatus health',
\ ' :ChopsticksBeta beta test guide',
@ -260,6 +261,7 @@ function! s:CheatSheet() abort
\ ' Esc exit insert',
\ ' ,ev edit vimrc',
\ ' ,sv reload vimrc',
\ ' :ChopsticksHelp full help',
\ ' :ChopsticksTutor practice',
\ ' :ChopsticksStatus health',
\ ' :ChopsticksBeta beta test guide',

18
modules/help.vim Normal file
View file

@ -0,0 +1,18 @@
" help.vim — native Vim help entrypoint
function! s:OpenHelp() abort
let l:doc = g:chopsticks_dir . '/doc'
if isdirectory(l:doc)
silent! execute 'helptags ' . fnameescape(l:doc)
endif
try
help chopsticks
catch /^Vim\%((\a\+)\)\=:E149/
echohl WarningMsg
echom 'chopsticks help tags are missing; run :helptags ' . l:doc
echohl None
endtry
endfunction
command! ChopsticksHelp call s:OpenHelp()

2
modules/status.vim
View file

@ -85,6 +85,8 @@ function! s:ChopsticksStatus() abort
call add(l:lines, 'chopsticks status')
call add(l:lines, repeat('─', 50))
call add(l:lines, '')
call add(l:lines, ' help :ChopsticksHelp :ChopsticksTutor SPC ?')
call add(l:lines, '')
if !empty(get(g:, 'chopsticks_beta_label', ''))
call add(l:lines, '── beta ──')

2
modules/tutor.vim
View file

@ -28,6 +28,7 @@ function! s:ChopsticksTutor() abort
\ ' SPC ? active cheat sheet',
\ ' SPC w save',
\ ' SPC qx save and quit',
\ ' :ChopsticksHelp full help',
\ ' :ChopsticksStatus health check',
\ ' :ChopsticksBeta beta checklist',
\ ' :ChopsticksBetaLog beta notes',
@ -92,6 +93,7 @@ function! s:ChopsticksTutor() abort
\ ' <C-w>hjkl split navigation',
\ '',
\ ' support',
\ ' :ChopsticksHelp full help',
\ ' :ChopsticksStatus health check',
\ ' :ChopsticksBeta beta checklist',
\ ' :ChopsticksBetaLog beta notes',

15
scripts/test-quick.sh
View file

@ -29,8 +29,10 @@ check_docs() {
markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md BETA.md
step "Documentation consistency"
for command in ChopsticksBeta ChopsticksBetaLog ChopsticksBetaSession; do
for file in README.md BETA.md modules/beta.vim modules/cheatsheet.vim \
for command in ChopsticksHelp ChopsticksBeta ChopsticksBetaLog \
ChopsticksBetaSession
do
for file in README.md BETA.md doc/chopsticks.txt modules/cheatsheet.vim \
modules/tutor.vim modules/status.vim
do
grep -Fq "$command" "$file" || {
@ -39,6 +41,15 @@ check_docs() {
}
done
done
grep -Fq '*chopsticks.txt*' doc/chopsticks.txt
grep -Fq '*chopsticks-v3-space*' doc/chopsticks.txt
grep -Fq 'command! ChopsticksHelp' modules/help.vim
for command in ChopsticksBeta ChopsticksBetaLog ChopsticksBetaSession; do
grep -Fq "command! $command" modules/beta.vim || {
echo "Missing $command definition in modules/beta.vim" >&2
exit 1
}
done
if command -v vhs >/dev/null 2>&1; then
vhs validate .github/demo.tape

12
scripts/test-vim.sh
View file

@ -42,11 +42,20 @@ check_vim() {
fi
mkdir -p "$TMP_ROOT/chopsticks path/modules"
mkdir -p "$TMP_ROOT/chopsticks path/doc"
cp .vimrc "$TMP_ROOT/chopsticks path/.vimrc"
cp modules/*.vim "$TMP_ROOT/chopsticks path/modules/"
cp doc/*.txt "$TMP_ROOT/chopsticks path/doc/"
XDG_CONFIG_HOME="$EMPTY_XDG" vim -u "$TMP_ROOT/chopsticks path/.vimrc" \
-i NONE -es -N -c 'qa!' 2>&1
XDG_CONFIG_HOME="$EMPTY_XDG" \
vim -u "$TMP_ROOT/chopsticks path/.vimrc" -i NONE -es -N \
-c 'ChopsticksHelp' \
-c 'if expand("%:t") !=# "chopsticks.txt" | cquit | endif' \
-c 'if search("chopsticks-v3-space", "n") == 0 | cquit | endif' \
-c 'qa!' 2>&1
XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N \
-c 'let g:chopsticks_profile = "minimal"' \
-c 'source .vimrc' \
@ -79,6 +88,7 @@ check_vim() {
exit 1
fi
grep -Fq 'OK vim-lsp stack (installed)' "$TMP_ROOT/status-default.txt"
grep -Fq 'help :ChopsticksHelp :ChopsticksTutor SPC ?' "$TMP_ROOT/status-default.txt"
grep -Fq 'candidate 3.0.0-beta.1' "$TMP_ROOT/status-default.txt"
grep -Fq 'keymap space' "$TMP_ROOT/status-default.txt"
grep -Fq 'commands :ChopsticksBeta :ChopsticksBetaLog' "$TMP_ROOT/status-default.txt"
@ -258,6 +268,7 @@ check_vim() {
grep -Fq 'SPC w save' "$TMP_ROOT/cheat-default.txt"
grep -Fq 's+2ch easymotion jump' "$TMP_ROOT/cheat-default.txt"
grep -Fq 'cl / cc native s / S substitute' "$TMP_ROOT/cheat-default.txt"
grep -Fq ':ChopsticksHelp full help' "$TMP_ROOT/cheat-default.txt"
grep -Fq ':ChopsticksTutor practice' "$TMP_ROOT/cheat-default.txt"
grep -Fq ':ChopsticksBeta beta test guide' "$TMP_ROOT/cheat-default.txt"
grep -Fq ':ChopsticksBetaLog beta notes' "$TMP_ROOT/cheat-default.txt"
@ -332,6 +343,7 @@ check_vim() {
-c 'qa!' 2>&1
grep -Fq 'chopsticks tutor' "$TMP_ROOT/tutor-default.txt"
grep -Fq 'SPC ? active cheat sheet' "$TMP_ROOT/tutor-default.txt"
grep -Fq ':ChopsticksHelp full help' "$TMP_ROOT/tutor-default.txt"
grep -Fq 's + 2 chars visible jump' "$TMP_ROOT/tutor-default.txt"
grep -Fq 'cl / cc native s / S substitute' "$TMP_ROOT/tutor-default.txt"
grep -Fq 'gd / gr / K definition / refs / docs' "$TMP_ROOT/tutor-default.txt"