alee/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Now with more & cleaner docs (probably).

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-14 15:27:09 -05:00
parent a2acf69a8a
commit 11e1e8d06e
4 changed files with 491 additions and 943 deletions
Download Patch File Download Diff File Expand all files Collapse all files

401
README.md
View File

@@ -1,374 +1,131 @@
# ADLee's Dotfiles # 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) [![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/) [![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 | Component | Description |
- **adlee.zsh-theme** - A feature-rich, performant zsh theme |-----------|-------------|
- Git branch/status integration with visual indicators | **Zsh Theme** | Git status, command timer, smart path truncation |
- Command execution timer (shows time for commands > 10s) | **Espanso** | 100+ text snippets (`..date`, `..gst`, `..dps`) |
- Smart path truncation for long directories | **CLI Tools** | fzf, bat, eza integrations |
- User/root detection (blue prompt for users, red for root) | **Snapper** | Btrfs snapshot helpers for CachyOS/Arch |
- Clean, minimal design that's easy to read
### Espanso Text Expansion ## Quick Start
- **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
### Modern CLI Tools ```bash
- **fzf** - Fuzzy finder for files and history # One-liner
- **bat** - Syntax-highlighted file viewer curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
- **eza** - Modern ls replacement with icons
- **espanso** - Universal text expander
### Easy Deployment # Or clone first
- **One-command installation** on new systems git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
- **Automated backups** of existing configs cd ~/.dotfiles && ./install.sh
- **System-wide theme deployment** for all users ```
- **Modular architecture** for easy customization
## Repository Structure The installer backs up existing configs, installs oh-my-zsh, and creates symlinks.
## Repository Layout
``` ```
dotfiles/ dotfiles/
├── install.sh # Main installation script ├── install.sh # Main installer
├── README.md # This file
├── LICENSE # MIT License
├── .gitignore # Git ignore rules
│
├── zsh/ ├── zsh/
│ ├── .zshrc # Main zsh configuration │ ├── .zshrc # Shell config
│ └── themes/ │ ├── themes/adlee.zsh-theme
│ └── adlee.zsh-theme # Custom zsh theme │ └── functions/snapper.zsh
│
├── espanso/ ├── espanso/
│ ├── config/ │ ├── config/default.yml
│ │ └── default.yml # Espanso settings │ └── match/base.yml # 100+ snippets
│ └── match/ ├── git/.gitconfig
│ ├── base.yml # Base snippets (100+ triggers) ├── vim/.vimrc
│ └── personal.yml # Personal info snippets ├── tmux/.tmux.conf
│ ├── bin/ # Helper scripts
├── git/ └── docs/ # Extended docs
│ ├── .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
``` ```
## 🚀 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 ```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 ```bash
# Clone the repository sudo ./bin/deploy-zshtheme-systemwide.sh --all # All users
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles sudo ./bin/deploy-zshtheme-systemwide.sh --status # Check status
cd ~/.dotfiles
# Run the installer
./install.sh
``` ```
### 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 ## Updating
### Update Dotfiles from GitHub
```bash ```bash
cd ~/.dotfiles cd ~/.dotfiles
git pull origin main 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 ./install.sh
``` ```
### Sync Changes Between Systems ## Snapper Integration (CachyOS/Arch)
For btrfs systems with limine-snapper-sync:
```bash ```bash
# On system A (make changes) snap-create "Before update" # Create + validate limine entry
cd ~/.dotfiles snap-list # Recent snapshots
git add . snap-check-limine # Verify boot menu sync
git commit -m "Update aliases"
git push
# On system B (pull changes)
cd ~/.dotfiles
git pull
source ~/.zshrc
``` ```
## Troubleshooting ## Troubleshooting
### Theme Not Loading | Issue | Fix |
|-------|-----|
Ensure `ZSH_THEME="adlee"` in `~/.zshrc`: | Theme not loading | Check `ZSH_THEME="adlee"` in ~/.zshrc, then `source ~/.zshrc` |
```bash | Espanso not working | `espanso status`, then `espanso restart` |
grep ZSH_THEME ~/.zshrc | Broken symlinks | `cd ~/.dotfiles && ./install.sh` |
```
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
## License ## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. MIT – See [LICENSE](LICENSE)
## 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/)
--- ---
**Author**: Aaron D. Lee **Author**: Aaron D. Lee
**Repository**: https://github.com/adlee-was-taken/dotfiles **Repo**: 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

488
docs/ESPANSO.md
View File

@@ -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 ## Controls
## 🚀 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
| Action | Shortcut | | Action | Shortcut |
|--------|----------| |--------|----------|
| Toggle espanso on/off | `ALT+SHIFT+E` | | Toggle on/off | `ALT+SHIFT+E` |
| Open search menu | `ALT+SPACE` | | Search snippets | `ALT+SPACE` |
| Restart espanso | `espanso restart` | | Restart | `espanso restart` |
| Check status | `espanso status` | | 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 | ### Git
|---------|--------|---------|
| `..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
| Trigger | Output | | 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` | | `..glog` | `git log --oneline --graph --decorate --all` |
| `..gpush` | `git push origin ` | | `..gpush` | `git push origin ` |
| `..gpull` | `git pull origin ` | | `..gpull` | `git pull origin ` |
| `..gbranch` | `git branch -a` |
| `..gdiff` | `git diff` |
| `..gadd` | `git add .` | | `..gadd` | `git add .` |
| `..branch` | Current git branch name | | `..branch` | Current branch name (dynamic) |
### Docker Shortcuts ### Docker
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
@@ -111,106 +52,34 @@ All triggers use the `..` prefix for consistency and to avoid accidental expansi
| `..dcdown` | `docker-compose down` | | `..dcdown` | `docker-compose down` |
| `..dlog` | `docker logs -f ` | | `..dlog` | `docker logs -f ` |
| `..dexec` | `docker exec -it ` | | `..dexec` | `docker exec -it ` |
| `..dim` | `docker images` |
| `..dprune` | `docker system prune -af` | | `..dprune` | `docker system prune -af` |
### System Information ### System Info
| Trigger | Output | Description | | Trigger | Output |
|---------|--------|-------------| |---------|--------|
| `..ip` | Your public IP | Via ifconfig.me | | `..ip` | Public IP (via curl) |
| `..locip` | Your local IP | From hostname -i | | `..locip` | Local IP |
### Code Templates ### Code Templates
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `..bash` | Bash script template with shebang and error handling | | `..bash` | Bash script with shebang + `set -euo pipefail` |
| `..python` | Python script template with main function | | `..python` | Python script with main() |
| `..she!` | `#!/usr/bin/env bash` (shebang only) | | `..she!` | `#!/usr/bin/env bash` |
**Bash Template:** ### Markdown
```bash
#!/usr/bin/env bash
set -euo pipefail
```
**Python Template:**
```python
#!/usr/bin/env python3
def main():
pass
if __name__ == "__main__":
main()
```
### Markdown Helpers
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `..mdcode` | Markdown code block | | `..mdcode` | Code block |
| `..mdbash` | Bash code block | | `..mdbash` | Bash code block |
| `..mdpy` | Python code block | | `..mdpy` | Python code block |
| `..mdjs` | JavaScript code block | | `..mdtable` | Table template |
| `..mdtable` | Markdown table template | | `..mdlink` | Link (prompts for text/url) |
| `..mdlink` | Markdown link (interactive) |
| `..mdimg` | Markdown image (interactive) |
**Table Template:** ### Comments
```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
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
@@ -218,68 +87,75 @@ if __name__ == "__main__":
| `..fixme` | `// FIXME: ` | | `..fixme` | `// FIXME: ` |
| `..note` | `// NOTE: ` | | `..note` | `// NOTE: ` |
| `..hack` | `// HACK: ` | | `..hack` | `// HACK: ` |
| `..debug` | `// DEBUG: ` |
### Common Commands ### Quick Commands
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `..ll` | `ls -lah` | | `..ll` | `ls -lah` |
| `..la` | `ls -A` |
| `..grep` | `grep -rni "" .` | | `..grep` | `grep -rni "" .` |
| `..find` | `find . -name ""` | | `..find` | `find . -name ""` |
| `..port` | `lsof -i :` | | `..port` | `lsof -i :` |
| `..kill` | `kill -9 ` |
| `..proc` | `ps aux | grep ` | | `..proc` | `ps aux | grep ` |
| `..disk` | `df -h` | | `..disk` | `df -h` |
| `..mem` | `free -h` | | `..mem` | `free -h` |
### Lorem Ipsum ### Emoticons
| Trigger | Output | | Trigger | Output |
|---------|--------| |---------|--------|
| `..lorem` | Single paragraph | | `..shrug` | ¯\\\_(ツ)\_/¯ |
| `..loremlong` | Extended lorem ipsum (4 sentences) | | `..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 ### Auto-Corrections
These work automatically without the `..` prefix: These work without `..` prefix:
| Typo | Correction | | Typo | Correction |
|------|------------| |------|------------|
| `teh` | the | | teh | the |
| `recieve` | receive | | recieve | receive |
| `seperator` | separator | | definately | definitely |
| `definately` | definitely | | seperator | separator |
| `occured` | occurred | | occured | occurred |
| `lenght` | length | | lenght | length |
| `wierd` | weird | | wierd | weird |
| `thier` | their | | thier | their |
## Creating Custom Snippets ## Adding Custom Snippets
Edit your snippet files: Edit `~/.config/espanso/match/base.yml`:
```bash
# Base snippets (general use)
vim ~/.config/espanso/match/base.yml
# Personal snippets (your info)
vim ~/.config/espanso/match/personal.yml
```
### Simple Text Replacement
```yaml ```yaml
matches: matches:
# Simple replacement
- trigger: "..hw" - trigger: "..hw"
replace: "Hello, World!" replace: "Hello, World!"
```
### With Date Variables # With shell command
- trigger: "..uptime"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: 'uptime -p'
```yaml # With date
matches:
- trigger: "..today" - trigger: "..today"
replace: "Today is {{mydate}}" replace: "Today is {{mydate}}"
vars: vars:
@@ -289,204 +165,34 @@ matches:
format: "%B %d, %Y" 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'
``` ```
~/.config/espanso/
### Multi-line Templates ├── config/default.yml # Settings
└── match/
```yaml ├── base.yml # Main snippets
matches: └── personal.yml # Your info
- 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"
``` ```
## 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 ## 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: ## Installing Packages
```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
```bash ```bash
# List all matches espanso install emoji # :smile: → 😊
espanso match list | grep "..date" espanso install greek-letters # :alpha: → α
espanso install math # :sum: → ∑
# Check if trigger is recognized espanso package list # Show installed
espanso match list | grep "trigger"
``` ```
## Pro Tips Browse more: https://hub.espanso.org/
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!

406
docs/SETUP_GUIDE.md
View File

@@ -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 - Git
- [ ] `README.md` - Main documentation (use the artifact provided) - Curl
- [ ] `LICENSE` - MIT License file - Zsh (will be installed if missing)
- [ ] `.gitignore` - Git ignore rules
- [ ] `install.sh` - Main installation script
### Zsh Configuration ## Fresh Install
- [ ] `zsh/.zshrc` - Main zsh config
- [ ] `zsh/themes/adlee.zsh-theme` - Custom theme
- [ ] `zsh/.zshrc.local.example` - Template for local settings (optional)
### Espanso Configuration ### Option 1: One-liner
- [ ] `espanso/config/default.yml` - Espanso settings
- [ ] `espanso/match/base.yml` - Base snippets
- [ ] `espanso/match/personal.yml` - Personal snippets
### Git Configuration ```bash
- [ ] `git/.gitconfig` - Git settings curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
- [ ] `git/.gitignore_global` - Global gitignore (optional) ```
### Other Configs ### Option 2: Clone First
- [ ] `vim/.vimrc` - Vim config (if you use vim)
- [ ] `tmux/.tmux.conf` - Tmux config (if you use tmux)
### Utility Scripts ```bash
- [ ] `bin/update-dotfiles` - Update script git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
- [ ] `bin/setup-espanso.sh` - Espanso wizard cd ~/.dotfiles
- [ ] `bin/deploy-zshtheme-systemwide.sh` - System-wide deployment ./install.sh
```
### Documentation ### What the Installer Does
- [ ] `docs/SETUP_GUIDE.md` - Detailed setup guide
- [ ] `docs/ESPANSO.md` - Espanso reference
- [ ] `CHECKLIST.md` - This file
## 🔧 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 ```bash
cd ~/.dotfiles cd ~/.dotfiles
mkdir -p zsh/themes git pull origin main
mkdir -p espanso/config espanso/match ./install.sh
mkdir -p git source ~/.zshrc
mkdir -p vim
mkdir -p tmux
mkdir -p bin
mkdir -p docs
``` ```
### 2. Create/Copy Configuration Files Or use the helper:
- [ ] 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
```bash ```bash
cat > .gitignore << 'EOF' update-dotfiles.sh
# 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
``` ```
### 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 ```bash
cd ~/.dotfiles cd ~/.dotfiles
git init
git add . 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 ## Multi-Machine Sync
```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`
```bash ```bash
# Quick find all instances # Machine A: push changes
grep -r "adlee-was-taken" . 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 | Path | Purpose |
- [ ] Test install script on local machine |------|---------|
```bash | `zsh/.zshrc` | Main shell config |
# Dry run first | `zsh/themes/adlee.zsh-theme` | Prompt theme |
bash -n install.sh # Check for syntax errors | `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 |
# Then test (will backup existing configs) ## Symlinks Created
./install.sh
```
- [ ] Verify symlinks were created correctly | Source | Target |
```bash |--------|--------|
ls -la ~ | grep "^l" # Show all symlinks in home | `~/.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 zsh theme ## System-Wide Theme
```bash
source ~/.zshrc
# Check if prompt looks correct
```
- [ ] Test espanso Deploy to all users on a system:
```bash
espanso status
# Try typing: ..date
```
### Test GitHub Setup ```bash
- [ ] Clone on a test directory # Interactive
```bash sudo ./bin/deploy-zshtheme-systemwide.sh
cd /tmp
git clone https://github.com/adlee-was-taken/dotfiles.git test-dotfiles
cd test-dotfiles
./install.sh
```
### Test System-wide Deployment # All users with oh-my-zsh
- [ ] Check current status sudo ./bin/deploy-zshtheme-systemwide.sh --all
```bash
sudo ./bin/deploy-zshtheme-systemwide.sh --status
```
- [ ] Test deployment # Current user + root only
```bash sudo ./bin/deploy-zshtheme-systemwide.sh --current
sudo ./bin/deploy-zshtheme-systemwide.sh --current
```
## 📝 Final Touches # Check status
sudo ./bin/deploy-zshtheme-systemwide.sh --status
```
### Customize Personal Info Creates symlinks from each user's oh-my-zsh themes folder to `/usr/local/share/zsh/themes/adlee.zsh-theme`.
- [ ] 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
### Optional Enhancements ## Customization Tips
- [ ] 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`
### Security Check ### Add Aliases
- [ ] Ensure no sensitive info in committed files
```bash
# Search for potential secrets
grep -rE '(password|secret|token|key)' . --exclude-dir=.git
```
- [ ] Verify `.gitignore` is working Edit `~/.dotfiles/zsh/.zshrc`:
```bash
git status # Should not show .local files or sensitive data
```
## 🎉 You're Done! ```bash
alias projects='cd ~/projects'
alias k='kubectl'
```
Once all items are checked: ### Machine-Specific Config
- [ ] Commit any final changes
```bash
git add .
git commit -m "Complete repository setup"
git push
```
- [ ] Test on a second machine (if available) Create `~/.zshrc.local` (not tracked by git):
- [ ] Star your own repo (you deserve it! 😄)
- [ ] Share with others who might find it useful
## 📚 Next Steps ```bash
# Work machine specific
export WORK_API_KEY="xxx"
alias vpn='sudo openconnect ...'
```
- Read through `docs/SETUP_GUIDE.md` for detailed usage ### Theme Colors
- 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
--- Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme` and look for:
**Need help?** Open an issue in your repository or check the documentation files. ```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
```

137
docs/SNAPPER.md Normal file
View File

@@ -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 <num>` | Details for specific snapshot |
| `snap-delete <num>` | 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)