chopsticks/QUICKSTART.md

Quick Start

Five minutes from zero to a working Vim engineering environment.

New to Vim? Read Step 0 first — it takes 2 minutes and prevents the most common beginner frustration. Already know how Vim modes work? Skip to Step 1.

---

Step 0: Vim Basics

When confused, press Esc until things feel normal again — then keep reading.

Vim is modal: the keyboard behaves differently depending on which mode you are in. Most people get stuck because they try to type text while in Normal mode.

The Three Modes

Mode	Purpose	How to enter	How to leave
Normal	Navigate and run commands	Startup default	— (you're already here)
Insert	Type text	i before cursor, a after, o new line below	Esc or jk
Visual	Select text	v char-by-char, V whole lines	Esc

4 Survival Commands

Learn these before anything else. They will get you out of every stuck situation.

Command	Action
Esc or jk	Exit insert/visual mode — return to Normal
:q! then Enter	Force quit without saving (emergency exit)
,x	Save and quit
,w or Ctrl+s	Save the file

Once in Normal mode, press ,? to open a cheat sheet covering everything else.

---

Step 1: Install

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

The script handles everything: symlinks, vim-plug, plugins, and all tools. It detects your OS (macOS/Debian/Arch/Fedora) and installs what it can automatically.

Non-interactive (CI / server):

./install.sh --yes

---

Step 2: Open Vim

vim

The startup screen (vim-startify) shows recent files and sessions. Press Ctrl+p to find a file, or just type a path.

To open a project:

vim .        # NERDTree on left, Startify on right
vim myfile   # opens file directly

---

Step 3: Set Up LSP (pick your path)

Path A: With Node.js (CoC — full LSP)

node --version   # must be >= 14.14

Inside Vim, install language servers for your stack:

:CocInstall coc-pyright coc-tsserver coc-go coc-rust-analyzer

Or let install.sh do it — it asks during setup.

Path B: Without Node.js (vim-lsp — no dependencies)

Open a source file, then run:

:LspInstallServer

This auto-detects and installs the correct language server for the current filetype.

---

The 12 Keys That Matter

,           (pause 500ms)   Show all keybindings (which-key)
,?                          Open cheat sheet inside Vim
Esc / jk                    Exit insert mode → Normal (memorize this)
Ctrl+s                      Save (works in normal and insert mode)
Ctrl+p                      Fuzzy find file
Ctrl+n                      Toggle file tree
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
,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 all references
K	Show 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+2ch	EasyMotion: jump anywhere

Manage Errors

Key	Action
]g	Jump to next diagnostic
[g	Jump to previous diagnostic
K	Read the error message
,ca	Apply code action / auto-fix

Git Workflow

,gs   git status (stage with 's', commit with 'cc')
,gd   diff current file
,gb   blame current file
,gc   commit
,gp   push
,gl   pull

---

Language Workflows

Python

# tools installed by install.sh; or manually:
pip install black flake8 pylint isort

Auto-formats with black + isort on save. Lint errors show as X/! in the sign column.

JavaScript / TypeScript

npm install -g prettier eslint typescript

Auto-formats with prettier on save.

Go

# tools installed by install.sh; or manually:
go install golang.org/x/tools/gopls@latest
go install golang.org/x/tools/cmd/goimports@latest
go install honnef.co/go/tools/cmd/staticcheck@latest

gofmt + goimports run on save automatically.

Markdown

Install marksman for LSP support (completions, link checking):

brew install marksman          # macOS
sudo pacman -S marksman        # Arch
# or: ./install.sh (handles it automatically)

---

Customize

Edit config live:

,ev     " opens ~/.vimrc in Vim
,sv     " reloads config without restarting

Per-project settings: create .vimrc in your project root.

" project/.vimrc
set shiftwidth=2
let g:ale_python_black_options = '--line-length=100'

Change color scheme in ~/.vimrc:

colorscheme dracula    " or: gruvbox, solarized, onedark

---

Quick Reference Card

BASICS (learn these first)
  Esc / jk        Exit insert mode → Normal
  Ctrl+s          Save (normal + insert mode)
  :q! + Enter     Emergency quit without saving
  ,?              Open cheat sheet

FILES
  Ctrl+n          File tree toggle
  Ctrl+p          Fuzzy find file (git-aware)
  ,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          Go to definition
  K           Show documentation
  [g / ]g     Prev/next LSP diagnostic
  [e / ]e     Prev/next ALE error
  ,rn         Rename symbol
  ,ca         Code action / auto-fix
  ,f          Format selection  |  ,F  Format whole file

GIT
  ,gs  Status  |  ,gd  Diff  |  ,gb  Blame
  ,gc  Commit  |  ,gp  Push  |  ,gl  Pull

WINDOWS / PANES
  Ctrl+h/j/k/l    Move between Vim windows or tmux panes
  ,h / ,l         Prev / next buffer
  ,tv         Open terminal (vertical)
  ,th         Open terminal (horizontal)
  Esc         Exit terminal mode
  ,u          Undo tree  |  ,tt  Tag browser

SEARCH & REPLACE
  /text       Search forward  |  ?text  backward
  //          Search for visually selected text
  ,*          Replace word under cursor (file-wide)

CLIPBOARD
  ,y / ,Y     Yank / yank line to system clipboard
  ,p / ,P     Paste from system clipboard (after / before)

---

See README.md for the complete reference.