From 11e1e8d06e9a5d289c455dbad92211091c09db91 Mon Sep 17 00:00:00 2001 From: "Aaron D. Lee" Date: Sun, 14 Dec 2025 15:27:09 -0500 Subject: [PATCH] Now with more & cleaner docs (probably). --- README.md | 401 +++++++----------------------------- docs/ESPANSO.md | 488 +++++++++----------------------------------- docs/SETUP_GUIDE.md | 408 ++++++++++++++++-------------------- docs/SNAPPER.md | 137 +++++++++++++ 4 files changed, 491 insertions(+), 943 deletions(-) create mode 100644 docs/SNAPPER.md diff --git a/README.md b/README.md index 6a7d5d4..66c0160 100644 --- a/README.md +++ b/README.md @@ -1,374 +1,131 @@ # ADLee's Dotfiles -> Personal configuration files and automation scripts for a powerful, consistent development environment across Linux/macOS systems. +Personal configuration files for a fast, consistent dev environment across Linux/macOS. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Shell](https://img.shields.io/badge/Shell-Zsh-green.svg)](https://www.zsh.org/) -[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/adlee-was-taken/dotfiles/graphs/commit-activity) - -## Preview ``` -┌[alee@hostname]─[~/.dotfiles]-[main *] +┌[alee@catchthesethighs]─[~/.dotfiles ⎇ main] └% ``` -## Features +## What's Included -### Custom Zsh Theme -- **adlee.zsh-theme** - A feature-rich, performant zsh theme - - Git branch/status integration with visual indicators - - Command execution timer (shows time for commands > 10s) - - Smart path truncation for long directories - - User/root detection (blue prompt for users, red for root) - - Clean, minimal design that's easy to read +| 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 | -### Espanso Text Expansion -- **100+ pre-configured snippets** using `..trigger` syntax - - Date/time stamps (UTC, local, ISO 8601) - - Git shortcuts (`..gst`, `..gco`, `..gcm`) - - Docker commands (`..dps`, `..dcup`, `..dlog`) - - Code templates (bash, python, markdown) - - System info (`..ip`, `..user`, `..branch`) - - Common typo corrections - - Personal information templates +## Quick Start -### Modern CLI Tools -- **fzf** - Fuzzy finder for files and history -- **bat** - Syntax-highlighted file viewer -- **eza** - Modern ls replacement with icons -- **espanso** - Universal text expander +```bash +# One-liner +curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash -### Easy Deployment -- **One-command installation** on new systems -- **Automated backups** of existing configs -- **System-wide theme deployment** for all users -- **Modular architecture** for easy customization +# Or clone first +git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles +cd ~/.dotfiles && ./install.sh +``` -## Repository Structure +The installer backs up existing configs, installs oh-my-zsh, and creates symlinks. + +## Repository Layout ``` dotfiles/ -├── install.sh # Main installation script -├── README.md # This file -├── LICENSE # MIT License -├── .gitignore # Git ignore rules -│ +├── install.sh # Main installer ├── zsh/ -│ ├── .zshrc # Main zsh configuration -│ └── themes/ -│ └── adlee.zsh-theme # Custom zsh theme -│ +│ ├── .zshrc # Shell config +│ ├── themes/adlee.zsh-theme +│ └── functions/snapper.zsh ├── espanso/ -│ ├── config/ -│ │ └── default.yml # Espanso settings -│ └── match/ -│ ├── base.yml # Base snippets (100+ triggers) -│ └── personal.yml # Personal info snippets -│ -├── git/ -│ ├── .gitconfig # Git configuration -│ └── .gitignore_global # Global gitignore patterns -│ -├── vim/ -│ └── .vimrc # Vim configuration -│ -├── tmux/ -│ └── .tmux.conf # Tmux configuration -│ -├── bin/ -│ ├── update-dotfiles.sh # Update from repo -│ ├── setup-espanso.sh # Espanso setup wizard -│ └── deploy-zshtheme-systemwide.sh # System-wide deployment -│ -└── docs/ - ├── SETUP_GUIDE.md # Detailed setup instructions - └── ESPANSO.md # Espanso reference guide +│ ├── config/default.yml +│ └── match/base.yml # 100+ snippets +├── git/.gitconfig +├── vim/.vimrc +├── tmux/.tmux.conf +├── bin/ # Helper scripts +└── docs/ # Extended docs ``` -## 🚀 Quick Start +## Espanso Snippets -### Option 1: One-Line Install (Recommended) +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 -curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | 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 ``` -### Option 2: Manual Install +## System-Wide Theme Deployment + +Share the theme across all users: ```bash -# Clone the repository -git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles -cd ~/.dotfiles - -# Run the installer -./install.sh +sudo ./bin/deploy-zshtheme-systemwide.sh --all # All users +sudo ./bin/deploy-zshtheme-systemwide.sh --status # Check status ``` -### What Gets Installed? - -The installer will: -1. Detect your OS (Ubuntu, Arch, Fedora, macOS) -2. Install dependencies (git, curl, zsh) -3. Backup existing configs to `~/.dotfiles_backup_YYYYMMDD_HHMMSS/` -4. Install oh-my-zsh -5. Create symlinks to dotfiles -6. Optionally install espanso, fzf, bat, eza -7. Set zsh as default shell - -## ⚙️ Post-Installation - -### Set Up Espanso - -Personalize your text expansion snippets: - -```bash -cd ~/.dotfiles -./bin/setup-espanso.sh -``` - -This wizard will: -- Update `personal.yml` with your name, email, etc. -- Install optional espanso packages (emoji, math symbols) -- Show you useful triggers and tips - -### Test Espanso - -Try typing these anywhere: -- `..date` → 2025-12-13 -- `..time` → 14:30:45 -- `..ip` → Your public IP -- `..shrug` → ¯\\\_(ツ)_/¯ - -Toggle espanso: `ALT+SHIFT+E` -Search snippets: `ALT+SPACE` - -### Deploy Theme System-Wide (Optional) - -To share the theme across all users on your system: - -```bash -cd ~/.dotfiles -sudo ./bin/deploy-zshtheme-systemwide.sh --all -``` - -Options: -- `--all` - Deploy to all users with oh-my-zsh -- `--current` - Deploy to current user + root only -- `--status` - Show deployment status -- `--force` - Force replace existing links - ## Updating -### Update Dotfiles from GitHub - ```bash cd ~/.dotfiles git pull origin main -./install.sh # Re-link updated files -``` - -Or use the helper script: - -```bash -update-dotfiles.sh -``` - -### Push Changes to GitHub - -```bash -cd ~/.dotfiles -git add . -git commit -m "Update theme colors" -git push origin main -``` - -## Customization - -### Modify the Zsh Theme - -```bash -vim ~/.dotfiles/zsh/themes/adlee.zsh-theme -source ~/.zshrc # Test changes -``` - -### Add Custom Aliases - -Edit `~/.dotfiles/zsh/.zshrc` and add to the aliases section: - -```bash -# Custom aliases -alias projects='cd ~/projects' -alias dc='docker-compose' -``` - -### Add Espanso Snippets - -Edit `~/.dotfiles/espanso/match/base.yml`: - -```yaml -matches: - - trigger: "..myproject" - replace: "cd ~/projects/my-awesome-project" -``` - -Then restart espanso: -```bash -espanso restart -``` - -## Documentation - -- **[SETUP_GUIDE.md](docs/SETUP_GUIDE.md)** - Detailed setup instructions -- **[ESPANSO.md](docs/ESPANSO.md)** - Complete espanso reference -- **[Zsh Theme Variables](zsh/themes/adlee.zsh-theme)** - Customize colors and format - -## Espanso Quick Reference - -### Date & Time -| Trigger | Output | -|---------|--------| -| `..date` | 2025-12-13 | -| `..time` | 14:30:45 | -| `..ts` | 2025-12-13T14:30:45.123Z | -| `..epoch` | 1702476645 | - -### Git Shortcuts -| Trigger | Output | -|---------|--------| -| `..gst` | `git status` | -| `..gco` | `git checkout ` | -| `..gcm` | `git commit -m ""` | -| `..branch` | Current git branch name | - -### System Info -| Trigger | Output | -|---------|--------| -| `..user` | Current username | -| `..host` | Hostname | -| `..ip` | Public IP address | -| `..pwd` | Current directory | - -### Emoticons -| Trigger | Output | -|---------|--------| -| `..shrug` | ¯\\\_(ツ)_/¯ | -| `..flip` | (╯°□°)╯︵ ┻━┻ | -| `..check` | ✓ | - -[See full list in ESPANSO.md](docs/ESPANSO.md) - -## Multi-System Setup - -### Deploy to New System - -```bash -# On the new system -git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles -cd ~/.dotfiles ./install.sh ``` -### Sync Changes Between Systems +## Snapper Integration (CachyOS/Arch) + +For btrfs systems with limine-snapper-sync: ```bash -# On system A (make changes) -cd ~/.dotfiles -git add . -git commit -m "Update aliases" -git push - -# On system B (pull changes) -cd ~/.dotfiles -git pull -source ~/.zshrc +snap-create "Before update" # Create + validate limine entry +snap-list # Recent snapshots +snap-check-limine # Verify boot menu sync ``` ## Troubleshooting -### Theme Not Loading - -Ensure `ZSH_THEME="adlee"` in `~/.zshrc`: -```bash -grep ZSH_THEME ~/.zshrc -``` - -Then reload: -```bash -source ~/.zshrc -``` - -### Espanso Not Expanding - -Check if espanso is running: -```bash -espanso status -``` - -If not running: -```bash -espanso service start -``` - -View logs: -```bash -espanso log -``` - -### Symlinks Broken - -Remove broken symlinks: -```bash -find ~ -maxdepth 1 -type l -xtype l -delete -``` - -Re-run installation: -```bash -cd ~/.dotfiles && ./install.sh -``` - -### Permission Errors - -Make scripts executable: -```bash -chmod +x ~/.dotfiles/install.sh -chmod +x ~/.dotfiles/bin/* -``` - -## Contributing - -This is a personal dotfiles repository, but suggestions and improvements are welcome! - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/improvement`) -3. Commit your changes (`git commit -m 'Add some improvement'`) -4. Push to the branch (`git push origin feature/improvement`) -5. Open a Pull Request +| Issue | Fix | +|-------|-----| +| Theme not loading | Check `ZSH_THEME="adlee"` in ~/.zshrc, then `source ~/.zshrc` | +| Espanso not working | `espanso status`, then `espanso restart` | +| Broken symlinks | `cd ~/.dotfiles && ./install.sh` | ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. - -## Acknowledgments - -- [oh-my-zsh](https://ohmyz.sh/) - Zsh configuration framework -- [espanso](https://espanso.org/) - Text expander -- [vimrc](https://github.com/amix/vimrc) - Ultimate virmrc by amix -- [fzf](https://github.com/junegunn/fzf) - Fuzzy finder -- [bat](https://github.com/sharkdp/bat) - Cat clone with syntax highlighting -- [eza](https://github.com/eza-community/eza) - Modern ls replacement - -## Resources - -- [Arch Linux Wiki: Dotfiles](https://wiki.archlinux.org/title/Dotfiles) -- [GitHub: Awesome Dotfiles](https://github.com/webpro/awesome-dotfiles) -- [Espanso Hub](https://hub.espanso.org/) +MIT – See [LICENSE](LICENSE) --- **Author**: Aaron D. Lee -**Repository**: https://github.com/adlee-was-taken/dotfiles -**Last Updated**: 2025-12-13 - -If you find this useful, consider giving it a star!# dotfiles -Aaron D. Lee's dotfiles for Linux/MacOs +**Repo**: https://github.com/adlee-was-taken/dotfiles diff --git a/docs/ESPANSO.md b/docs/ESPANSO.md index e6406c1..deb2994 100644 --- a/docs/ESPANSO.md +++ b/docs/ESPANSO.md @@ -1,92 +1,35 @@ -# Espanso Quick Reference Guide +# Espanso Quick Reference -A comprehensive guide to using espanso text expansion with Aaron D. Lee's custom configuration. +Text expansion with 100+ pre-configured snippets using `..trigger` syntax. -> **Last Updated**: 2025-12-14 - -## 🚀 Getting Started - -### Installation - -Espanso is automatically installed when you run the main install script: - -```bash -./install.sh -``` - -Or install it separately: - -```bash -# Arch Linux -paru -S espanso-bin -espanso service register - -# Ubuntu/Debian -wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb -sudo apt install ./espanso-debian-x11-amd64.deb -espanso service register - -# macOS -brew tap espanso/espanso -brew install espanso -espanso service register -``` - -### Initial Setup - -Run the setup wizard to personalize your configuration: - -```bash -cd ~/.dotfiles -./bin/setup-espanso.sh -``` - -This will: -- Personalize your snippets with your information -- Install optional espanso packages -- Show you useful triggers and tips - -## ⌨️ Basic Controls +## Controls | Action | Shortcut | |--------|----------| -| Toggle espanso on/off | `ALT+SHIFT+E` | -| Open search menu | `ALT+SPACE` | -| Restart espanso | `espanso restart` | -| Check status | `espanso status` | +| Toggle on/off | `ALT+SHIFT+E` | +| Search snippets | `ALT+SPACE` | +| Restart | `espanso restart` | +| Status | `espanso status` | -## Complete Snippet Reference +## Snippet Reference -All triggers use the `..` prefix for consistency and to avoid accidental expansion. +### Date & Time -### Date & Time Stamps +| 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-14` | -| `..ds` | Date stamp (alias) | `2025-12-14` | -| `..sds` | Short date (filename safe) | `20251214` | -| `..ts` | UTC ISO 8601 timestamp | `2025-12-14T14:30:45.123Z` | -| `..time` | Current time | `14:30:45` | -| `..utime` | UTC time | `14:30:45` | -| `..ztime` | Time with timezone | `14:30:45.123 EST` | -| `..uztime` | UTC time with timezone | `14:30:45.123 UTC` | -| `..dt` | Date/time with timezone | `2025-12-14 14:30:45 EST` | -| `..udt` | UTC date/time | `2025-12-14 14:30:45 UTC` | -| `..utc` | Full UTC timestamp | `2025-12-14 14:30:45.123 UTC` | -| `..month` | Current month name | `December` | -| `..year` | Current year | `2025` | -| `..week` | Week number | `Week 50` | -| `..day` | Day of week | `Saturday` | - -### Unix Timestamps - -| Trigger | Output | Example | -|---------|--------|---------| -| `..epoch` | Unix timestamp (seconds) | `1702573845` | -| `..epochms` | Unix timestamp (milliseconds) | `1702573845123` | - -### Git Shortcuts +### Git | Trigger | Output | |---------|--------| @@ -96,12 +39,10 @@ All triggers use the `..` prefix for consistency and to avoid accidental expansi | `..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 git branch name | +| `..branch` | Current branch name (dynamic) | -### Docker Shortcuts +### Docker | Trigger | Output | |---------|--------| @@ -111,106 +52,34 @@ All triggers use the `..` prefix for consistency and to avoid accidental expansi | `..dcdown` | `docker-compose down` | | `..dlog` | `docker logs -f ` | | `..dexec` | `docker exec -it ` | -| `..dim` | `docker images` | | `..dprune` | `docker system prune -af` | -### System Information +### System Info -| Trigger | Output | Description | -|---------|--------|-------------| -| `..ip` | Your public IP | Via ifconfig.me | -| `..locip` | Your local IP | From hostname -i | +| Trigger | Output | +|---------|--------| +| `..ip` | Public IP (via curl) | +| `..locip` | Local IP | ### Code Templates | Trigger | Output | |---------|--------| -| `..bash` | Bash script template with shebang and error handling | -| `..python` | Python script template with main function | -| `..she!` | `#!/usr/bin/env bash` (shebang only) | +| `..bash` | Bash script with shebang + `set -euo pipefail` | +| `..python` | Python script with main() | +| `..she!` | `#!/usr/bin/env bash` | -**Bash Template:** -```bash -#!/usr/bin/env bash - -set -euo pipefail - -``` - -**Python Template:** -```python -#!/usr/bin/env python3 - -def main(): - pass - -if __name__ == "__main__": - main() -``` - -### Markdown Helpers +### Markdown | Trigger | Output | |---------|--------| -| `..mdcode` | Markdown code block | +| `..mdcode` | Code block | | `..mdbash` | Bash code block | | `..mdpy` | Python code block | -| `..mdjs` | JavaScript code block | -| `..mdtable` | Markdown table template | -| `..mdlink` | Markdown link (interactive) | -| `..mdimg` | Markdown image (interactive) | +| `..mdtable` | Table template | +| `..mdlink` | Link (prompts for text/url) | -**Table Template:** -```markdown -| Column 1 | Column 2 | Column 3 | -|----------|----------|----------| -| Cell 1 | Cell 2 | Cell 3 | -``` - -### Emoticons & Symbols - -| 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 | - -### File Paths & Navigation - -| Trigger | Output | -|---------|--------| -| `..~` | `cd ~` | -| `..tmp` | `cd /tmp/` | -| `..logs` | `cd /var/log/` | - -### Common URLs - -| Trigger | Output | -|---------|--------| -| `..gh` | https://github.com | -| `..gl` | https://gitlab.com | -| `..gist` | https://gist.github.com | -| `..so` | https://stackoverflow.com | -| `..reddit` | https://reddit.com | - -### Programming Comments +### Comments | Trigger | Output | |---------|--------| @@ -218,68 +87,75 @@ if __name__ == "__main__": | `..fixme` | `// FIXME: ` | | `..note` | `// NOTE: ` | | `..hack` | `// HACK: ` | -| `..debug` | `// DEBUG: ` | -### Common Commands +### 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` | -### Lorem Ipsum +### Emoticons | Trigger | Output | |---------|--------| -| `..lorem` | Single paragraph | -| `..loremlong` | Extended lorem ipsum (4 sentences) | +| `..shrug` | ¯\\\_(ツ)\_/¯ | +| `..flip` | (╯°□°)╯︵ ┻━┻ | +| `..unflip` | ┬─┬ ノ( ゜-゜ノ) | +| `..lenny` | ( ͡° ͜ʖ ͡°) | +| `..check` | ✓ | +| `..cross` | ✗ | +| `..arrow` | → | + +### Quick Responses + +| Trigger | Output | +|---------|--------| +| `..brb` | Be right back | +| `..lgtm` | Looks good to me | +| `..wfm` | Works for me | +| `..tyvm` | Thank you very much | ### Auto-Corrections -These work automatically without the `..` prefix: +These work without `..` prefix: | Typo | Correction | |------|------------| -| `teh` | the | -| `recieve` | receive | -| `seperator` | separator | -| `definately` | definitely | -| `occured` | occurred | -| `lenght` | length | -| `wierd` | weird | -| `thier` | their | +| teh | the | +| recieve | receive | +| definately | definitely | +| seperator | separator | +| occured | occurred | +| lenght | length | +| wierd | weird | +| thier | their | -## Creating Custom Snippets +## Adding Custom Snippets -Edit your snippet files: - -```bash -# Base snippets (general use) -vim ~/.config/espanso/match/base.yml - -# Personal snippets (your info) -vim ~/.config/espanso/match/personal.yml -``` - -### Simple Text Replacement +Edit `~/.config/espanso/match/base.yml`: ```yaml matches: + # Simple replacement - trigger: "..hw" replace: "Hello, World!" -``` -### With Date Variables + # With shell command + - trigger: "..uptime" + replace: "{{output}}" + vars: + - name: output + type: shell + params: + cmd: 'uptime -p' -```yaml -matches: + # With date - trigger: "..today" replace: "Today is {{mydate}}" vars: @@ -289,204 +165,34 @@ matches: format: "%B %d, %Y" ``` -### With Shell Commands +After editing: `espanso restart` + +## Config Locations -```yaml -matches: - - trigger: "..uptime" - replace: "{{output}}" - vars: - - name: output - type: shell - params: - cmd: 'uptime -p' ``` - -### Multi-line Templates - -```yaml -matches: - - trigger: "..header" - replace: | - # ============================================================================ - # {{title}} - # Author: Aaron D. Lee - # Date: {{date}} - # ============================================================================ - vars: - - name: title - type: form - params: - layout: "Title: {{title}}" - - name: date - type: date - params: - format: "%Y-%m-%d" +~/.config/espanso/ +├── config/default.yml # Settings +└── match/ + ├── base.yml # Main snippets + └── personal.yml # Your info ``` -## Package Management - -### List Installed Packages - -```bash -espanso package list -``` - -### Install Additional Packages - -```bash -# Emoji support -espanso install emoji --force - -# Greek letters -espanso install greek-letters --force - -# Math symbols -espanso install math --force - -# Complete emoji collection -espanso install all-emojis --force -``` - -### Browse Available Packages - -Visit: https://hub.espanso.org/ - -## Configuration - -### Main Configuration - -Location: `~/.config/espanso/config/default.yml` - -Key settings: - -```yaml -# Toggle key -toggle_key: ALT+SHIFT+E - -# Search shortcut -search_shortcut: ALT+SPACE - -# Backend -backend: Auto - -# Show notifications -show_notifications: true - -# Auto-restart on config changes -auto_restart: true -``` - -### Match Files - -- `~/.config/espanso/match/base.yml` - Main snippets (100+ triggers) -- `~/.config/espanso/match/personal.yml` - Personal information - ## Troubleshooting -### Espanso Not Working +```bash +espanso status # Check if running +espanso restart # Restart service +espanso log # View logs +espanso match list # List all triggers +``` -1. Check if running: - ```bash - espanso status - ``` - -2. Restart the service: - ```bash - espanso restart - ``` - -3. Check logs: - ```bash - espanso log - ``` - -### Snippets Not Expanding - -1. Verify the trigger syntax in your YAML files -2. Check for YAML syntax errors: - ```bash - espanso match list - ``` -3. Ensure espanso is enabled (not toggled off with `ALT+SHIFT+E`) - -### Test a Specific Trigger +## Installing Packages ```bash -# List all matches -espanso match list | grep "..date" - -# Check if trigger is recognized -espanso match list | grep "trigger" +espanso install emoji # :smile: → 😊 +espanso install greek-letters # :alpha: → α +espanso install math # :sum: → ∑ +espanso package list # Show installed ``` -## Pro Tips - -1. **Consistent Naming**: All triggers use `..` prefix to avoid accidents -2. **Quick Testing**: Type trigger in any text field to test immediately -3. **Search Feature**: Use `ALT+SPACE` to search all available snippets -4. **Restart After Changes**: `espanso restart` after editing YAML files -5. **Check Logs**: Use `espanso log` to debug issues -6. **Backup Your Config**: Your espanso config is in your dotfiles repo! - -## Common Workflows - -### Developer Workflow - -``` -..gstat → Check git status -..gadd → Stage all changes -..gcm → Commit with message -..gpush → Push to remote -``` - -### Documentation Writing - -``` -..date → Add current date -..mdcode → Insert code block -..mdtable → Create table -..todo → Add TODO comment -``` - -### System Administration - -``` -..dps → Check running containers -..disk → Check disk usage -..mem → Check memory usage -..port → Check port usage -``` - -## Syncing Across Systems - -Your espanso config is part of your dotfiles: - -```bash -# On system A (after making changes) -cd ~/.dotfiles -git add espanso/ -git commit -m "Update espanso snippets" -git push - -# On system B (pull changes) -cd ~/.dotfiles -git pull -espanso restart -``` - -## Resources - -- [Official Documentation](https://espanso.org/docs/) -- [Package Hub](https://hub.espanso.org/) -- [GitHub Repository](https://github.com/espanso/espanso) -- [Community Forum](https://github.com/espanso/espanso/discussions) - ---- - -**Configuration Location**: `~/.config/espanso/` -**Total Triggers**: 100+ pre-configured -**Custom Prefix**: `..` (double period) -**Last Updated**: 2025-12-14 - -Add your own snippets to `personal.yml` for custom shortcuts! +Browse more: https://hub.espanso.org/ diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md index 85d5b78..446486f 100644 --- a/docs/SETUP_GUIDE.md +++ b/docs/SETUP_GUIDE.md @@ -1,278 +1,226 @@ -# Dotfiles Repository Setup Checklist +# Setup Guide -Use this checklist to ensure your dotfiles repository is complete and ready to use. +Step-by-step instructions for setting up and maintaining your dotfiles. -## 📋 File Structure +## Prerequisites -### Core Files -- [ ] `README.md` - Main documentation (use the artifact provided) -- [ ] `LICENSE` - MIT License file -- [ ] `.gitignore` - Git ignore rules -- [ ] `install.sh` - Main installation script +- Git +- Curl +- Zsh (will be installed if missing) -### Zsh Configuration -- [ ] `zsh/.zshrc` - Main zsh config -- [ ] `zsh/themes/adlee.zsh-theme` - Custom theme -- [ ] `zsh/.zshrc.local.example` - Template for local settings (optional) +## Fresh Install -### Espanso Configuration -- [ ] `espanso/config/default.yml` - Espanso settings -- [ ] `espanso/match/base.yml` - Base snippets -- [ ] `espanso/match/personal.yml` - Personal snippets +### Option 1: One-liner -### Git Configuration -- [ ] `git/.gitconfig` - Git settings -- [ ] `git/.gitignore_global` - Global gitignore (optional) +```bash +curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash +``` -### Other Configs -- [ ] `vim/.vimrc` - Vim config (if you use vim) -- [ ] `tmux/.tmux.conf` - Tmux config (if you use tmux) +### Option 2: Clone First -### Utility Scripts -- [ ] `bin/update-dotfiles` - Update script -- [ ] `bin/setup-espanso.sh` - Espanso wizard -- [ ] `bin/deploy-zshtheme-systemwide.sh` - System-wide deployment +```bash +git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles +cd ~/.dotfiles +./install.sh +``` -### Documentation -- [ ] `docs/SETUP_GUIDE.md` - Detailed setup guide -- [ ] `docs/ESPANSO.md` - Espanso reference -- [ ] `CHECKLIST.md` - This file +### What the Installer Does -## 🔧 Setup Steps +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. Creates symlinks +6. Optionally installs espanso, fzf, bat, eza +7. Sets zsh as default shell + +## Post-Install + +### Personalize Espanso + +```bash +./bin/setup-espanso.sh +``` + +Updates `personal.yml` with your name, email, etc. + +### Test It + +```bash +source ~/.zshrc # Reload shell +echo "..date" | espanso # Test espanso (or just type ..date anywhere) +``` + +### Install Zsh Plugins (if missing) + +```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 +``` + +## Updating -### 1. Create Directory Structure ```bash cd ~/.dotfiles -mkdir -p zsh/themes -mkdir -p espanso/config espanso/match -mkdir -p git -mkdir -p vim -mkdir -p tmux -mkdir -p bin -mkdir -p docs +git pull origin main +./install.sh +source ~/.zshrc ``` -### 2. Create/Copy Configuration Files - -- [ ] Copy your existing `.zshrc` to `zsh/.zshrc` -- [ ] Copy your theme to `zsh/themes/adlee.zsh-theme` -- [ ] Copy espanso configs from `~/.config/espanso/` to `espanso/` -- [ ] Copy `.gitconfig` to `git/.gitconfig` -- [ ] Copy `.vimrc` to `vim/.vimrc` (if exists) -- [ ] Copy `.tmux.conf` to `tmux/.tmux.conf` (if exists) - -### 3. Create Scripts - -Download or create these scripts from the artifacts: -- [ ] `install.sh` -- [ ] `bin/update-dotfiles` -- [ ] `bin/setup-espanso.sh` -- [ ] `bin/deploy-zshtheme-systemwide.sh` - -Make them executable: -```bash -chmod +x install.sh -chmod +x bin/* -``` - -### 4. Create Documentation - -- [ ] Create `README.md` (use artifact provided) -- [ ] Create `docs/SETUP_GUIDE.md` (artifact provided earlier) -- [ ] Create `docs/ESPANSO.md` (artifact provided earlier) - -### 5. Create .gitignore +Or use the helper: ```bash -cat > .gitignore << 'EOF' -# OS files -.DS_Store -Thumbs.db - -# Backup files -*.backup -*.bak -*~ - -# Local machine-specific configs -*.local -.zshrc.local - -# Sensitive information -.env -.env.* -secrets/ - -# Optional: Uncomment if personal espanso info is sensitive -# espanso/match/personal.yml - -# Espanso backup files -espanso/match/*.backup -EOF +update-dotfiles.sh ``` -### 6. Create LICENSE +## Pushing Changes -```bash -cat > LICENSE << 'EOF' -MIT License - -Copyright (c) 2025 Aaron D. Lee - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -EOF -``` - -## 🐙 GitHub Setup - -### 1. Create Repository -- [ ] Go to https://github.com/new -- [ ] Name: `dotfiles` -- [ ] Description: "Personal configuration files and automation scripts" -- [ ] Visibility: Public or Private -- [ ] Don't initialize with README (you already have one) -- [ ] Click "Create repository" - -### 2. Initialize Git ```bash cd ~/.dotfiles -git init git add . -git commit -m "Initial commit: Add dotfiles and custom zsh theme" +git commit -m "Update aliases" +git push origin main ``` -### 3. Add Remote and Push -```bash -# Replace adlee-was-taken with your GitHub username -git remote add origin https://github.com/adlee-was-taken/dotfiles.git -git branch -M main -git push -u origin main -``` - -### 4. Update URLs in Files -- [ ] Update `install.sh` - Replace `adlee-was-taken` in `DOTFILES_REPO` -- [ ] Update `README.md` - Replace all `adlee-was-taken` references -- [ ] Update `docs/SETUP_GUIDE.md` - Replace `adlee-was-taken` +## Multi-Machine Sync ```bash -# Quick find all instances -grep -r "adlee-was-taken" . +# Machine A: push changes +cd ~/.dotfiles && git add . && git commit -m "Update" && git push + +# Machine B: pull changes +cd ~/.dotfiles && git pull && source ~/.zshrc ``` -## ✅ Verification +## File Structure -### Test Local Installation -- [ ] Test install script on local machine - ```bash - # Dry run first - bash -n install.sh # Check for syntax errors - - # Then test (will backup existing configs) - ./install.sh - ``` +| 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 | -- [ ] Verify symlinks were created correctly - ```bash - ls -la ~ | grep "^l" # Show all symlinks in home - ``` +## Symlinks Created -- [ ] Test zsh theme - ```bash - source ~/.zshrc - # Check if prompt looks correct - ``` +| Source | Target | +|--------|--------| +| `~/.dotfiles/zsh/.zshrc` | `~/.zshrc` | +| `~/.dotfiles/zsh/themes/adlee.zsh-theme` | `~/.oh-my-zsh/themes/adlee.zsh-theme` | +| `~/.dotfiles/git/.gitconfig` | `~/.gitconfig` | +| `~/.dotfiles/vim/.vimrc` | `~/.vimrc` | +| `~/.dotfiles/tmux/.tmux.conf` | `~/.tmux.conf` | +| `~/.dotfiles/espanso/` | `~/.config/espanso` | -- [ ] Test espanso - ```bash - espanso status - # Try typing: ..date - ``` +## System-Wide Theme -### Test GitHub Setup -- [ ] Clone on a test directory - ```bash - cd /tmp - git clone https://github.com/adlee-was-taken/dotfiles.git test-dotfiles - cd test-dotfiles - ./install.sh - ``` +Deploy to all users on a system: -### Test System-wide Deployment -- [ ] Check current status - ```bash - sudo ./bin/deploy-zshtheme-systemwide.sh --status - ``` +```bash +# Interactive +sudo ./bin/deploy-zshtheme-systemwide.sh -- [ ] Test deployment - ```bash - sudo ./bin/deploy-zshtheme-systemwide.sh --current - ``` +# All users with oh-my-zsh +sudo ./bin/deploy-zshtheme-systemwide.sh --all -## 📝 Final Touches +# Current user + root only +sudo ./bin/deploy-zshtheme-systemwide.sh --current -### Customize Personal Info -- [ ] Edit `espanso/match/personal.yml` with your info -- [ ] Edit `git/.gitconfig` with your name and email -- [ ] Update `README.md` with your GitHub username -- [ ] Update any other personal references +# Check status +sudo ./bin/deploy-zshtheme-systemwide.sh --status +``` -### Optional Enhancements -- [ ] Add GitHub Actions for linting (optional) -- [ ] Add screenshots to README -- [ ] Create a demo GIF of the theme -- [ ] Add more espanso snippets for your workflow -- [ ] Create shell aliases in `.zshrc` +Creates symlinks from each user's oh-my-zsh themes folder to `/usr/local/share/zsh/themes/adlee.zsh-theme`. -### Security Check -- [ ] Ensure no sensitive info in committed files - ```bash - # Search for potential secrets - grep -rE '(password|secret|token|key)' . --exclude-dir=.git - ``` +## Customization Tips -- [ ] Verify `.gitignore` is working - ```bash - git status # Should not show .local files or sensitive data - ``` +### Add Aliases -## 🎉 You're Done! +Edit `~/.dotfiles/zsh/.zshrc`: -Once all items are checked: -- [ ] Commit any final changes - ```bash - git add . - git commit -m "Complete repository setup" - git push - ``` +```bash +alias projects='cd ~/projects' +alias k='kubectl' +``` -- [ ] Test on a second machine (if available) -- [ ] Star your own repo (you deserve it! 😄) -- [ ] Share with others who might find it useful +### Machine-Specific Config -## 📚 Next Steps +Create `~/.zshrc.local` (not tracked by git): -- Read through `docs/SETUP_GUIDE.md` for detailed usage -- Explore `docs/ESPANSO.md` for all available snippets -- Customize the theme colors in `zsh/themes/adlee.zsh-theme` -- Add more aliases to `.zshrc` -- Consider contributing to the espanso community hub +```bash +# Work machine specific +export WORK_API_KEY="xxx" +alias vpn='sudo openconnect ...' +``` ---- +### Theme Colors -**Need help?** Open an issue in your repository or check the documentation files. +Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme` and look for: + +```zsh +typeset -g COLOR_GREEN='%{$FG[118]%}' +typeset -g COLOR_BLUE='%{$FG[069]%}' +``` + +## Troubleshooting + +### Theme Not Loading + +```bash +grep ZSH_THEME ~/.zshrc # Should show: ZSH_THEME="adlee" +source ~/.zshrc +``` + +### Espanso Not Expanding + +```bash +espanso status # Should show "running" +espanso restart +espanso log # Check for errors +``` + +### Broken Symlinks + +```bash +# Find broken symlinks in home +find ~ -maxdepth 1 -type l -xtype l + +# Re-run installer +cd ~/.dotfiles && ./install.sh +``` + +### Permission Errors + +```bash +chmod +x ~/.dotfiles/install.sh +chmod +x ~/.dotfiles/bin/* +``` + +## Security Notes + +- `.gitignore` excludes `.env`, `secrets/`, and `*.local` files +- Review `git/.gitconfig` before pushing (contains email) +- Personal espanso snippets may contain sensitive info + +## Uninstalling + +```bash +# Remove symlinks +rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf +rm ~/.oh-my-zsh/themes/adlee.zsh-theme +rm -rf ~/.config/espanso + +# Restore backups +cp ~/.dotfiles_backup_*/.zshrc ~/ + +# Remove dotfiles +rm -rf ~/.dotfiles +``` diff --git a/docs/SNAPPER.md b/docs/SNAPPER.md new file mode 100644 index 0000000..2ff15ff --- /dev/null +++ b/docs/SNAPPER.md @@ -0,0 +1,137 @@ +# Snapper Snapshot Management + +Zsh functions for managing btrfs snapshots with limine-snapper-sync integration on CachyOS/Arch. + +## Requirements + +- Btrfs filesystem with snapper configured +- `limine-snapper-sync` package (AUR) +- Snapper config named "root" + +## Quick Reference + +| Command | Description | +|---------|-------------| +| `snap-create "desc"` | Create snapshot + validate limine entry | +| `snap-list [n]` | Show last n snapshots (default: 10) | +| `snap-show ` | Details for specific snapshot | +| `snap-delete ` | Delete snapshot + update limine | +| `snap-check-limine` | Verify boot menu sync status | +| `snap-sync` | Manually trigger limine sync | +| `snap-info` | Detailed breakdown by type | +| `snap-validate-service` | Check service health | + +### Aliases + +```bash +snap → snap-create +snapls → snap-list +snaprm → snap-delete +snapshow → snap-show +snapcheck → snap-check-limine +snapsync → snap-sync +snapinfo → snap-info +``` + +## Usage Examples + +### Create Before Updates + +```bash +snap-create "Before system update" +# or just: +snap "Before system update" +``` + +Output shows: +- Snapshot number created +- Limine sync trigger +- Validation that entry was added to boot menu + +### Check Boot Menu Sync + +```bash +snap-check-limine +``` + +Shows: +- All snapshots in limine.conf +- Comparison with snapper list +- Missing entries (if any) + +### Pre/Post System Changes + +```bash +# Before risky change +snap "Before kernel update" + +# Make changes... +sudo pacman -Syu + +# If something breaks, boot into the snapshot from limine menu +``` + +## How It Works + +1. **snap-create** calls `snapper -c root create` +2. Triggers `limine-snapper-sync.service` +3. Validates that `/boot/limine.conf` was updated +4. Shows the new boot entry + +The limine bootloader can then boot any snapshot directly. + +## Snapshot Types + +| Type | Created By | +|------|------------| +| `single` | Manual (your `snap-create` calls) | +| `pre` | Auto before package operations | +| `post` | Auto after package operations | + +View with `snap-info`. + +## Troubleshooting + +### Snapshot Created but Not in Boot Menu + +```bash +# Check service status +snap-validate-service + +# Manual sync +snap-sync + +# Verify +snap-check-limine +``` + +### Service Not Running + +```bash +sudo systemctl enable limine-snapper-sync.service +sudo systemctl start limine-snapper-sync.service +``` + +### Boot Menu Has Stale Entries + +```bash +# Delete old snapshot +snap-delete 42 + +# This auto-triggers sync to remove from limine.conf +``` + +## Configuration + +Functions are in `~/.dotfiles/zsh/functions/snapper.zsh` and sourced by `.zshrc`. + +Key settings: +- Snapper config: `root` +- Limine config: `/boot/limine.conf` +- Sync service: `limine-snapper-sync.service` + +## Limitations + +- Only works with limine bootloader +- Requires snapper config named "root" +- limine-snapper-sync typically limits boot entries to recent snapshots (this is intentional to prevent menu clutter)