alee/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cb5a812242796f846f7e56a03512eb86c36d5266
dotfiles/docs/REFERENCE.md
Aaron D. Lee 48784c97fe Remove tmux-workspaces in favor of tmuxinator-only workflow 
- Delete tmux-workspaces.zsh and .tmux-templates directory
- Remove TW_* config settings from dotfiles.conf
- Clean up tmuxinator.zsh (remove import/integration code)
- Update README, INSTALL, and REFERENCE docs
- Fix editor config: .zshrc now uses DEFAULT_EDITOR from dotfiles.conf

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 20:32:01 -05:00

601 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Reference Guide
Complete reference for ADLee's Dotfiles configuration, Espanso triggers, and advanced features.
## Table of Contents
- [Configuration Reference](#configuration-reference)
- [Espanso Triggers](#espanso-triggers)
- [Vim Configuration](#vim-configuration)
- [Tmux Configuration](#tmux-configuration)
- [Git Aliases](#git-aliases)
- [Function Files Reference](#function-files-reference)
- [Color Reference](#color-reference)
---
## Configuration Reference
### dotfiles.conf Options
Complete list of all configuration options in `~/.dotfiles/dotfiles.conf`:
#### Core Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `DOTFILES_VERSION` | `"1.2.0"` | Dotfiles version |
| `DOTFILES_DIR` | `"$HOME/.dotfiles"` | Installation directory |
| `DOTFILES_BRANCH` | `"main"` | Git branch to use |
| `DOTFILES_BACKUP_PREFIX` | `"$HOME/.dotfiles_backup"` | Backup location prefix |
#### GitHub Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `DOTFILES_GITHUB_USER` | `"adlee-was-taken"` | GitHub username |
| `DOTFILES_REPO_NAME` | `"dotfiles"` | Repository name |
#### User Identity
| Variable | Default | Description |
|----------|---------|-------------|
| `USER_FULLNAME` | `""` | Your full name |
| `USER_EMAIL` | `""` | Your email |
| `USER_GITHUB` | `""` | Your GitHub username |
#### Git Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `GIT_USER_NAME` | `""` | Git user.name (falls back to USER_FULLNAME) |
| `GIT_USER_EMAIL` | `""` | Git user.email (falls back to USER_EMAIL) |
| `GIT_DEFAULT_BRANCH` | `"main"` | Default branch name |
#### Feature Toggles
| Variable | Values | Description |
|----------|--------|-------------|
| `INSTALL_DEPS` | `auto/true/false` | Install dependencies |
| `INSTALL_ZSH_PLUGINS` | `true/false` | Install zsh plugins |
| `INSTALL_FZF` | `true/false/ask` | Install fzf |
| `INSTALL_BAT` | `true/false/ask` | Install bat |
| `INSTALL_EZA` | `true/false/ask` | Install eza |
| `INSTALL_NEOVIM` | `true/false/ask` | Install neovim |
| `SET_ZSH_DEFAULT` | `true/false/ask` | Set zsh as default shell |
#### MOTD Settings
| Variable | Values | Description |
|----------|--------|-------------|
| `ENABLE_MOTD` | `true/false` | Enable MOTD display |
| `MOTD_STYLE` | `compact/mini/full/none` | MOTD display style |
| `MOTD_SHOW_FAILED_SERVICES` | `true/false` | Show failed systemd services |
| `MOTD_SHOW_UPDATES` | `true/false` | Show available updates |
#### Theme Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `ZSH_THEME_NAME` | `"adlee"` | Zsh theme name |
| `THEME_TIMER_THRESHOLD` | `10` | Seconds before showing timer |
| `THEME_PATH_TRUNCATE_LENGTH` | `32` | Max path display length |
#### Advanced Features
| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_SMART_SUGGESTIONS` | `true` | Enable typo correction |
| `ENABLE_COMMAND_PALETTE` | `true` | Enable Ctrl+Space palette |
| `ENABLE_SHELL_ANALYTICS` | `false` | Command usage tracking |
| `ENABLE_VAULT` | `true` | Enable secrets vault |
| `DOTFILES_AUTO_SYNC_CHECK` | `true` | Check for updates on start |
#### Btrfs Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `BTRFS_DEFAULT_MOUNT` | `"/"` | Default mount for btrfs commands |
#### Snapper Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `SNAPPER_CONFIG` | `"root"` | Snapper config name |
| `LIMINE_CONF` | `"/boot/limine.conf"` | Limine config path |
#### Tmux Workspace Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `TW_SESSION_PREFIX` | `"work"` | Session naming prefix |
| `TW_DEFAULT_TEMPLATE` | `"dev"` | Default workspace template |
#### Python Template Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `PY_TEMPLATE_BASE_DIR` | `"$HOME/projects"` | Project base directory |
| `PY_TEMPLATE_PYTHON` | `"python3"` | Python executable |
| `PY_TEMPLATE_VENV_NAME` | `"venv"` | Virtual env directory name |
| `PY_TEMPLATE_USE_POETRY` | `false` | Use poetry instead of venv |
| `PY_TEMPLATE_GIT_INIT` | `true` | Initialize git repo |
#### SSH Manager Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `SSH_AUTO_TMUX` | `true` | Auto-create tmux session |
| `SSH_TMUX_SESSION_PREFIX` | `"ssh"` | Session naming prefix |
| `SSH_SYNC_DOTFILES` | `ask` | Sync dotfiles on connect |
#### Package Manager
| Variable | Values | Description |
|----------|--------|-------------|
| `AUR_HELPER` | `auto/paru/yay` | Preferred AUR helper |
---
## Espanso Triggers
Complete list of text expansion triggers.
### Date and Time
| Trigger | Output | Example |
|---------|--------|---------|
| `..date` | Date (YYYY-MM-DD) | `2025-12-24` |
| `..ds` | Same as `..date` | `2025-12-24` |
| `..sds` | Short date (YYYYMMDD) | `20251224` |
| `..time` | Time (HH:MM:SS) | `14:30:45` |
| `..utime` | UTC time | `19:30:45` |
| `..ztime` | Time with timezone | `14:30:45.123 EST` |
| `..uztime` | UTC time with timezone | `19:30:45.123 UTC` |
| `..dt` | Date + time | `2025-12-24 14:30:45 EST` |
| `..udt` | UTC date + time | `2025-12-24 19:30:45 UTC` |
| `..ts` | ISO 8601 timestamp | `2025-12-24T19:30:45.123Z` |
| `..utc` | UTC with milliseconds | `2025-12-24 19:30:45.123 UTC` |
| `..month` | Month name | `December` |
| `..year` | Year | `2025` |
| `..week` | Week number | `Week 52` |
| `..day` | Day of week | `Wednesday` |
| `..epoch` | Unix timestamp | `1735066245` |
| `..epochms` | Unix timestamp (ms) | `1735066245123` |
### Quick Text
| Trigger | Output |
|---------|--------|
| `..shrug` | `¯\_(ツ)_/¯` |
| `..flip` | `(╯°□°)╯︵ ┻━┻` |
| `..unflip` | `┬─┬ ノ( ゜-゜ノ)` |
| `..lenny` | `( ͡° ͜ʖ ͡°)` |
| `..check` | `✓` |
| `..cross` | `✗` |
| `..arrow` | `→` |
| `..larrow` | `←` |
### Quick Responses
| Trigger | Output |
|---------|--------|
| `..brb` | Be right back |
| `..omw` | On my way |
| `..tyvm` | Thank you very much |
| `..lgtm` | Looks good to me |
| `..wfm` | Works for me |
| `..ack` | Acknowledged |
| `..asap` | As soon as possible |
### System Information
| Trigger | Output |
|---------|--------|
| `..ip` | Public IP address |
| `..locip` | Local IP address |
| `..branch` | Current git branch |
### Git Commands
| Trigger | Output |
|---------|--------|
| `..gstat` | `git status` |
| `..gco` | `git checkout ` |
| `..gcm` | `git commit -m ""` |
| `..glog` | `git log --oneline --graph --decorate --all` |
| `..gpush` | `git push origin ` |
| `..gpull` | `git pull origin ` |
| `..gbranch` | `git branch -a` |
| `..gdiff` | `git diff` |
| `..gadd` | `git add .` |
### Docker Commands
| Trigger | Output |
|---------|--------|
| `..dps` | `docker ps` |
| `..dpsa` | `docker ps -a` |
| `..dcup` | `docker-compose up -d` |
| `..dcdown` | `docker-compose down` |
| `..dlog` | `docker logs -f ` |
| `..dexec` | `docker exec -it ` |
| `..dim` | `docker images` |
| `..dprune` | `docker system prune -af` |
### Code Templates
| Trigger | Output |
|---------|--------|
| `..bash` | Bash shebang + `set -euo pipefail` |
| `..python` | Python main boilerplate |
| `..she!` | `#!/usr/bin/env bash` |
### Markdown
| Trigger | Output |
|---------|--------|
| `..mdcode` | Code block (generic) |
| `..mdbash` | Bash code block |
| `..mdpy` | Python code block |
| `..mdjs` | JavaScript code block |
| `..mdtable` | Markdown table template |
| `..mdlink` | `[text](url)` (prompts) |
| `..mdimg` | `![alt](url)` (prompts) |
### Programming Comments
| Trigger | Output |
|---------|--------|
| `..todo` | `// TODO: ` |
| `..fixme` | `// FIXME: ` |
| `..note` | `// NOTE: ` |
| `..hack` | `// HACK: ` |
| `..debug` | `// DEBUG: ` |
### Common Commands
| Trigger | Output |
|---------|--------|
| `..ll` | `ls -lah` |
| `..la` | `ls -A` |
| `..grep` | `grep -rni "" .` |
| `..find` | `find . -name ""` |
| `..port` | `lsof -i :` |
| `..kill` | `kill -9 ` |
| `..proc` | `ps aux \| grep ` |
| `..disk` | `df -h` |
| `..mem` | `free -h` |
### Navigation
| Trigger | Output |
|---------|--------|
| `..~` | `cd ~` |
| `..tmp` | `cd /tmp/` |
| `..logs` | `cd /var/log/` |
### URLs
| Trigger | Output |
|---------|--------|
| `..gh` | `https://github.com` |
| `..gl` | `https://gitlab.com` |
| `..gist` | `https://gist.github.com` |
| `..so` | `https://stackoverflow.com` |
| `..reddit` | `https://reddit.com` |
### Lorem Ipsum
| Trigger | Output |
|---------|--------|
| `..lorem` | One paragraph |
| `..loremlong` | Four paragraphs |
### Clipboard
| Trigger | Output |
|---------|--------|
| `..qp` | Primary clipboard (X11 selection) |
### Typo Corrections
| Trigger | Correction |
|---------|------------|
| `teh` | the |
| `recieve` | receive |
| `seperator` | separator |
| `definately` | definitely |
| `occured` | occurred |
| `lenght` | length |
| `wierd` | weird |
| `thier` | their |
### Emoji Package
| Trigger | Emoji |
|---------|-------|
| `:lol` | 😂 |
| `:sad` | ☹ |
| `:sml` | 😊 |
| `:strong` | 💪 |
| `:ba` | 😎 |
| `:ok` | 👍 |
| `:happy` | 😄 |
| `:cry` | 😭 |
| `:wow` | 😮 |
### Personal (in personal.yml)
| Trigger | Output |
|---------|--------|
| `..myemail` | Your email |
| `..myname` | Your full name |
| `..myphone` | Your phone |
| `..myweb` | Your website |
| `..mygithub` | Your GitHub URL |
| `..sig` | Email signature |
| `..sigfull` | Full signature |
| `..myaddr` | Your address |
| `..workemail` | Work email |
| `..worksig` | Work signature |
---
## Vim Configuration
### Leader Key
The leader key is `,` (comma).
### Key Mappings
| Mapping | Action |
|---------|--------|
| `,w` | Fast save (`:w!`) |
| `:W` | Sudo save |
| `Space` | Search (`/`) |
| `Ctrl+Space` | Backward search (`?`) |
| `,<Enter>` | Disable search highlight |
| `Ctrl+j/k/h/l` | Move between windows |
| `,bd` | Close buffer |
| `,ba` | Close all buffers |
| `,l` / `,h` | Next/previous buffer |
| `,tn` | New tab |
| `,to` | Tab only |
| `,tc` | Close tab |
| `,tm` | Move tab |
| `,tl` | Toggle last tab |
| `,te` | Open tab with buffer's path |
| `,cd` | Switch CWD to buffer dir |
| `Alt+j/k` | Move line down/up |
| `,ss` | Toggle spell checking |
| `,sn` / `,sp` | Next/previous misspelling |
| `,sa` | Add to dictionary |
| `,s?` | Suggest corrections |
| `,pp` | Toggle paste mode |
| `,q` | Open scratch buffer |
| `,x` | Open markdown buffer |
| `0` | First non-blank character |
### Settings
- 4 spaces for indentation
- Tabs expanded to spaces
- Smart indentation
- Line wrapping on word boundaries
- Incremental search with highlighting
- Wild menu for command completion
---
## Tmux Configuration
### Key Bindings
| Binding | Action |
|---------|--------|
| `Prefix + U` | Resize pane up 8 lines |
| `Prefix + D` | Resize pane down 8 lines |
| `Prefix + L` | Resize pane left 8 chars |
| `Prefix + R` | Resize pane right 8 chars |
### Settings
- Default shell: `/usr/bin/zsh`
- Terminal: `tmux-256color`
- XTerm keys enabled
- Escape time: 0 (no delay)
- Pane border status: bottom
---
## Git Aliases
Built-in git aliases from `.gitconfig`:
| Alias | Command |
|-------|---------|
| `git st` | `git status` |
| `git co` | `git checkout` |
| `git br` | `git branch` |
| `git ci` | `git commit` |
| `git lg` | `git log --oneline --graph --decorate --all` |
| `git unstage` | `git reset HEAD --` |
| `git last` | `git log -1 HEAD` |
| `git visual` | `gitk` |
---
## Function Files Reference
### btrfs-helpers.zsh
Btrfs filesystem management utilities.
**Exported functions:** `btrfs-usage`, `btrfs-subs`, `btrfs-balance`, `btrfs-balance-status`, `btrfs-balance-cancel`, `btrfs-scrub`, `btrfs-scrub-status`, `btrfs-scrub-cancel`, `btrfs-defrag`, `btrfs-compress`, `btrfs-info`, `btrfs-health`, `btrfs-snap-usage`, `btrfs-maintain`, `btrfs-help`
**Aliases:** `btru`, `btrs`, `btrh`, `btri`, `btrc`
### command-palette.zsh
Fuzzy command launcher.
**Exported functions:** `command_palette`, `palette`, `p`, `bookmark`, `bm`, `jump`, `j`
**Key bindings:** `Ctrl+Space`, `Ctrl+P`
### motd.zsh
Message of the Day display.
**Exported functions:** `show_motd`, `show_motd_mini`, `show_motd_full`, `sysbrief`
**Aliases:** `motd`, `motd-mini`, `motd-full`
### password-manager.zsh
LastPass CLI integration.
**Exported functions:** `pw`, `pwf`, `pwof`
**Aliases:** `pwl`, `pwg`, `pwc`, `pws`
### python-templates.zsh
Python project scaffolding.
**Exported functions:** `py-new`, `py-django`, `py-flask`, `py-fastapi`, `py-data`, `py-cli`, `venv`
**Aliases:** `pynew`, `pydjango`, `pyflask`, `pyfast`, `pydata`, `pycli`
### smart-suggest.zsh
Typo correction and suggestions.
**Exported functions:** `command_not_found_handler`, `fuck`
### snapper.zsh
Btrfs snapshot management.
**Exported functions:** `snap-create`, `snap-list`, `snap-show`, `snap-delete`, `snap-check-limine`, `snap-sync`, `snap-validate-service`
**Aliases:** `snap`, `snapls`, `snaprm`, `snapshow`, `snapcheck`, `snapsync`
### ssh-manager.zsh
SSH profile management.
**Exported functions:** `ssh-save`, `ssh-list`, `ssh-connect`, `ssh-delete`, `ssh-reconnect`, `ssh-sync-dotfiles`, `sshf`
**Aliases:** `sshl`, `sshs`, `sshc`, `sshd`, `sshr`, `sshsync`
### systemd-helpers.zsh
Systemd service management.
**Exported functions:** `sc`, `scu`, `scr`, `sce`, `scd`, `sclog`, `sclogs`, `sc-failed`, `sc-timers`, `sc-recent`, `sc-boot`, `sc-search`, `sc-info`, `scf`, `sclogf`, `sc-help`
**Aliases:** `scs`, `scstart`, `scstop`, `screload`, `scmask`, `scunmask`, `jctl`, `jctlf`, `jctlb`, `jctlerr`
---
## Color Reference
Color variables defined in `zsh/lib/colors.zsh`:
### Standard Colors
| Variable | Description |
|----------|-------------|
| `DF_RED` | Red |
| `DF_GREEN` | Green |
| `DF_YELLOW` | Yellow (bold) |
| `DF_BLUE` | Blue |
| `DF_MAGENTA` | Magenta |
| `DF_CYAN` | Cyan |
| `DF_WHITE` | White |
### Bold Variants
`DF_BOLD_RED`, `DF_BOLD_GREEN`, `DF_BOLD_YELLOW`, `DF_BOLD_BLUE`, `DF_BOLD_MAGENTA`, `DF_BOLD_CYAN`, `DF_BOLD_WHITE`
### Text Styles
| Variable | Description |
|----------|-------------|
| `DF_BOLD` | Bold text |
| `DF_DIM` | Dim/faint text |
| `DF_ITALIC` | Italic text |
| `DF_UNDERLINE` | Underlined text |
| `DF_RESET` / `DF_NC` | Reset formatting |
### 256-Color Palette
| Variable | Description |
|----------|-------------|
| `DF_GREY` | Grey (242) |
| `DF_LIGHT_GREY` | Light grey (248) |
| `DF_DARK_GREY` | Dark grey (239) |
| `DF_ORANGE` | Orange (208) |
| `DF_LIGHT_ORANGE` | Light orange (220) |
| `DF_PINK` | Pink (213) |
| `DF_PURPLE` | Purple (141) |
| `DF_LIGHT_BLUE` | Light blue (39) |
| `DF_LIGHT_GREEN` | Light green (82) |
| `DF_BRIGHT_GREEN` | Bright green (118) |
| `DF_TEAL` | Teal (51) |
### Semantic Colors
| Variable | Maps To |
|----------|---------|
| `DF_SUCCESS` | `DF_GREEN` |
| `DF_ERROR` | `DF_RED` |
| `DF_WARNING` | `DF_YELLOW` |
| `DF_INFO` | `DF_CYAN` |
| `DF_HINT` | `DF_DIM` |
| `DF_ACCENT` | `DF_BLUE` |
| `DF_MUTED` | `DF_GREY` |
### Print Functions
| Function | Description |
|----------|-------------|
| `df_print_step "msg"` | Print step with `==>` prefix |
| `df_print_success "msg"` | Print with ✓ prefix |
| `df_print_error "msg"` | Print with ✗ prefix (stderr) |
| `df_print_warning "msg"` | Print with ⚠ prefix |
| `df_print_info "msg"` | Print with ℹ prefix |
| `df_print_section "title"` | Print section divider |
| `df_print_header "name"` | Print MOTD-style header box |
### Usage in Scripts
```bash
# In bash scripts
source "$HOME/.dotfiles/zsh/lib/colors.zsh"
echo -e "${DF_GREEN}Success!${DF_NC}"
# In zsh functions
source "${0:A:h}/../lib/colors.zsh"
df_print_success "Operation completed"
```
---
## Environment Variables
These are set or used by the dotfiles:
| Variable | Description |
|----------|-------------|
| `DOTFILES_DIR` | Dotfiles installation path |
| `UPDATE_PKG_COUNT` | Available package updates (for prompt) |
| `EDITOR` | Default editor (vim) |
| `VISUAL` | Visual editor (vim) |
| `LANG` / `LC_ALL` | Locale (en_US.UTF-8) |
| `FZF_DEFAULT_OPTS` | FZF appearance settings |
| `FZF_DEFAULT_COMMAND` | FZF file finder command |
Reference in New Issue View Git Blame Copy Permalink