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

Cleanup tasks.

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-15 16:17:06 -05:00
parent 048c9ed8bc
commit 5f3aad3b99
8 changed files with 1341 additions and 773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
docs/ESPANSO.md
View File

@@ -10,26 +10,32 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
| Search snippets | `ALT+SPACE` |
| Restart | `espanso restart` |
| Status | `espanso status` |
| View logs | `espanso log` |
## Snippet Reference
---
## Snippet Categories
### Date & Time
| Trigger | Output |
|---------|--------|
| `..date` | 2025-12-14 |
| `..sds` | 20251214 (filename-safe) |
| `..time` | 14:30:45 |
| `..ts` | 2025-12-14T14:30:45.123Z |
| `..utc` | 2025-12-14 14:30:45.123 UTC |
| `..dt` | 2025-12-14 14:30:45 EST |
| `..epoch` | 1702573845 |
| `..epochms` | 1702573845123 |
| `..month` | December |
| `..day` | Saturday |
| `..week` | Week 50 |
| Trigger | Output | Example |
|---------|--------|---------|
| `..date` | Current date | 2025-12-15 |
| `..sds` | Filename-safe date | 20251215 |
| `..time` | Current time | 14:30:45 |
| `..ts` | ISO timestamp | 2025-12-15T14:30:45.123Z |
| `..utc` | UTC datetime | 2025-12-15 14:30:45.123 UTC |
| `..dt` | Local datetime | 2025-12-15 14:30:45 EST |
| `..udt` | UTC datetime | 2025-12-15 14:30:45 UTC |
| `..ztime` | Time with timezone | 14:30:45.123 EST |
| `..epoch` | Unix timestamp | 1702573845 |
| `..epochms` | Unix ms timestamp | 1702573845123 |
| `..month` | Month name | December |
| `..day` | Day name | Saturday |
| `..week` | Week number | Week 50 |
| `..year` | Year | 2025 |
### Git
### Git Commands
| Trigger | Output |
|---------|--------|
@@ -39,10 +45,12 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
| `..glog` | `git log --oneline --graph --decorate --all` |
| `..gpush` | `git push origin ` |
| `..gpull` | `git pull origin ` |
| `..gbranch` | `git branch -a` |
| `..gdiff` | `git diff` |
| `..gadd` | `git add .` |
| `..branch` | Current branch name (dynamic) |
### Docker
### Docker Commands
| Trigger | Output |
|---------|--------|
@@ -52,6 +60,7 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
| `..dcdown` | `docker-compose down` |
| `..dlog` | `docker logs -f ` |
| `..dexec` | `docker exec -it ` |
| `..dim` | `docker images` |
| `..dprune` | `docker system prune -af` |
### System Info
@@ -73,11 +82,13 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
| Trigger | Output |
|---------|--------|
| `..mdcode` | Code block |
| `..mdcode` | Code block (triple backticks) |
| `..mdbash` | Bash code block |
| `..mdpy` | Python code block |
| `..mdjs` | JavaScript code block |
| `..mdtable` | Table template |
| `..mdlink` | Link (prompts for text/url) |
| `..mdimg` | Image (prompts for alt/url) |
### Comments
@@ -87,20 +98,41 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
| `..fixme` | `// FIXME: ` |
| `..note` | `// NOTE: ` |
| `..hack` | `// HACK: ` |
| `..debug` | `// DEBUG: ` |
### Quick Commands
| Trigger | Output |
|---------|--------|
| `..ll` | `ls -lah` |
| `..la` | `ls -A` |
| `..grep` | `grep -rni "" .` |
| `..find` | `find . -name ""` |
| `..port` | `lsof -i :` |
| `..kill` | `kill -9 ` |
| `..proc` | `ps aux | grep ` |
| `..disk` | `df -h` |
| `..mem` | `free -h` |
### Emoticons
### Navigation
| Trigger | Output |
|---------|--------|
| `..~` | `cd ~` |
| `..tmp` | `cd /tmp/` |
| `..logs` | `cd /var/log/` |
### URLs
| Trigger | Output |
|---------|--------|
| `..gh` | `https://github.com` |
| `..gl` | `https://gitlab.com` |
| `..gist` | `https://gist.github.com` |
| `..so` | `https://stackoverflow.com` |
| `..reddit` | `https://reddit.com` |
### Emoticons & Symbols
| Trigger | Output |
|---------|--------|
@@ -111,19 +143,38 @@ Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
| `..check` | ✓ |
| `..cross` | ✗ |
| `..arrow` | → |
| `..larrow` | ← |
### Quick Responses
| Trigger | Output |
|---------|--------|
| `..brb` | Be right back |
| `..omw` | On my way |
| `..tyvm` | Thank you very much |
| `..lgtm` | Looks good to me |
| `..wfm` | Works for me |
| `..tyvm` | Thank you very much |
| `..ack` | Acknowledged |
| `..asap` | As soon as possible |
### Auto-Corrections
### Lorem Ipsum
These work without `..` prefix:
| Trigger | Output |
|---------|--------|
| `..lorem` | One paragraph |
| `..loremlong` | Four paragraphs |
### Clipboard
| Trigger | Output |
|---------|--------|
| `..qp` | Paste from primary selection (X11/Wayland) |
---
## Auto-Corrections
These work without the `..` prefix:
| Typo | Correction |
|------|------------|
@@ -136,17 +187,54 @@ These work without `..` prefix:
| wierd | weird |
| thier | their |
## Adding Custom Snippets
---
Edit `~/.config/espanso/match/base.yml`:
## Personal Snippets
Edit `~/.dotfiles/espanso/match/personal.yml`:
```yaml
matches:
- trigger: "..myemail"
replace: "your.email@example.com"
- trigger: "..myname"
replace: "Your Full Name"
- trigger: "..myphone"
replace: "+1 (555) 123-4567"
- trigger: "..sig"
replace: |
Best regards,
Your Full Name
your.email@example.com
- trigger: "..myaddr"
replace: |
123 Main Street
City, ST 12345
```
Run `setup-espanso.sh` to configure interactively.
---
## Adding Custom Snippets
Edit `~/.dotfiles/espanso/match/base.yml`:
### Simple Replacement
```yaml
matches:
# Simple replacement
- trigger: "..hw"
replace: "Hello, World!"
```
# With shell command
### With Shell Command
```yaml
- trigger: "..uptime"
replace: "{{output}}"
vars:
@@ -154,8 +242,11 @@ matches:
type: shell
params:
cmd: 'uptime -p'
```
# With date
### With Date Formatting
```yaml
- trigger: "..today"
replace: "Today is {{mydate}}"
vars:
@@ -165,34 +256,129 @@ matches:
format: "%B %d, %Y"
```
### With Form Input
```yaml
- trigger: "..mailto"
replace: "<a href=\"mailto:{{email}}\">{{name}}</a>"
vars:
- name: email
type: form
params:
layout: "Email: {{email}}"
- name: name
type: form
params:
layout: "Display name: {{name}}"
```
### With Clipboard
```yaml
- trigger: "..cliplink"
replace: "[{{clipboard}}]({{clipboard}})"
vars:
- name: clipboard
type: clipboard
```
After editing: `espanso restart`
## Config Locations
---
## Config Files
```
~/.config/espanso/
├── config/default.yml # Settings
~/.config/espanso/ (symlinked to ~/.dotfiles/espanso/)
├── config/
│ └── default.yml # Global settings
└── match/
├── base.yml # Main snippets
└── personal.yml # Your info
├── base.yml # Main snippets (100+)
├── personal.yml # Your personal info
└── packages/ # Installed packages
```
## Troubleshooting
---
## Useful Commands
```bash
espanso status # Check if running
espanso restart # Restart service
espanso log # View logs
espanso match list # List all triggers
espanso status # Check if running
espanso start # Start service
espanso restart # Restart service
espanso stop # Stop service
espanso log # View logs
espanso edit # Open config in editor
espanso match list # List all triggers
espanso path # Show config paths
```
---
## Installing Packages
Browse packages: https://hub.espanso.org/
```bash
espanso install emoji # :smile: → 😊
espanso install greek-letters # :alpha: → α
espanso install math # :sum: → ∑
espanso install lorem # More lorem ipsum options
espanso package list # Show installed
espanso package uninstall <n> # Remove package
```
Browse more: https://hub.espanso.org/
---
## Troubleshooting
### Espanso Not Starting
```bash
espanso service register # Register as service
espanso start
```
### Snippets Not Expanding
```bash
espanso restart
espanso log # Check for errors
```
### Wrong Keyboard Layout
Edit `~/.config/espanso/config/default.yml`:
```yaml
backend: Clipboard # Try different backend
```
### Check Syntax
```bash
espanso --help # Will error if YAML is invalid
espanso match list # Lists triggers if syntax is OK
```
### Wayland Issues
If using Wayland, you may need the Wayland-specific build:
```bash
# Check your session
echo $XDG_SESSION_TYPE
# Install Wayland version if needed
# (varies by distro)
```
---
## Tips
1. **Test snippets** - Type them in any text field
2. **Use search** - `ALT+SPACE` to search all triggers
3. **Escape triggers** - Type slowly or add a space to prevent expansion
4. **Backup config** - It's in your dotfiles, so it syncs automatically
5. **Restart after changes** - `espanso restart`

678
docs/SETUP_GUIDE.md
View File

@@ -1,22 +1,65 @@
# Setup Guide
Step-by-step instructions for setting up and maintaining your dotfiles.
Complete guide for installing, configuring, and maintaining your dotfiles.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation Methods](#installation-methods)
- [Post-Install Setup](#post-install-setup)
- [Configuration](#configuration)
- [Features Guide](#features-guide)
- [Customization](#customization)
- [Multi-Machine Setup](#multi-machine-setup)
- [Troubleshooting](#troubleshooting)
- [Uninstalling](#uninstalling)
---
## Prerequisites
**Required:**
- Git
- Curl
- Zsh (will be installed if missing)
- Zsh (installed automatically if missing)
## Fresh Install
**Optional (for full features):**
- `fzf` - For command palette and fuzzy finding
- `age` or `gpg` - For secrets vault
- `gum` - For beautiful setup wizard
### Option 1: One-liner
---
## Installation Methods
### Method 1: Interactive Wizard (Recommended)
The wizard provides a beautiful TUI to customize your installation:
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard
```
The wizard will guide you through:
1. Identity setup (name, email, GitHub)
2. Git configuration
3. Feature selection
4. Theme choice
5. Advanced options
### Method 2: One-liner
Quick install with defaults:
```bash
curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
```
### Option 2: Clone First
### Method 3: Standard Install
Clone and run with prompts:
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
@@ -24,119 +67,443 @@ cd ~/.dotfiles
./install.sh
```
### What the Installer Does
1. Detects OS (Ubuntu, Arch, Fedora, macOS)
2. Installs dependencies (git, curl, zsh)
3. Backs up existing configs to `~/.dotfiles_backup_YYYYMMDD_HHMMSS/`
4. Installs oh-my-zsh
5. Installs zsh plugins (autosuggestions, syntax-highlighting)
6. Configures git (prompts for name/email if not in config)
7. Creates symlinks
8. Optionally installs espanso, fzf, bat, eza
9. Sets zsh as default shell
### Install Options
```bash
./install.sh # Full interactive install
./install.sh --skip-deps # Skip dependency check (for re-runs)
./install.sh --deps-only # Only install dependencies
./install.sh --uninstall # Remove symlinks, offer to restore backups
./install.sh --uninstall --purge # Also remove ~/.dotfiles
./install.sh --help # Show all options
./install.sh # Interactive install
./install.sh --wizard # TUI wizard
./install.sh --skip-deps # Skip dependency installation
./install.sh --deps-only # Only install dependencies
./install.sh --uninstall # Remove symlinks
./install.sh --uninstall --purge # Remove everything
./install.sh --help # Show all options
```
## Post-Install
---
### Verify Installation
## Post-Install Setup
### 1. Verify Installation
```bash
dotfiles-doctor.sh # Check health of installation
dotfiles-doctor.sh --fix # Attempt to fix issues
dotfiles-doctor.sh
```
### Check Version
This checks:
- All symlinks are valid
- Zsh plugins installed
- Git configured
- Theme loaded
- Optional tools present
Fix issues automatically:
```bash
dotfiles-version.sh # Show local vs remote version
dotfiles-version.sh --check # Exit 1 if updates available
dotfiles-doctor.sh --fix
```
### Personalize Espanso
### 2. Restart Shell
```bash
./bin/setup-espanso.sh
exec zsh
# or just close and reopen your terminal
```
Updates `personal.yml` with your name, email, etc.
### Test It
### 3. Personalize Espanso (Optional)
```bash
source ~/.zshrc # Reload shell
echo "..date" | espanso # Test espanso (or just type ..date anywhere)
setup-espanso.sh
```
### Install Zsh Plugins (if missing)
This sets up your personal info for text expansion (email, name, signatures).
### 4. Set Up Secrets Vault (Optional)
```bash
git clone https://github.com/zsh-users/zsh-autosuggestions \
${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting \
${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
vault init
vault set GITHUB_TOKEN "your-token-here"
vault list
```
## Updating
### 5. Configure Directory Bookmarks (Optional)
```bash
cd ~/.dotfiles
git pull origin main
./install.sh
bookmark projects ~/projects
bookmark work ~/work
bookmark list
```
---
## Configuration
### Main Configuration File
All settings are in `~/.dotfiles/dotfiles.conf`:
```bash
# ============================================================================
# Identity
# ============================================================================
USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com"
USER_GITHUB="yourusername"
# ============================================================================
# Git Configuration
# ============================================================================
GIT_USER_NAME="" # Falls back to USER_FULLNAME
GIT_USER_EMAIL="" # Falls back to USER_EMAIL
GIT_DEFAULT_BRANCH="main"
GIT_CREDENTIAL_HELPER="store"
# ============================================================================
# Feature Toggles
# ============================================================================
# Values: "true", "false", or "ask"
INSTALL_DEPS="auto" # Auto-skip if already installed
INSTALL_ZSH_PLUGINS="true" # zsh-autosuggestions, syntax-highlighting
INSTALL_FZF="ask"
INSTALL_BAT="ask"
INSTALL_EZA="ask"
INSTALL_ESPANSO="ask"
SET_ZSH_DEFAULT="ask"
# ============================================================================
# Advanced Features
# ============================================================================
ENABLE_SMART_SUGGESTIONS="true" # Typo correction
ENABLE_COMMAND_PALETTE="true" # Ctrl+Space launcher
ENABLE_SHELL_ANALYTICS="false" # Command stats
ENABLE_VAULT="true" # Encrypted secrets
DOTFILES_AUTO_SYNC_CHECK="true" # Check for updates on shell start
```
### Applying Configuration Changes
After editing `dotfiles.conf`:
```bash
./install.sh --skip-deps
# or just
source ~/.zshrc
```
Or use the helper:
---
## Features Guide
### Command Palette
**Trigger:** `Ctrl+Space` or `Ctrl+P`
The command palette searches:
- ⚡ Aliases
- λ Functions
- ↺ Recent commands
- 📁 Bookmarked directories
- ⚙ Dotfiles scripts
- ★ Quick actions
- ⎇ Git commands (context-aware)
- ◉ Docker commands
**Keybindings in palette:**
| Key | Action |
|-----|--------|
| `Enter` | Execute command |
| `Ctrl+E` | Edit command first |
| `Ctrl+Y` | Copy to clipboard |
| `Ctrl+R` | Refresh entries |
| `Esc` | Cancel |
**Bookmarks:**
```bash
update-dotfiles.sh
bookmark <name> [path] # Save bookmark (default: current dir)
bookmark list # List all bookmarks
bookmark delete <name> # Remove bookmark
jump <name> # Go to bookmark
j # Fuzzy select bookmark
```
## Pushing Changes
### Smart Suggestions
Automatically corrects 100+ common typos:
```bash
gti → git
dokcer → docker
sl → ls
pytohn → python
```
Suggests aliases for frequently typed commands:
```bash
💡 You've typed 'git status' 50 times
You already have an alias: gs
```
**Commands:**
```bash
fuck # Re-run last command with typo fixed
```
### Shell Analytics
```bash
shell-stats.sh # Full dashboard
shell-stats.sh --top 20 # Top 20 commands
shell-stats.sh --suggest # Alias recommendations
shell-stats.sh --heatmap # Activity by hour
shell-stats.sh --dirs # Most visited directories
shell-stats.sh --git # Git command breakdown
shell-stats.sh --docker # Docker command breakdown
shell-stats.sh --export # Export as JSON
```
### Secrets Vault
Encrypted storage using `age` or `gpg`:
```bash
vault set KEY "value" # Store (or prompt for value)
vault get KEY # Retrieve
vault list # Show all keys
vault delete KEY # Remove
vault shell # Print as export statements
vault export backup.enc # Backup encrypted vault
vault import backup.enc # Restore vault
vault status # Show vault info
```
**Auto-loading:** Secrets are automatically loaded into your environment on shell start.
### Dotfiles Sync
```bash
dotfiles-sync.sh # Interactive sync
dotfiles-sync.sh --status # Show sync status
dotfiles-sync.sh --push # Push local changes
dotfiles-sync.sh --pull # Pull remote changes
dotfiles-sync.sh --diff # Show local changes
dotfiles-sync.sh --watch 300 # Auto-sync every 5 minutes
dotfiles-sync.sh --log # Show sync history
```
**Auto-check:** On shell start, you'll be notified of available updates.
---
## Customization
### Adding Aliases
Edit `~/.dotfiles/zsh/.zshrc`:
```bash
# Custom aliases
alias projects='cd ~/projects'
alias k='kubectl'
alias tf='terraform'
```
### Machine-Specific Config
Create `~/.zshrc.local` (not tracked by git):
```bash
# Work machine
export CORP_PROXY="http://proxy:8080"
export WORK_EMAIL="me@company.com"
# Local paths
export PATH="$HOME/work-tools/bin:$PATH"
```
### Custom Espanso Snippets
Edit `~/.dotfiles/espanso/match/personal.yml`:
```yaml
matches:
- trigger: "..myemail"
replace: "your.email@example.com"
- trigger: "..sig"
replace: |
Best regards,
Your Name
```
### Theme Customization
Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme`:
```zsh
# Change colors
typeset -g COLOR_GREEN='%{$FG[118]%}'
typeset -g COLOR_BLUE='%{$FG[069]%}'
# Change timer threshold (seconds)
typeset -g TIMER_THRESHOLD=10
```
---
## Multi-Machine Setup
### Initial Setup on New Machine
```bash
# Clone your dotfiles
git clone https://github.com/YOUR_USER/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```
### Syncing Changes
**On Machine A (make changes):**
```bash
cd ~/.dotfiles
git add .
git commit -m "Update aliases"
git push origin main
# Edit files...
dotfiles-sync.sh --push "Added new aliases"
```
## Multi-Machine Sync
**On Machine B (get changes):**
```bash
# Machine A: push changes
cd ~/.dotfiles && git add . && git commit -m "Update" && git push
# Machine B: pull changes
cd ~/.dotfiles && git pull && source ~/.zshrc
dotfiles-sync.sh --pull
source ~/.zshrc
```
## File Structure
### Automatic Sync
| Path | Purpose |
|------|---------|
| `zsh/.zshrc` | Main shell config |
| `zsh/themes/adlee.zsh-theme` | Prompt theme |
| `zsh/functions/snapper.zsh` | Btrfs snapshot helpers |
| `espanso/match/base.yml` | Text snippets |
| `espanso/match/personal.yml` | Your personal info |
| `git/.gitconfig` | Git settings |
| `vim/.vimrc` | Vim config |
| `tmux/.tmux.conf` | Tmux config |
| `bin/` | Utility scripts |
Enable watch mode (runs in background):
## Symlinks Created
```bash
dotfiles-sync.sh --watch 300 # Check every 5 minutes
```
Or add to crontab:
```bash
*/30 * * * * ~/.dotfiles/bin/dotfiles-sync.sh --auto
```
---
## Troubleshooting
### Run the Doctor First
```bash
dotfiles-doctor.sh --fix
```
### Common Issues
| Issue | Solution |
|-------|----------|
| Theme not loading | Check `ZSH_THEME="adlee"` in .zshrc, run `source ~/.zshrc` |
| Zsh plugins missing | Run `./install.sh` (auto-installs plugins now) |
| Command palette not working | Install fzf: `./install.sh` will prompt |
| Vault errors | Install age: `brew install age` or `pacman -S age` |
| Espanso not expanding | Run `espanso status`, then `espanso restart` |
| Sync conflicts | Run `dotfiles-sync.sh --conflicts` to see conflicts |
| Symlinks broken | Run `./install.sh --skip-deps` to recreate |
### Manual Fixes
**Reinstall zsh plugins:**
```bash
rm -rf ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
rm -rf ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
./install.sh --skip-deps
```
**Reset git config:**
```bash
rm ~/.gitconfig
./install.sh --skip-deps
```
**Fix permissions:**
```bash
chmod +x ~/.dotfiles/install.sh
chmod +x ~/.dotfiles/bin/*
```
### Getting Help
```bash
# Any script
<script> --help
# Examples
./install.sh --help
vault --help
dotfiles-sync.sh --help
shell-stats.sh --help
```
---
## Uninstalling
### Quick Uninstall
```bash
./install.sh --uninstall
```
This will:
1. Remove all symlinks
2. Find and offer to restore backups
3. Keep ~/.dotfiles directory
### Complete Removal
```bash
./install.sh --uninstall --purge
```
This also removes the `~/.dotfiles` directory.
### Manual Uninstall
```bash
# Remove symlinks
rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
rm ~/.oh-my-zsh/themes/adlee.zsh-theme
rm -rf ~/.config/espanso
rm ~/.local/bin/dotfiles-*.sh ~/.local/bin/vault.sh ~/.local/bin/shell-stats.sh
# Restore backups (if any)
ls ~/.dotfiles_backup_*
# Remove dotfiles
rm -rf ~/.dotfiles
# Optional: Remove oh-my-zsh
rm -rf ~/.oh-my-zsh
# Change shell back to bash
chsh -s /bin/bash
```
---
## File Reference
### Symlinks Created
| Source | Target |
|--------|--------|
@@ -146,156 +513,27 @@ cd ~/.dotfiles && git pull && source ~/.zshrc
| `~/.dotfiles/vim/.vimrc` | `~/.vimrc` |
| `~/.dotfiles/tmux/.tmux.conf` | `~/.tmux.conf` |
| `~/.dotfiles/espanso/` | `~/.config/espanso` |
| `~/.dotfiles/bin/*` | `~/.local/bin/*` |
## System-Wide Theme
### Key Files
Deploy to all users on a system:
| File | Purpose |
|------|---------|
| `dotfiles.conf` | Central configuration |
| `zsh/.zshrc` | Main shell config |
| `zsh/themes/adlee.zsh-theme` | Prompt theme |
| `zsh/functions/smart-suggest.zsh` | Typo correction |
| `zsh/functions/command-palette.zsh` | Fuzzy launcher |
| `espanso/match/base.yml` | Text expansion snippets |
| `espanso/match/personal.yml` | Personal snippets |
| `vault/` | Encrypted secrets (gitignored) |
```bash
# Interactive
sudo ./bin/deploy-zshtheme-systemwide.sh
---
# All users with oh-my-zsh
sudo ./bin/deploy-zshtheme-systemwide.sh --all
## Security Notes
# Current user + root only
sudo ./bin/deploy-zshtheme-systemwide.sh --current
# Check status
sudo ./bin/deploy-zshtheme-systemwide.sh --status
```
Creates symlinks from each user's oh-my-zsh themes folder to `/usr/local/share/zsh/themes/adlee.zsh-theme`.
## Configuration
### dotfiles.conf
The main configuration file. Edit to customize your installation:
```bash
# --- Version ---
DOTFILES_VERSION="1.0.0"
# --- User Identity ---
USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com"
USER_GITHUB="yourusername"
# --- Git Configuration ---
GIT_USER_NAME="" # Falls back to USER_FULLNAME
GIT_USER_EMAIL="" # Falls back to USER_EMAIL
GIT_DEFAULT_BRANCH="main"
GIT_CREDENTIAL_HELPER="store"
# --- Feature Toggles ---
INSTALL_DEPS="auto" # "auto", "true", "false", or "ask"
INSTALL_ZSH_PLUGINS="true" # Auto-install zsh plugins
INSTALL_ESPANSO="ask"
INSTALL_FZF="ask"
INSTALL_BAT="ask"
INSTALL_EZA="ask"
SET_ZSH_DEFAULT="ask"
```
### Git Identity
The installer configures git automatically:
1. Uses `GIT_USER_NAME` / `GIT_USER_EMAIL` from config
2. Falls back to `USER_FULLNAME` / `USER_EMAIL`
3. Prompts if both are empty
To reconfigure git later:
```bash
git config --global user.name "New Name"
git config --global user.email "new@email.com"
```
Or edit `dotfiles.conf` and re-run `./install.sh`.
## Customization Tips
### Add Aliases
Edit `~/.dotfiles/zsh/.zshrc`:
```bash
alias projects='cd ~/projects'
alias k='kubectl'
```
### Machine-Specific Config
Create `~/.zshrc.local` (not tracked by git):
```bash
# Work machine specific
export WORK_API_KEY="xxx"
alias vpn='sudo openconnect ...'
```
### Theme Colors
Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme` and look for:
```zsh
typeset -g COLOR_GREEN='%{$FG[118]%}'
typeset -g COLOR_BLUE='%{$FG[069]%}'
```
## Troubleshooting
### Run the Doctor
```bash
dotfiles-doctor.sh # Diagnose issues
dotfiles-doctor.sh --fix # Auto-fix what's possible
```
### Common Issues
| Issue | Fix |
|-------|-----|
| Theme not loading | `dotfiles-doctor.sh --fix` |
| Zsh plugins missing | `./install.sh` (auto-installs) |
| Espanso not expanding | `espanso restart` |
| Git identity not set | Re-run `./install.sh` |
| Broken symlinks | `./install.sh` |
### Manual Fixes
```bash
# Reinstall zsh plugins
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
# Fix permissions
chmod +x ~/.dotfiles/install.sh
chmod +x ~/.dotfiles/bin/*
```
## Uninstalling
### Quick Uninstall
```bash
./install.sh --uninstall # Remove symlinks, offer backup restore
./install.sh --uninstall --purge # Also delete ~/.dotfiles
```
### Manual Uninstall
```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
```
- `.gitignore` excludes sensitive files (`.env`, `secrets/`, `*.local`, `vault/`)
- Vault uses strong encryption (age/gpg)
- Never commit API keys or tokens
- Review `git/.gitconfig` before pushing (contains email)
- Personal espanso snippets may contain sensitive info

236
docs/SNAPPER.md
View File

@@ -7,31 +7,24 @@ Zsh functions for managing btrfs snapshots with limine-snapper-sync integration
- Btrfs filesystem with snapper configured
- `limine-snapper-sync` package (AUR)
- Snapper config named "root"
- Limine bootloader
---
## 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 |
| Command | Alias | Description |
|---------|-------|-------------|
| `snap-create "desc"` | `snap` | Create snapshot + validate limine entry |
| `snap-list [n]` | `snapls` | Show last n snapshots (default: 10) |
| `snap-show <num>` | `snapshow` | Details for specific snapshot |
| `snap-delete <num>` | `snaprm` | Delete snapshot + update limine |
| `snap-check-limine` | `snapcheck` | Verify boot menu sync status |
| `snap-sync` | `snapsync` | Manually trigger limine sync |
| `snap-info` | `snapinfo` | 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
@@ -39,46 +32,100 @@ snapinfo → snap-info
```bash
snap-create "Before system update"
# or just:
# or using alias:
snap "Before system update"
```
Output shows:
- Snapshot number created
- Limine sync trigger
- Validation that entry was added to boot menu
Output:
```
╔════════════════════════════════════════════════════════════╗
║ Snapper Snapshot Creation & Validation ║
╚════════════════════════════════════════════════════════════╝
==> Checking limine.conf state before snapshot
✓ Before: 5 snapshot entries
✓ Before checksum: a1b2c3d4...
==> Creating snapshot: "Before system update"
✓ Snapshot created: #42
==> Triggering limine-snapper-sync service...
✓ Service triggered successfully
==> Validating limine.conf update
✓ limine.conf was updated
✓ Added 1 new snapshot entry
✓ Found snapshot #42 in limine.conf
╔════════════════════════════════════════════════════════════╗
║ Summary ║
╚════════════════════════════════════════════════════════════╝
Snapshot Number: #42
Description: "Before system update"
Status: ✓ VALIDATED
```
### Check Boot Menu Sync
```bash
snap-check-limine
# or:
snapcheck
```
Shows:
- All snapshots in limine.conf
- Comparison with snapper list
- Missing entries (if any)
- Sync status
### Pre/Post System Changes
### List Recent Snapshots
```bash
# Before risky change
snap "Before kernel update"
# Make changes...
sudo pacman -Syu
# If something breaks, boot into the snapshot from limine menu
snap-list # Last 10
snap-list 20 # Last 20
# or:
snapls 20
```
### View Snapshot Details
```bash
snap-show 42
# or:
snapshow 42
```
Shows:
- Snapshot info from snapper
- Corresponding entry in limine.conf
### Delete Snapshot
```bash
snap-delete 42
# or:
snaprm 42
```
Automatically:
- Deletes snapshot from snapper
- Triggers limine-snapper-sync
- Verifies removal from boot menu
---
## How It Works
1. **snap-create** calls `snapper -c root create`
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.
The limine bootloader can then boot any snapshot directly from the boot menu.
---
## Snapshot Types
@@ -88,7 +135,26 @@ The limine bootloader can then boot any snapshot directly.
| `pre` | Auto before package operations |
| `post` | Auto after package operations |
View with `snap-info`.
View breakdown with `snap-info` or `snapinfo`.
---
## Pre/Post System Changes Workflow
```bash
# Before risky change
snap "Before kernel update"
# Make changes
sudo pacman -Syu
# If something breaks:
# 1. Reboot
# 2. Select snapshot from limine boot menu
# 3. System restored to pre-update state
```
---
## Troubleshooting
@@ -100,6 +166,8 @@ snap-validate-service
# Manual sync
snap-sync
# or:
snapsync
# Verify
snap-check-limine
@@ -121,17 +189,95 @@ snap-delete 42
# This auto-triggers sync to remove from limine.conf
```
### Check Service Logs
```bash
sudo journalctl -u limine-snapper-sync.service -n 50
```
### Validate Everything
```bash
snap-validate-service
```
This checks:
- Service unit exists
- Service is enabled
- Snapper config exists
- limine.conf exists
- Current sync status
---
## Configuration
Functions are in `~/.dotfiles/zsh/functions/snapper.zsh` and sourced by `.zshrc`.
Functions are sourced from `~/.dotfiles/zsh/functions/snapper.zsh`.
Key settings:
- Snapper config: `root`
- Limine config: `/boot/limine.conf`
- Sync service: `limine-snapper-sync.service`
Settings in `~/.dotfiles/dotfiles.conf`:
```bash
SNAPPER_CONFIG="root"
LIMINE_CONF="/boot/limine.conf"
```
---
## 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)
- Only works with **limine bootloader**
- Requires snapper config named **"root"**
- `limine-snapper-sync` typically limits boot entries to recent snapshots (intentional to prevent menu clutter)
---
## Installing limine-snapper-sync
On Arch/CachyOS:
```bash
# If using paru
paru -S limine-snapper-sync
# If using yay
yay -S limine-snapper-sync
# Enable service
sudo systemctl enable limine-snapper-sync.service
```
---
## Manual Snapper Commands
If you need to use snapper directly:
```bash
# List all snapshots
sudo snapper -c root list
# Create snapshot
sudo snapper -c root create --description "My snapshot"
# Delete snapshot
sudo snapper -c root delete 42
# Compare snapshots
sudo snapper -c root diff 41..42
# Show snapper config
sudo snapper -c root get-config
```
---
## Boot Recovery
If your system won't boot:
1. At limine boot menu, select a snapshot
2. System boots into that snapshot state
3. Once booted, you can:
- Fix the issue
- Roll back permanently with `snapper rollback`
- Create a new snapshot of the working state