From 5f3aad3b9939e6d31102fc8b1a23bfbf8dc9a124 Mon Sep 17 00:00:00 2001 From: "Aaron D. Lee" Date: Mon, 15 Dec 2025 16:17:06 -0500 Subject: [PATCH] Cleanup tasks. --- .editorconfig | 3 + .gitignore | 52 +++- CHANGELOG.md | 122 ++++++++ README.md | 425 +++++++++++++++++++-------- docs/ESPANSO.md | 260 ++++++++++++++--- docs/SETUP_GUIDE.md | 678 ++++++++++++++++++++++++++++++-------------- docs/SNAPPER.md | 236 ++++++++++++--- zsh/zshrc | 338 ---------------------- 8 files changed, 1341 insertions(+), 773 deletions(-) create mode 100644 CHANGELOG.md delete mode 100644 zsh/zshrc diff --git a/.editorconfig b/.editorconfig index 431a5a2..abb8286 100644 --- a/.editorconfig +++ b/.editorconfig @@ -15,5 +15,8 @@ indent_size = 4 [*.{yml,yaml}] indent_size = 2 +[*.md] +trim_trailing_whitespace = false + [Makefile] indent_style = tab diff --git a/.gitignore b/.gitignore index ab3e14b..fcd8d2d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,27 +1,63 @@ -# OS files +# ============================================================================ +# Dotfiles .gitignore +# ============================================================================ + +# --- OS files --- .DS_Store Thumbs.db +Desktop.ini -# Backup files +# --- Backup files --- *.backup *.bak *~ +*.swp +*.swo -# Local machine-specific configs +# --- Local machine-specific configs --- *.local .zshrc.local +.gitconfig.local -# Sensitive information +# --- Sensitive information --- .env .env.* secrets/ .git-credentials -# Espanso backups +# --- Vault (encrypted secrets) --- +vault/ +!vault/.gitkeep + +# --- Espanso --- espanso/match/*.backup -# Editor files -*.swp -*.swo +# --- Editor/IDE files --- .idea/ .vscode/ +*.sublime-* +.project +.settings/ + +# --- Cache and temp files --- +.cache/ +*.log +*.tmp +.sync_state +.sync_log + +# --- Command tracking --- +.smart-suggest-track + +# --- Bookmarks (machine-specific) --- +.bookmarks + +# --- Generated files --- +dotfiles.conf.wizard +git/.gitconfig + +# --- Package managers --- +node_modules/ +__pycache__/ +*.pyc +.npm/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..50390f0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,122 @@ +# Changelog + +All notable changes to this dotfiles project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2025-12-15 + +### Added + +#### Core Features +- **Interactive Setup Wizard** (`setup-wizard.sh`) - Beautiful TUI installer using `gum` with fallback to basic prompts +- **Command Palette** (`command-palette.zsh`) - Raycast-style fuzzy launcher triggered by Ctrl+Space or Ctrl+P +- **Smart Suggestions** (`smart-suggest.zsh`) - Typo correction for 100+ common mistakes + alias recommendations +- **Shell Analytics** (`shell-stats.sh`) - Dashboard showing command usage, suggestions, and activity heatmap +- **Secrets Vault** (`vault.sh`) - Encrypted storage for API keys using age/gpg +- **Dotfiles Sync** (`dotfiles-sync.sh`) - Multi-machine synchronization with watch mode +- **Dotfiles Doctor** (`dotfiles-doctor.sh`) - Health checker with auto-fix capability +- **Version Tracking** (`dotfiles-version.sh`) - Compare local vs remote versions + +#### Configuration +- Centralized `dotfiles.conf` for all settings +- Git identity configuration (generated, not hardcoded) +- Feature toggles for all optional components +- Machine-specific config support via `.zshrc.local` + +#### Installation +- `--wizard` flag for interactive TUI installation +- `--uninstall` flag to remove symlinks and restore backups +- `--purge` flag to completely remove dotfiles +- `--skip-deps` flag for faster re-runs +- Auto-detection of installed dependencies +- Automatic zsh plugin installation + +#### Zsh Theme +- Two-line prompt with git integration +- Command timer for long-running commands +- Root detection (red prompt for root) +- Smart path truncation + +#### Espanso +- 100+ text expansion snippets +- Personal snippet template +- Setup script for personalization + +#### Snapper (Arch/CachyOS) +- Btrfs snapshot management functions +- limine-snapper-sync integration +- Boot menu validation + +#### Documentation +- Comprehensive README with feature overview +- Detailed SETUP_GUIDE with troubleshooting +- ESPANSO reference with all snippets +- SNAPPER guide for btrfs users + +### Changed +- Optimized `.zshrc` with lazy-loading for NVM and virtualenvwrapper +- Streamlined `adlee.zsh-theme` (removed unused functions) +- Git config now generated from `dotfiles.conf` instead of hardcoded + +### Removed +- Hardcoded git credentials from `.gitconfig` +- Redundant code in theme file +- Duplicate `export ZSH=` statements + +--- + +## Version History + +### Versioning Scheme + +- **Major** (1.x.x): Breaking changes, major feature additions +- **Minor** (x.1.x): New features, non-breaking changes +- **Patch** (x.x.1): Bug fixes, documentation updates + +### Checking Your Version + +```bash +dotfiles-version.sh +``` + +### Updating + +```bash +cd ~/.dotfiles +git pull origin main +./install.sh --skip-deps +``` + +Or use: + +```bash +update-dotfiles.sh +``` + +--- + +## Roadmap + +### Planned for 1.1.0 +- [ ] Multiple theme support with live preview +- [ ] Project scaffolding templates +- [ ] SSH key generation helper +- [ ] Machine profiles (work, personal, server) + +### Planned for 1.2.0 +- [ ] Dynamic MOTD/welcome screen +- [ ] Remote machine bootstrap script +- [ ] Neovim configuration support + +--- + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Update CHANGELOG.md +5. Bump version in `dotfiles.conf` +6. Submit a pull request diff --git a/README.md b/README.md index 65912ec..83536ec 100644 --- a/README.md +++ b/README.md @@ -6,154 +6,329 @@ Personal configuration files for a fast, consistent dev environment across Linux [![Shell](https://img.shields.io/badge/Shell-Zsh-green.svg)](https://www.zsh.org/) ``` -┌[alee@catchthesethighs]─[~/.dotfiles ⎇ main] +┌[alee@battlestation]─[~/.dotfiles ⎇ main] └% ``` -## What's Included +## ✨ Features -| Component | Description | -|-----------|-------------| -| **Zsh Theme** | Git status, command timer, smart path truncation | -| **Espanso** | 100+ text snippets (`..date`, `..gst`, `..dps`) | -| **CLI Tools** | fzf, bat, eza integrations | -| **Snapper** | Btrfs snapshot helpers for CachyOS/Arch | +| Feature | Description | +|---------|-------------| +| **Setup Wizard** | Beautiful TUI installer with feature selection | +| **Zsh Theme** | Git status, command timer, root detection | +| **Command Palette** | Raycast-style fuzzy launcher (Ctrl+Space) | +| **Smart Suggestions** | Typo correction + alias recommendations | +| **Shell Analytics** | Track command usage, get insights | +| **Secrets Vault** | Encrypted storage for API keys | +| **Dotfiles Sync** | Auto-sync across machines | +| **Espanso** | 100+ text expansion snippets | +| **Snapper** | Btrfs snapshot helpers (Arch/CachyOS) | -## Quick Start +## 🚀 Quick Start + +### One-liner Install ```bash -# One-liner curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash +``` -# Or clone first +### Interactive Wizard (Recommended) + +```bash +git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles +cd ~/.dotfiles +./install.sh --wizard +``` + +### Standard Install + +```bash git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles -cd ~/.dotfiles && ./install.sh -``` - -The installer backs up existing configs, installs oh-my-zsh + plugins, configures git, and creates symlinks. - -### Install Options - -```bash -./install.sh --skip-deps # Skip dependency check (re-runs) -./install.sh --uninstall # Remove symlinks -./install.sh --uninstall --purge # Remove everything -``` - -## Repository Layout - -``` -dotfiles/ -├── install.sh # Main installer -├── dotfiles.conf # Configuration (fork-friendly) -├── zsh/ -│ ├── .zshrc # Shell config -│ ├── themes/adlee.zsh-theme -│ └── functions/snapper.zsh -├── espanso/ -│ ├── config/default.yml -│ └── match/base.yml # 100+ snippets -├── git/.gitconfig.template # Git config template -├── vim/.vimrc -├── tmux/.tmux.conf -├── bin/ # Helper scripts -│ ├── dotfiles-doctor.sh # Health checker -│ ├── dotfiles-version.sh # Version checker -│ └── update-dotfiles.sh -└── docs/ # Extended docs -``` - -## Health Check - -Verify your installation: - -```bash -dotfiles-doctor.sh # Run diagnostics -dotfiles-doctor.sh --fix # Auto-fix issues -dotfiles-version.sh # Check for updates -``` - -## Espanso Snippets - -All triggers use `..` prefix to avoid accidents. - -| Category | Examples | -|----------|----------| -| **Time** | `..date` → 2025-12-14, `..ts` → ISO timestamp, `..epoch` | -| **Git** | `..gstat`, `..gcm`, `..branch` (current branch) | -| **Docker** | `..dps`, `..dcup`, `..dlog` | -| **Symbols** | `..shrug` → ¯\\\_(ツ)\_/¯, `..check` → ✓ | - -Full list: [docs/ESPANSO.md](docs/ESPANSO.md) - -## Theme Features - -- **Git integration** – `⎇ branch` with dirty indicator (`*`) -- **Command timer** – shows elapsed time for commands >10s -- **Smart paths** – truncates long directories -- **User detection** – blue prompt for users, red for root - -## Customization - -```bash -# Edit theme -vim ~/.dotfiles/zsh/themes/adlee.zsh-theme -source ~/.zshrc - -# Add espanso snippets -vim ~/.dotfiles/espanso/match/base.yml -espanso restart - -# Add aliases -vim ~/.dotfiles/zsh/.zshrc -``` - -## System-Wide Theme Deployment - -Share the theme across all users: - -```bash -sudo ./bin/deploy-zshtheme-systemwide.sh --all # All users -sudo ./bin/deploy-zshtheme-systemwide.sh --status # Check status -``` - -## Updating - -```bash cd ~/.dotfiles -git pull origin main ./install.sh ``` -## Snapper Integration (CachyOS/Arch) +## 📁 Repository Layout -For btrfs systems with limine-snapper-sync: - -```bash -snap-create "Before update" # Create + validate limine entry -snap-list # Recent snapshots -snap-check-limine # Verify boot menu sync +``` +dotfiles/ +├── install.sh # Main installer +├── dotfiles.conf # Central configuration +├── zsh/ +│ ├── .zshrc # Shell config +│ ├── themes/adlee.zsh-theme +│ └── functions/ +│ ├── snapper.zsh # Btrfs snapshots +│ ├── smart-suggest.zsh # Typo correction +│ └── command-palette.zsh +├── espanso/ # Text expansion +│ └── match/base.yml # 100+ snippets +├── bin/ # Utility scripts +│ ├── setup-wizard.sh # TUI installer +│ ├── dotfiles-doctor.sh # Health checker +│ ├── dotfiles-sync.sh # Multi-machine sync +│ ├── shell-stats.sh # Analytics +│ └── vault.sh # Secrets manager +├── git/.gitconfig.template +├── vim/.vimrc +├── tmux/.tmux.conf +└── docs/ ``` -## Troubleshooting +## 🎮 Command Palette -```bash -dotfiles-doctor.sh --fix # Auto-diagnose and fix +Press **Ctrl+Space** or **Ctrl+P** to open the fuzzy command launcher: + +``` +╭──────────────────────────────────────────╮ +│ ❯ git │ +├──────────────────────────────────────────┤ +│ ⎇ git status │ +│ ⎇ git pull main │ +│ ⚡ gs (alias → git status) │ +│ ↺ git commit -m "..." │ +│ ★ Edit .zshrc │ +╰──────────────────────────────────────────╯ ``` -| Issue | Fix | -|-------|-----| -| Theme not loading | `dotfiles-doctor.sh --fix` | -| Zsh plugins missing | `./install.sh` (auto-installs now) | -| Espanso not working | `espanso status`, then `espanso restart` | -| Broken symlinks | `./install.sh` | -| Want to uninstall | `./install.sh --uninstall` | +**Searches:** aliases, functions, history, bookmarks, git commands, docker commands, quick actions -## License +**Keybindings:** +- `Enter` - Execute +- `Ctrl+E` - Edit before running +- `Ctrl+Y` - Copy to clipboard + +### Directory Bookmarks + +```bash +bookmark projects ~/projects # Save +bookmark list # List all +jump projects # Go to bookmark +j # Fuzzy select +``` + +## 🔧 Smart Suggestions + +Automatic typo correction: + +```bash +$ gti status +✗ Command not found: gti +→ Did you mean: git? + +$ dokcer ps +✗ Command not found: dokcer +→ Did you mean: docker? +``` + +Alias recommendations: + +```bash +💡 Tip: You've typed 'docker-compose up -d' 15 times + Consider adding: alias dcu='docker-compose up -d' +``` + +Quick fix with `fuck`: + +```bash +$ gti status +✗ Command not found: gti +$ fuck +Running: git status +``` + +## 📊 Shell Analytics + +```bash +shell-stats.sh +``` + +``` +╔═══════════════════════════════════════════════════════════════════╗ +║ Shell Analytics Dashboard ║ +╠═══════════════════════════════════════════════════════════════════╣ +║ Total commands: 4,832 ║ +║ Unique commands: 847 ║ +║ ║ +║ Top Commands ║ +║ git 847 ████████████████████████░░░░░░ ║ +║ cd 412 ████████████░░░░░░░░░░░░░░░░░░ ║ +║ ls 398 ███████████░░░░░░░░░░░░░░░░░░░ ║ +╚═══════════════════════════════════════════════════════════════════╝ +``` + +```bash +shell-stats.sh --suggest # Alias suggestions +shell-stats.sh --heatmap # Activity by hour +shell-stats.sh --git # Git breakdown +shell-stats.sh --dirs # Most visited directories +``` + +## 🔐 Secrets Vault + +Encrypted storage for API keys and tokens: + +```bash +vault set GITHUB_TOKEN ghp_xxxxxxxxxxxx +vault set AWS_SECRET_KEY # Prompts (hidden input) +vault get GITHUB_TOKEN +vault list # Shows keys only +vault delete OLD_KEY +``` + +Export to environment: + +```bash +eval $(vault shell) # Load all secrets +``` + +Uses `age` or `gpg` encryption. Secrets auto-load on shell start. + +## 🔄 Dotfiles Sync + +Keep dotfiles synchronized across machines: + +```bash +dotfiles-sync.sh # Interactive sync +dotfiles-sync.sh --status # Show status +dotfiles-sync.sh --push # Push changes +dotfiles-sync.sh --pull # Pull changes +dotfiles-sync.sh --watch 300 # Auto-sync every 5 min +``` + +On shell start, you'll see: + +``` +⚠ Dotfiles: 3 update(s) available + Run: dotfiles-sync.sh --pull +``` + +## ⌨️ Espanso Snippets + +All triggers use `..` prefix: + +| Category | Examples | +|----------|----------| +| **Date/Time** | `..date` → 2025-12-15, `..ts` → ISO timestamp | +| **Git** | `..gstat`, `..gcm`, `..branch` (current branch) | +| **Docker** | `..dps`, `..dcup`, `..dlog` | +| **Symbols** | `..shrug` → ¯\\\_(ツ)\_/¯, `..check` → ✓ | +| **Code** | `..bash` → script template, `..python` → main template | + +Full list: [docs/ESPANSO.md](docs/ESPANSO.md) + +## 🎨 Theme Features + +``` +┌[user@hostname]─[~/projects ⎇ main *] +└% +``` + +- **Git integration** – Branch name with dirty indicator (`*`) +- **Command timer** – Shows elapsed time for commands >10s +- **Smart paths** – Truncates long directories +- **Root detection** – Red prompt for root, blue for users + +## 🩺 Health Check + +```bash +dotfiles-doctor.sh # Run diagnostics +dotfiles-doctor.sh --fix # Auto-fix issues +``` + +``` +━━━ Symlinks ━━━ +✓ Symlink valid: .zshrc +✓ Symlink valid: .gitconfig +✓ Symlink valid: adlee.zsh-theme + +━━━ Zsh Plugins ━━━ +✓ Plugin installed: zsh-autosuggestions +✓ Plugin installed: zsh-syntax-highlighting + +━━━ Summary ━━━ + Passed: 12 + Warnings: 1 + Failed: 0 +``` + +## ⚙️ Configuration + +All settings in `dotfiles.conf`: + +```bash +# Identity +USER_FULLNAME="Your Name" +USER_EMAIL="you@example.com" +GIT_USER_NAME="" # Falls back to USER_FULLNAME + +# Features +INSTALL_ZSH_PLUGINS="true" +INSTALL_FZF="ask" +INSTALL_ESPANSO="ask" + +# Advanced +ENABLE_SMART_SUGGESTIONS="true" +ENABLE_COMMAND_PALETTE="true" +ENABLE_VAULT="true" +DOTFILES_AUTO_SYNC_CHECK="true" +``` + +## 🔄 Updating + +```bash +cd ~/.dotfiles && git pull && ./install.sh +# or +update-dotfiles.sh +``` + +Check version: + +```bash +dotfiles-version.sh +``` + +## 🗑️ Uninstalling + +```bash +./install.sh --uninstall # Remove symlinks +./install.sh --uninstall --purge # Also delete ~/.dotfiles +``` + +## 📚 Documentation + +- [Setup Guide](docs/SETUP_GUIDE.md) - Detailed installation instructions +- [Espanso Reference](docs/ESPANSO.md) - All text expansion snippets +- [Snapper Guide](docs/SNAPPER.md) - Btrfs snapshot management + +## 🛠️ Install Options + +```bash +./install.sh # Standard install +./install.sh --wizard # Interactive TUI +./install.sh --skip-deps # Skip dependency check +./install.sh --uninstall # Remove symlinks +./install.sh --help # All options +``` + +## 📋 Requirements + +- **OS:** Linux (Ubuntu, Arch, Fedora) or macOS +- **Shell:** Zsh (installed automatically) +- **Optional:** fzf (for command palette), age/gpg (for vault) + +## 🤝 Forking + +1. Fork the repo +2. Edit `dotfiles.conf` with your settings +3. Customize files as needed +4. The installer will use your fork's URLs + +## 📄 License MIT – See [LICENSE](LICENSE) --- -**Author**: Aaron D. Lee -**Repo**: https://github.com/adlee-was-taken/dotfiles +**Author:** Aaron D. Lee +**Repo:** https://github.com/adlee-was-taken/dotfiles diff --git a/docs/ESPANSO.md b/docs/ESPANSO.md index deb2994..690b66d 100644 --- a/docs/ESPANSO.md +++ b/docs/ESPANSO.md @@ -10,26 +10,32 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax. | Search snippets | `ALT+SPACE` | | Restart | `espanso restart` | | Status | `espanso status` | +| View logs | `espanso log` | -## Snippet Reference +--- + +## Snippet Categories ### Date & Time -| Trigger | Output | -|---------|--------| -| `..date` | 2025-12-14 | -| `..sds` | 20251214 (filename-safe) | -| `..time` | 14:30:45 | -| `..ts` | 2025-12-14T14:30:45.123Z | -| `..utc` | 2025-12-14 14:30:45.123 UTC | -| `..dt` | 2025-12-14 14:30:45 EST | -| `..epoch` | 1702573845 | -| `..epochms` | 1702573845123 | -| `..month` | December | -| `..day` | Saturday | -| `..week` | Week 50 | +| Trigger | Output | Example | +|---------|--------|---------| +| `..date` | Current date | 2025-12-15 | +| `..sds` | Filename-safe date | 20251215 | +| `..time` | Current time | 14:30:45 | +| `..ts` | ISO timestamp | 2025-12-15T14:30:45.123Z | +| `..utc` | UTC datetime | 2025-12-15 14:30:45.123 UTC | +| `..dt` | Local datetime | 2025-12-15 14:30:45 EST | +| `..udt` | UTC datetime | 2025-12-15 14:30:45 UTC | +| `..ztime` | Time with timezone | 14:30:45.123 EST | +| `..epoch` | Unix timestamp | 1702573845 | +| `..epochms` | Unix ms timestamp | 1702573845123 | +| `..month` | Month name | December | +| `..day` | Day name | Saturday | +| `..week` | Week number | Week 50 | +| `..year` | Year | 2025 | -### Git +### Git Commands | Trigger | Output | |---------|--------| @@ -39,10 +45,12 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax. | `..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 .` | | `..branch` | Current branch name (dynamic) | -### Docker +### Docker Commands | Trigger | Output | |---------|--------| @@ -52,6 +60,7 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax. | `..dcdown` | `docker-compose down` | | `..dlog` | `docker logs -f ` | | `..dexec` | `docker exec -it ` | +| `..dim` | `docker images` | | `..dprune` | `docker system prune -af` | ### System Info @@ -73,11 +82,13 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax. | Trigger | Output | |---------|--------| -| `..mdcode` | Code block | +| `..mdcode` | Code block (triple backticks) | | `..mdbash` | Bash code block | | `..mdpy` | Python code block | +| `..mdjs` | JavaScript code block | | `..mdtable` | Table template | | `..mdlink` | Link (prompts for text/url) | +| `..mdimg` | Image (prompts for alt/url) | ### Comments @@ -87,20 +98,41 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax. | `..fixme` | `// FIXME: ` | | `..note` | `// NOTE: ` | | `..hack` | `// HACK: ` | +| `..debug` | `// DEBUG: ` | ### Quick 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` | -### Emoticons +### 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` | + +### Emoticons & Symbols | Trigger | Output | |---------|--------| @@ -111,19 +143,38 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax. | `..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 | -| `..tyvm` | Thank you very much | +| `..ack` | Acknowledged | +| `..asap` | As soon as possible | -### Auto-Corrections +### Lorem Ipsum -These work without `..` prefix: +| Trigger | Output | +|---------|--------| +| `..lorem` | One paragraph | +| `..loremlong` | Four paragraphs | + +### Clipboard + +| Trigger | Output | +|---------|--------| +| `..qp` | Paste from primary selection (X11/Wayland) | + +--- + +## Auto-Corrections + +These work without the `..` prefix: | Typo | Correction | |------|------------| @@ -136,17 +187,54 @@ These work without `..` prefix: | wierd | weird | | thier | their | -## Adding Custom Snippets +--- -Edit `~/.config/espanso/match/base.yml`: +## Personal Snippets + +Edit `~/.dotfiles/espanso/match/personal.yml`: + +```yaml +matches: + - trigger: "..myemail" + replace: "your.email@example.com" + + - trigger: "..myname" + replace: "Your Full Name" + + - trigger: "..myphone" + replace: "+1 (555) 123-4567" + + - trigger: "..sig" + replace: | + Best regards, + Your Full Name + your.email@example.com + + - trigger: "..myaddr" + replace: | + 123 Main Street + City, ST 12345 +``` + +Run `setup-espanso.sh` to configure interactively. + +--- + +## Adding Custom Snippets + +Edit `~/.dotfiles/espanso/match/base.yml`: + +### Simple Replacement ```yaml matches: - # Simple replacement - trigger: "..hw" replace: "Hello, World!" +``` - # With shell command +### With Shell Command + +```yaml - trigger: "..uptime" replace: "{{output}}" vars: @@ -154,8 +242,11 @@ matches: type: shell params: cmd: 'uptime -p' +``` - # With date +### With Date Formatting + +```yaml - trigger: "..today" replace: "Today is {{mydate}}" vars: @@ -165,34 +256,129 @@ matches: format: "%B %d, %Y" ``` +### With Form Input + +```yaml + - trigger: "..mailto" + replace: "{{name}}" + vars: + - name: email + type: form + params: + layout: "Email: {{email}}" + - name: name + type: form + params: + layout: "Display name: {{name}}" +``` + +### With Clipboard + +```yaml + - trigger: "..cliplink" + replace: "[{{clipboard}}]({{clipboard}})" + vars: + - name: clipboard + type: clipboard +``` + After editing: `espanso restart` -## Config Locations +--- + +## Config Files ``` -~/.config/espanso/ -├── config/default.yml # Settings +~/.config/espanso/ (symlinked to ~/.dotfiles/espanso/) +├── config/ +│ └── default.yml # Global settings └── match/ - ├── base.yml # Main snippets - └── personal.yml # Your info + ├── base.yml # Main snippets (100+) + ├── personal.yml # Your personal info + └── packages/ # Installed packages ``` -## Troubleshooting +--- + +## Useful Commands ```bash -espanso status # Check if running -espanso restart # Restart service -espanso log # View logs -espanso match list # List all triggers +espanso status # Check if running +espanso start # Start service +espanso restart # Restart service +espanso stop # Stop service +espanso log # View logs +espanso edit # Open config in editor +espanso match list # List all triggers +espanso path # Show config paths ``` +--- + ## Installing Packages +Browse packages: https://hub.espanso.org/ + ```bash espanso install emoji # :smile: → 😊 espanso install greek-letters # :alpha: → α espanso install math # :sum: → ∑ +espanso install lorem # More lorem ipsum options espanso package list # Show installed +espanso package uninstall # Remove package ``` -Browse more: https://hub.espanso.org/ +--- + +## Troubleshooting + +### Espanso Not Starting + +```bash +espanso service register # Register as service +espanso start +``` + +### Snippets Not Expanding + +```bash +espanso restart +espanso log # Check for errors +``` + +### Wrong Keyboard Layout + +Edit `~/.config/espanso/config/default.yml`: + +```yaml +backend: Clipboard # Try different backend +``` + +### Check Syntax + +```bash +espanso --help # Will error if YAML is invalid +espanso match list # Lists triggers if syntax is OK +``` + +### Wayland Issues + +If using Wayland, you may need the Wayland-specific build: + +```bash +# Check your session +echo $XDG_SESSION_TYPE + +# Install Wayland version if needed +# (varies by distro) +``` + +--- + +## Tips + +1. **Test snippets** - Type them in any text field +2. **Use search** - `ALT+SPACE` to search all triggers +3. **Escape triggers** - Type slowly or add a space to prevent expansion +4. **Backup config** - It's in your dotfiles, so it syncs automatically +5. **Restart after changes** - `espanso restart` diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md index 8944754..1f6cb5e 100644 --- a/docs/SETUP_GUIDE.md +++ b/docs/SETUP_GUIDE.md @@ -1,22 +1,65 @@ # Setup Guide -Step-by-step instructions for setting up and maintaining your dotfiles. +Complete guide for installing, configuring, and maintaining your dotfiles. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Installation Methods](#installation-methods) +- [Post-Install Setup](#post-install-setup) +- [Configuration](#configuration) +- [Features Guide](#features-guide) +- [Customization](#customization) +- [Multi-Machine Setup](#multi-machine-setup) +- [Troubleshooting](#troubleshooting) +- [Uninstalling](#uninstalling) + +--- ## Prerequisites +**Required:** - Git - Curl -- Zsh (will be installed if missing) +- Zsh (installed automatically if missing) -## Fresh Install +**Optional (for full features):** +- `fzf` - For command palette and fuzzy finding +- `age` or `gpg` - For secrets vault +- `gum` - For beautiful setup wizard -### Option 1: One-liner +--- + +## Installation Methods + +### Method 1: Interactive Wizard (Recommended) + +The wizard provides a beautiful TUI to customize your installation: + +```bash +git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles +cd ~/.dotfiles +./install.sh --wizard +``` + +The wizard will guide you through: +1. Identity setup (name, email, GitHub) +2. Git configuration +3. Feature selection +4. Theme choice +5. Advanced options + +### Method 2: One-liner + +Quick install with defaults: ```bash curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash ``` -### Option 2: Clone First +### Method 3: Standard Install + +Clone and run with prompts: ```bash git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles @@ -24,119 +67,443 @@ cd ~/.dotfiles ./install.sh ``` -### What the Installer Does - -1. Detects OS (Ubuntu, Arch, Fedora, macOS) -2. Installs dependencies (git, curl, zsh) -3. Backs up existing configs to `~/.dotfiles_backup_YYYYMMDD_HHMMSS/` -4. Installs oh-my-zsh -5. Installs zsh plugins (autosuggestions, syntax-highlighting) -6. Configures git (prompts for name/email if not in config) -7. Creates symlinks -8. Optionally installs espanso, fzf, bat, eza -9. Sets zsh as default shell - ### Install Options ```bash -./install.sh # Full interactive install -./install.sh --skip-deps # Skip dependency check (for re-runs) -./install.sh --deps-only # Only install dependencies -./install.sh --uninstall # Remove symlinks, offer to restore backups -./install.sh --uninstall --purge # Also remove ~/.dotfiles -./install.sh --help # Show all options +./install.sh # Interactive install +./install.sh --wizard # TUI wizard +./install.sh --skip-deps # Skip dependency installation +./install.sh --deps-only # Only install dependencies +./install.sh --uninstall # Remove symlinks +./install.sh --uninstall --purge # Remove everything +./install.sh --help # Show all options ``` -## Post-Install +--- -### Verify Installation +## Post-Install Setup + +### 1. Verify Installation ```bash -dotfiles-doctor.sh # Check health of installation -dotfiles-doctor.sh --fix # Attempt to fix issues +dotfiles-doctor.sh ``` -### Check Version +This checks: +- All symlinks are valid +- Zsh plugins installed +- Git configured +- Theme loaded +- Optional tools present + +Fix issues automatically: ```bash -dotfiles-version.sh # Show local vs remote version -dotfiles-version.sh --check # Exit 1 if updates available +dotfiles-doctor.sh --fix ``` -### Personalize Espanso +### 2. Restart Shell ```bash -./bin/setup-espanso.sh +exec zsh +# or just close and reopen your terminal ``` -Updates `personal.yml` with your name, email, etc. - -### Test It +### 3. Personalize Espanso (Optional) ```bash -source ~/.zshrc # Reload shell -echo "..date" | espanso # Test espanso (or just type ..date anywhere) +setup-espanso.sh ``` -### Install Zsh Plugins (if missing) +This sets up your personal info for text expansion (email, name, signatures). + +### 4. Set Up Secrets Vault (Optional) ```bash -git clone https://github.com/zsh-users/zsh-autosuggestions \ - ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions - -git clone https://github.com/zsh-users/zsh-syntax-highlighting \ - ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting +vault init +vault set GITHUB_TOKEN "your-token-here" +vault list ``` -## Updating +### 5. Configure Directory Bookmarks (Optional) ```bash -cd ~/.dotfiles -git pull origin main -./install.sh +bookmark projects ~/projects +bookmark work ~/work +bookmark list +``` + +--- + +## Configuration + +### Main Configuration File + +All settings are in `~/.dotfiles/dotfiles.conf`: + +```bash +# ============================================================================ +# Identity +# ============================================================================ +USER_FULLNAME="Your Name" +USER_EMAIL="you@example.com" +USER_GITHUB="yourusername" + +# ============================================================================ +# Git Configuration +# ============================================================================ +GIT_USER_NAME="" # Falls back to USER_FULLNAME +GIT_USER_EMAIL="" # Falls back to USER_EMAIL +GIT_DEFAULT_BRANCH="main" +GIT_CREDENTIAL_HELPER="store" + +# ============================================================================ +# Feature Toggles +# ============================================================================ +# Values: "true", "false", or "ask" + +INSTALL_DEPS="auto" # Auto-skip if already installed +INSTALL_ZSH_PLUGINS="true" # zsh-autosuggestions, syntax-highlighting +INSTALL_FZF="ask" +INSTALL_BAT="ask" +INSTALL_EZA="ask" +INSTALL_ESPANSO="ask" +SET_ZSH_DEFAULT="ask" + +# ============================================================================ +# Advanced Features +# ============================================================================ +ENABLE_SMART_SUGGESTIONS="true" # Typo correction +ENABLE_COMMAND_PALETTE="true" # Ctrl+Space launcher +ENABLE_SHELL_ANALYTICS="false" # Command stats +ENABLE_VAULT="true" # Encrypted secrets +DOTFILES_AUTO_SYNC_CHECK="true" # Check for updates on shell start +``` + +### Applying Configuration Changes + +After editing `dotfiles.conf`: + +```bash +./install.sh --skip-deps +# or just source ~/.zshrc ``` -Or use the helper: +--- + +## Features Guide + +### Command Palette + +**Trigger:** `Ctrl+Space` or `Ctrl+P` + +The command palette searches: +- ⚡ Aliases +- λ Functions +- ↺ Recent commands +- 📁 Bookmarked directories +- ⚙ Dotfiles scripts +- ★ Quick actions +- ⎇ Git commands (context-aware) +- ◉ Docker commands + +**Keybindings in palette:** +| Key | Action | +|-----|--------| +| `Enter` | Execute command | +| `Ctrl+E` | Edit command first | +| `Ctrl+Y` | Copy to clipboard | +| `Ctrl+R` | Refresh entries | +| `Esc` | Cancel | + +**Bookmarks:** ```bash -update-dotfiles.sh +bookmark [path] # Save bookmark (default: current dir) +bookmark list # List all bookmarks +bookmark delete # Remove bookmark +jump # Go to bookmark +j # Fuzzy select bookmark ``` -## Pushing Changes +### Smart Suggestions + +Automatically corrects 100+ common typos: + +```bash +gti → git +dokcer → docker +sl → ls +pytohn → python +``` + +Suggests aliases for frequently typed commands: + +```bash +💡 You've typed 'git status' 50 times + You already have an alias: gs +``` + +**Commands:** + +```bash +fuck # Re-run last command with typo fixed +``` + +### Shell Analytics + +```bash +shell-stats.sh # Full dashboard +shell-stats.sh --top 20 # Top 20 commands +shell-stats.sh --suggest # Alias recommendations +shell-stats.sh --heatmap # Activity by hour +shell-stats.sh --dirs # Most visited directories +shell-stats.sh --git # Git command breakdown +shell-stats.sh --docker # Docker command breakdown +shell-stats.sh --export # Export as JSON +``` + +### Secrets Vault + +Encrypted storage using `age` or `gpg`: + +```bash +vault set KEY "value" # Store (or prompt for value) +vault get KEY # Retrieve +vault list # Show all keys +vault delete KEY # Remove +vault shell # Print as export statements +vault export backup.enc # Backup encrypted vault +vault import backup.enc # Restore vault +vault status # Show vault info +``` + +**Auto-loading:** Secrets are automatically loaded into your environment on shell start. + +### Dotfiles Sync + +```bash +dotfiles-sync.sh # Interactive sync +dotfiles-sync.sh --status # Show sync status +dotfiles-sync.sh --push # Push local changes +dotfiles-sync.sh --pull # Pull remote changes +dotfiles-sync.sh --diff # Show local changes +dotfiles-sync.sh --watch 300 # Auto-sync every 5 minutes +dotfiles-sync.sh --log # Show sync history +``` + +**Auto-check:** On shell start, you'll be notified of available updates. + +--- + +## Customization + +### Adding Aliases + +Edit `~/.dotfiles/zsh/.zshrc`: + +```bash +# Custom aliases +alias projects='cd ~/projects' +alias k='kubectl' +alias tf='terraform' +``` + +### Machine-Specific Config + +Create `~/.zshrc.local` (not tracked by git): + +```bash +# Work machine +export CORP_PROXY="http://proxy:8080" +export WORK_EMAIL="me@company.com" + +# Local paths +export PATH="$HOME/work-tools/bin:$PATH" +``` + +### Custom Espanso Snippets + +Edit `~/.dotfiles/espanso/match/personal.yml`: + +```yaml +matches: + - trigger: "..myemail" + replace: "your.email@example.com" + + - trigger: "..sig" + replace: | + Best regards, + Your Name +``` + +### Theme Customization + +Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme`: + +```zsh +# Change colors +typeset -g COLOR_GREEN='%{$FG[118]%}' +typeset -g COLOR_BLUE='%{$FG[069]%}' + +# Change timer threshold (seconds) +typeset -g TIMER_THRESHOLD=10 +``` + +--- + +## Multi-Machine Setup + +### Initial Setup on New Machine + +```bash +# Clone your dotfiles +git clone https://github.com/YOUR_USER/dotfiles.git ~/.dotfiles +cd ~/.dotfiles +./install.sh +``` + +### Syncing Changes + +**On Machine A (make changes):** ```bash cd ~/.dotfiles -git add . -git commit -m "Update aliases" -git push origin main +# Edit files... +dotfiles-sync.sh --push "Added new aliases" ``` -## Multi-Machine Sync +**On Machine B (get changes):** ```bash -# Machine A: push changes -cd ~/.dotfiles && git add . && git commit -m "Update" && git push - -# Machine B: pull changes -cd ~/.dotfiles && git pull && source ~/.zshrc +dotfiles-sync.sh --pull +source ~/.zshrc ``` -## File Structure +### Automatic Sync -| Path | Purpose | -|------|---------| -| `zsh/.zshrc` | Main shell config | -| `zsh/themes/adlee.zsh-theme` | Prompt theme | -| `zsh/functions/snapper.zsh` | Btrfs snapshot helpers | -| `espanso/match/base.yml` | Text snippets | -| `espanso/match/personal.yml` | Your personal info | -| `git/.gitconfig` | Git settings | -| `vim/.vimrc` | Vim config | -| `tmux/.tmux.conf` | Tmux config | -| `bin/` | Utility scripts | +Enable watch mode (runs in background): -## Symlinks Created +```bash +dotfiles-sync.sh --watch 300 # Check every 5 minutes +``` + +Or add to crontab: + +```bash +*/30 * * * * ~/.dotfiles/bin/dotfiles-sync.sh --auto +``` + +--- + +## Troubleshooting + +### Run the Doctor First + +```bash +dotfiles-doctor.sh --fix +``` + +### Common Issues + +| Issue | Solution | +|-------|----------| +| Theme not loading | Check `ZSH_THEME="adlee"` in .zshrc, run `source ~/.zshrc` | +| Zsh plugins missing | Run `./install.sh` (auto-installs plugins now) | +| Command palette not working | Install fzf: `./install.sh` will prompt | +| Vault errors | Install age: `brew install age` or `pacman -S age` | +| Espanso not expanding | Run `espanso status`, then `espanso restart` | +| Sync conflicts | Run `dotfiles-sync.sh --conflicts` to see conflicts | +| Symlinks broken | Run `./install.sh --skip-deps` to recreate | + +### Manual Fixes + +**Reinstall zsh plugins:** + +```bash +rm -rf ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions +rm -rf ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting +./install.sh --skip-deps +``` + +**Reset git config:** + +```bash +rm ~/.gitconfig +./install.sh --skip-deps +``` + +**Fix permissions:** + +```bash +chmod +x ~/.dotfiles/install.sh +chmod +x ~/.dotfiles/bin/* +``` + +### Getting Help + +```bash +# Any script +