chopsticks/QUICKSTART.md

Quick Start

Five minutes from zero to a working Vim environment.

---

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.

---

Step 1: Install

curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash

Traditional:

git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
cd ~/.vim && ./install.sh

Non-interactive / CI:

curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash -s -- --yes

---

Step 2: Open Vim

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:

: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:

:LspStatus

Markdown LSP (marksman) needs a standalone binary:

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        Exit insert mode → Normal
Ctrl+s          Save
Ctrl+p          Fuzzy find file
,e              File browser (netrw)
gd              Go to definition
K               Show documentation
[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

---

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')
,gd   diff current file
,gb   blame
,gc   commit
,gp   push
,gl   pull
[x / ]x   navigate conflict markers

---

Quick Reference Card

BASICS
  Esc / jk        Exit insert mode → Normal
  Ctrl+s          Save
  :q! + Enter     Emergency quit
  ,?              Open cheat sheet

FILES
  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

---

See README.md for the complete reference.