public/cheatsheets/zsh/zsh-cheatsheet.md

# Zsh Cheatsheet

Reference for the new ZDOTDIR-based zsh setup (oh-my-zsh removed,
config lives in `~/.config/zsh/`).

## Aliases

### Docker Compose
| Alias | Expands to | What it does |
|---|---|---|
| `dcu` | `docker compose up -d` | Start containers in detached mode |
| `dcd` | `docker compose down` | Stop and remove containers |
| `dcr` | `docker compose restart` | Restart containers |
| `dcp` | `docker compose pull` | Pull latest images |

### Navigation
| Alias | Expands to | What it does |
|---|---|---|
| `..` | `cd ..` | Up one directory |
| `...` | `cd ../..` | Up two directories |
| `....` | `cd ../../..` | Up three directories |

### File listing
| Alias | Expands to | What it does |
|---|---|---|
| `ls` | `eza -lahF --group-directories-first --time-style="+%d/%m/%Y %H:%M" --git` (falls back to plain `ls -lahF ...` if eza isn't installed) | Long listing, all files, classify symbols (`/`, `*`, `@`), directories first, custom date format, git status column |
| `tree` | `eza --tree` (only if eza is installed) | Tree view of directory structure |
| `cat` | `bat` (only if bat is installed) | Syntax-highlighted file viewer |

### System
| Alias | Expands to | What it does |
|---|---|---|
| `df` | `df -h` | Disk usage, human-readable sizes |
| `free` | `free -h` | Memory usage, human-readable sizes |
| `c` | `clear` | Clear the terminal |

## Functions

| Function | Usage | What it does |
|---|---|---|
| `cd` (overridden) | `cd <dir>` | Changes directory, then automatically runs `ls` (so you always see the contents of where you land). `cd` with no argument goes to `$HOME`. |
| `mkcd` | `mkcd <dir>` | Creates a directory and `cd`s into it in one step |
| `extract` | `extract <file>` | Extracts an archive based on its extension. Supports `.tar.gz`/`.tgz`, `.tar.bz2`, `.tar.xz`, `.zip`, `.gz` |
| `ports` | `ports` | Shows listening ports and the processes using them (`sudo ss -tulpen`) |
| `psg` | `psg <name>` | Searches running processes by name (case-insensitive `ps aux | grep`) |
| `killport` | `killport <port>` | Kills whatever process is listening on the given port |
| `logtail` | `logtail <file> [lines]` | Tails a log file (`-f`), default 50 lines, or specify a custom number |
| `reload` | `reload` | Reloads the zsh config (`source $ZDOTDIR/.zshrc`) without restarting the shell |

## Keybindings

| Key | Action | Notes |
|---|---|---|
| `Ctrl + →` | Move cursor forward one word | |
| `Ctrl + ←` | Move cursor backward one word | |
| `Ctrl + \` | Toggle autosuggestions on/off | Echoes "Autosuggestions: on/off" so you know the current state |
| `↑` (Up arrow) | Search history backward by prefix | Type a few characters first, then press Up to find matching previous commands |
| `↓` (Down arrow) | Search history forward by prefix | Same as above, opposite direction |

## Line editing (built-in zsh defaults)

These come from zsh's default "emacs" editing mode (the standard unless
something switches it to vi mode — this setup doesn't). Most of these
work in any emacs-style shell (bash, zsh) and are worth building into
muscle memory since they work everywhere.

### Cursor movement

| Key | Action |
|---|---|
| `←` / `→` | Move cursor one character left/right |
| `Ctrl + ←` / `Ctrl + →` | Move cursor one **word** left/right (custom binding in this setup) |
| `Ctrl + A` | Jump to the **start** of the line |
| `Ctrl + E` | Jump to the **end** of the line |
| `Alt + B` | Move backward one word (alternative to Ctrl+←) |
| `Alt + F` | Move forward one word (alternative to Ctrl+→) |

### Deleting / cutting text

| Key | Action |
|---|---|
| `Backspace` | Delete the character **before** the cursor |
| `Ctrl + D` / `Delete` | Delete the character **under/after** the cursor (Ctrl+D on an empty line exits the shell — careful) |
| `Ctrl + W` | Delete the **word before** the cursor (cuts to kill-ring) |
| `Alt + D` | Delete the **word after** the cursor (cuts to kill-ring) |
| `Alt + Backspace` | Same as Ctrl+W — delete word before cursor |
| `Ctrl + U` | Delete **everything before** the cursor (whole line back to start) |
| `Ctrl + K` | Delete **everything after** the cursor (to end of line) |

### Pasting (yanking) deleted text

zsh doesn't have "select text" like a GUI — instead, anything you cut
with `Ctrl+W`, `Alt+D`, `Ctrl+U`, or `Ctrl+K` goes into a clipboard-like
buffer (the "kill ring"), which you can paste back with:

| Key | Action |
|---|---|
| `Ctrl + Y` | Paste ("yank") the last cut text at the cursor |

**Practical example:** to move a word from the end of a command to the
start — put cursor at end of word, `Alt + Backspace` to cut it, `Ctrl + A`
to jump to the start of the line, `Ctrl + Y` to paste it there.

### Undo / retype

| Key | Action |
|---|---|
| `Ctrl + _` (Ctrl + Shift + -) | Undo the last edit |
| `Ctrl + L` | Clear the screen (same as the `c` alias, but doesn't lose scrollback the same way) |

### Transposing / fixing typos

| Key | Action |
|---|---|
| `Ctrl + T` | Swap the two characters around the cursor (fixes a typo like `hte` → `the`) — **note:** this is overridden by fzf's Ctrl+T in this setup if fzf is installed |
| `Alt + T` | Swap the two **words** around the cursor |

### Case changes

| Key | Action |
|---|---|
| `Alt + U` | Uppercase the word from the cursor onward |
| `Alt + L` | Lowercase the word from the cursor onward |
| `Alt + C` | Capitalize the word from the cursor onward |

### Re-running / editing previous commands

| Key | Action |
|---|---|
| `!!` | Re-run the last command (e.g. `sudo !!` re-runs the last command with sudo) |
| `!$` | The last **argument** of the previous command (e.g. `cat !$` opens whatever file you last referenced) |
| `Ctrl + R` (no fzf) | Reverse incremental search through history (built-in, before fzf takes over — see fzf section below for the upgraded version) |
| `fc` | Opens the last command in `$EDITOR` (nano) for editing, then runs it |

## Fuzzy search (fzf)

Only active if `fzf` is installed.

| Key | Action | Notes |
|---|---|---|
| `Ctrl + R` | Fuzzy search command history | Type to filter, select a command, it's inserted at the cursor. This overrides the built-in reverse search mentioned above |
| `Ctrl + F` | Fuzzy file search (includes hidden files, excludes `.git`) | Selected file path is inserted at the cursor. Uses `fd` if installed, otherwise falls back to `find` |
| `Ctrl + T` | Fuzzy file search (fzf's built-in, non-hidden files) | Only active if fzf's own shell integration is found on the system; uses `fd` for speed if installed. This overrides the built-in character-transpose shortcut mentioned above |

## Plugins (auto-loaded on shell startup)

These are cloned automatically into `$ZDOTDIR/plugins/` the first time
you start a shell after the role runs — no manual setup needed.

| Plugin | What it does |
|---|---|
| `zsh-autosuggestions` | Shows a greyed-out suggestion as you type, based on history. Press `→` (right arrow) or `End` to accept it |
| `fast-syntax-highlighting` | Colors commands as you type — valid commands, paths, strings, etc. get different colors so you can spot typos before pressing Enter |

## Environment / history

- History file: `~/.local/state/zsh/history`
- History size: 10,000 commands
- History behavior: shared across sessions, duplicates ignored, commands
  starting with a space aren't recorded (`HIST_IGNORE_SPACE`)
- Default editor: `nano` (`$EDITOR` / `$VISUAL`)
- Config location: `$ZDOTDIR` = `~/.config/zsh/`
- Per-host extra env vars (e.g. `VAULT_ADDR`) are set via `zsh_extra_env`
  in Ansible host_vars, appended to `env.zsh`

## Startup

`fastfetch` runs automatically every time a new shell opens, showing
system info (OS, kernel, uptime, packages, etc.) above the prompt.