Now with more & cleaner docs (probably).
This commit is contained in:
Aaron D. Lee
488
docs/ESPANSO.md
488
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/
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
137
docs/SNAPPER.md
Normal file
137
docs/SNAPPER.md
Normal 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)
|
||||
Reference in New Issue
Block a user