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

Dotfiles update 2025-12-24 17:46

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-24 17:46:07 -05:00
parent b12a5a7b0f
commit e86371e63a
10 changed files with 1665 additions and 4111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

495
INSTALL.md Normal file
View File

@@ -0,0 +1,495 @@
# Installation Guide
Complete installation guide for ADLee's Dotfiles on Arch Linux and CachyOS.
## Table of Contents
- [Requirements](#requirements)
- [Quick Install](#quick-install)
- [Step-by-Step Installation](#step-by-step-installation)
- [Post-Installation](#post-installation)
- [Optional Tools](#optional-tools)
- [Customization](#customization)
- [Updating](#updating)
- [Uninstalling](#uninstalling)
- [Troubleshooting](#troubleshooting)
---
## Requirements
### Operating System
- **Arch Linux** or **CachyOS** (other Arch-based distros may work but are untested)
### Required Packages
These are installed automatically by `install.sh`:
| Package | Purpose |
|---------|---------|
| `git` | Version control |
| `curl` | HTTP requests |
| `zsh` | Shell |
### Recommended Packages
| Package | Purpose | Install |
|---------|---------|---------|
| `fzf` | Fuzzy finder (command palette) | `sudo pacman -S fzf` |
| `bat` | Better cat with syntax highlighting | `sudo pacman -S bat` |
| `eza` | Modern ls replacement | `sudo pacman -S eza` |
| `tmux` | Terminal multiplexer | `sudo pacman -S tmux` |
| `neovim` | Modern vim | `sudo pacman -S neovim` |
### For Full Functionality
| Package | Purpose | Install |
|---------|---------|---------|
| `age` or `gpg` | Vault encryption | `sudo pacman -S age` |
| `lastpass-cli` | Password manager | `paru -S lastpass-cli` |
| `snapper` | Btrfs snapshots | `sudo pacman -S snapper` |
| `limine-snapper-sync` | Boot menu sync | `paru -S limine-snapper-sync` |
| `compsize` | Btrfs compression stats | `sudo pacman -S compsize` |
| `gum` | Interactive wizard | `sudo pacman -S gum` |
---
## Quick Install
### One-Liner
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh
```
### With Interactive Wizard
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard
```
---
## Step-by-Step Installation
### 1. Clone the Repository
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
```
### 2. Review Configuration (Optional)
Edit `dotfiles.conf` before installing to customize:
```bash
vim dotfiles.conf
```
Key settings to review:
```bash
# Your identity
USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com"
USER_GITHUB="yourusername"
# Feature toggles
INSTALL_FZF="ask" # true, false, or ask
INSTALL_BAT="ask"
INSTALL_EZA="ask"
INSTALL_NEOVIM="ask"
SET_ZSH_DEFAULT="ask"
# MOTD style
MOTD_STYLE="compact" # compact, mini, full, or none
```
### 3. Run the Installer
```bash
./install.sh
```
The installer will:
1. Detect your OS (Arch/CachyOS only)
2. Install core dependencies (git, curl, zsh)
3. Backup existing configuration files
4. Install Oh-My-Zsh
5. Install zsh plugins (autosuggestions, syntax-highlighting)
6. Configure git (prompts for name/email if not set)
7. Create symlinks for all dotfiles
8. Optionally set zsh as default shell
9. Offer to install optional tools
### 4. Restart Your Terminal
```bash
exec zsh
```
Or simply close and reopen your terminal.
---
## Post-Installation
### Verify Installation
```bash
dfd # or: dotfiles-doctor.sh
```
This runs a health check and reports any issues.
### Fix Any Issues
```bash
dffix # or: dotfiles-doctor.sh --fix
```
### Initialize the Secrets Vault
If you plan to use the vault for storing API keys:
```bash
vault init
```
### Set Up LastPass (Optional)
```bash
# Install
paru -S lastpass-cli
# Login
lpass login your@email.com
# Test
pw list
```
### Configure Snapper (CachyOS/Btrfs)
If using btrfs with snapshots:
```bash
# Install snapper
sudo pacman -S snapper
# Create config for root
sudo snapper -c root create-config /
# Install limine sync (if using limine bootloader)
paru -S limine-snapper-sync
sudo systemctl enable limine-snapper-sync.service
# Verify
snap-validate-service
```
---
## Optional Tools
### AUR Helper
If you don't have an AUR helper:
```bash
# Install paru (recommended)
sudo pacman -S --needed base-devel
git clone https://aur.archlinux.org/paru.git /tmp/paru
cd /tmp/paru && makepkg -si
```
### Recommended Tool Installation
```bash
# All recommended tools at once
sudo pacman -S fzf bat eza tmux neovim fd ripgrep
# AUR packages
paru -S lastpass-cli glow
```
### Espanso (Text Expansion)
```bash
# Install
paru -S espanso-wayland # or espanso-x11 for X11
# Start service
espanso service start
# Link config
ln -sf ~/.dotfiles/espanso ~/.config/espanso
# Personalize
./setup/setup-espanso.sh
```
---
## Customization
### Local Overrides
Create `~/.zshrc.local` for machine-specific settings that won't be synced:
```bash
# ~/.zshrc.local
# Machine-specific aliases
alias proj='cd ~/my-local-project'
# Local environment variables
export MY_LOCAL_VAR="value"
# Override settings
MOTD_STYLE="mini"
```
### Adding Custom Functions
Add `.zsh` files to `~/.dotfiles/zsh/functions/` – they're auto-loaded.
### Custom Tmux Templates
Add templates to `~/.dotfiles/.tmux-templates/`:
```bash
# ~/.dotfiles/.tmux-templates/mytemplate.tmux
# My custom layout
split-window -h -p 40
split-window -v -p 30
select-pane -t 0
```
Use with: `tw-create myproject mytemplate`
### Custom Bookmarks
```bash
bookmark work ~/projects/work
bookmark docs ~/Documents
j work # jump to bookmark
```
---
## Updating
### Update Dotfiles
```bash
dfu # or: dotfiles-update.sh
```
This will:
1. Pull latest changes from git
2. Optionally re-run the installer to update symlinks
### Check for Updates
```bash
dfv # or: dotfiles-version.sh
```
### Sync Across Machines
```bash
# Push local changes
dfpush "Updated aliases"
# Pull remote changes
dfpull
# Check sync status
dfs
```
---
## Uninstalling
### Remove Symlinks Only
```bash
./install.sh --uninstall
```
This will:
1. Remove all symlinks created by the installer
2. Offer to restore backed-up files
### Complete Removal
```bash
./install.sh --uninstall --purge
```
This will:
1. Remove all symlinks
2. Offer to restore backups
3. Delete the `~/.dotfiles` directory
### Manual Cleanup
If needed, manually remove:
```bash
rm -rf ~/.dotfiles
rm -f ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
rm -rf ~/.config/nvim
rm -f ~/.local/bin/dotfiles-*
```
---
## Troubleshooting
### Command Not Found
If dotfiles commands aren't available:
```bash
# Ensure PATH includes ~/.local/bin
echo $PATH | grep -q ".local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc.local
# Reload
source ~/.zshrc
```
### Oh-My-Zsh Issues
```bash
# Reinstall Oh-My-Zsh
rm -rf ~/.oh-my-zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
# Reinstall plugins
git clone --depth 1 https://github.com/zsh-users/zsh-autosuggestions ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
git clone --depth 1 https://github.com/zsh-users/zsh-syntax-highlighting ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
```
### Broken Symlinks
```bash
# Check for broken symlinks
dfd
# Fix automatically
dffix
```
### MOTD Not Showing
Check configuration:
```bash
# In dotfiles.conf
ENABLE_MOTD="true"
MOTD_STYLE="compact"
# Force show
motd --force
```
### Slow Shell Startup
Compile zsh files for faster loading:
```bash
dfcompile
```
Profile startup time:
```bash
# Add to top of ~/.zshrc
zmodload zsh/zprof
# At bottom of ~/.zshrc
zprof
# Then start new shell and review output
```
### Git Configuration Issues
```bash
# Check current config
git config --global --list
# Set manually
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```
### FZF Not Working
```bash
# Verify installation
which fzf
# Check if sourced correctly
[[ -d "$HOME/.fzf" || -f "/usr/share/fzf/key-bindings.zsh" ]] && echo "FZF available"
# Source manually if needed
source /usr/share/fzf/key-bindings.zsh
source /usr/share/fzf/completion.zsh
```
### Permission Denied on Scripts
```bash
# Fix permissions
chmod +x ~/.dotfiles/install.sh
chmod +x ~/.dotfiles/bin/*.sh
```
Or use:
```bash
dffix
```
---
## Install Options Reference
```bash
./install.sh [OPTIONS]
Options:
(none) Standard installation
--wizard Interactive TUI wizard
--skip-deps Skip dependency installation
--deps-only Only install dependencies
--uninstall Remove symlinks
--purge With --uninstall, also remove ~/.dotfiles
--help Show help
```
---
## Getting Help
```bash
# Dotfiles health check
dfd
# Version and update info
dfv
# Command help
dotfiles-cli help
```
For issues, check the [GitHub repository](https://github.com/adlee-was-taken/dotfiles).

894
README.md
View File

@@ -1,97 +1,191 @@
# ADLee's Dotfiles (Arch/CachyOS) # ADLee's Dotfiles
Personal configuration files for a fast, productive dev environment on **Arch Linux** and **CachyOS**. Personal configuration files for a fast, productive development environment on **Arch Linux** and **CachyOS**.
[![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/)
[![OS](https://img.shields.io/badge/OS-Arch%2FCachyOS-blue.svg)](https://archlinux.org/) [![OS](https://img.shields.io/badge/OS-Arch%20%2F%20CachyOS-blue.svg)](https://archlinux.org/)
``` ```
┌[alee@battlestation]─[~/.dotfiles ⎇ main] ┌[alee@battlestation]─[~/.dotfiles ⎇ main]─[⇑3]
└% └%
``` ```
## ✨ Features ## Features at a Glance
| Feature | Description | | Feature | Description |
|---------|-------------| |---------|-------------|
| **Setup Wizard** | Beautiful TUI installer with feature selection | | **Dynamic MOTD** | System info on shell start (uptime, load, memory, updates) |
| **Dynamic MOTD** | System info on shell start (uptime, CPU, memory, updates) | | **Two-Line Prompt** | Git status, command timer, update indicator, root detection |
| **Zsh Theme** | Two-line prompt with git status, command timer, root detection | | **Command Palette** | Raycast-style fuzzy launcher (`Ctrl+Space`) |
| **Command Palette** | Raycast-style fuzzy launcher (Ctrl+Space) |
| **Smart Suggestions** | Typo correction + alias recommendations | | **Smart Suggestions** | Typo correction + alias recommendations |
| **Shell Analytics** | Track command usage and get insights | | **Systemd Helpers** | Quick service management shortcuts |
| **Secrets Vault** | Encrypted storage for API keys and sensitive data | | **Btrfs Helpers** | Filesystem health, scrub, balance commands |
| **LastPass CLI** | Unified password manager integration | | **Snapper Integration** | Btrfs snapshots with limine boot menu sync |
| **Dotfiles Sync** | Keep configuration in sync across machines | | **Secrets Vault** | Encrypted storage for API keys (age/gpg) |
| **Snapper Integration** | Btrfs snapshot management with limine-snapper-sync | | **Password Manager** | LastPass CLI integration |
| **Tmux Workspaces** | Project templates with pre-configured layouts | | **Tmux Workspaces** | Project templates with pre-configured layouts |
| **SSH Manager** | Save and manage SSH connections with tmux integration | | **SSH Manager** | Save and manage SSH connections with tmux |
| **Python Templates** | Quick project scaffolding (Django, Flask, FastAPI, etc.) |
| **Dotfiles Sync** | Keep configuration in sync across machines |
| **Shell Analytics** | Track command usage and get insights |
## 🚀 Quick Start ---
### One-liner Install ## Quick Start
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh
```
### Interactive Wizard (Recommended)
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard
```
### Standard Install
```bash ```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles cd ~/.dotfiles
./install.sh ./install.sh
``` ```
## 📋 System Requirements See [INSTALL.md](INSTALL.md) for detailed installation instructions.
- **OS:** Arch Linux or CachyOS ---
- **Editors:** Vim (required), Neovim (optional)
- **Password Manager:** LastPass
- **Shell:** Zsh (installed by script)
- **Package Manager:** Pacman (built-in)
## 📁 Repository Layout ## Command Reference
``` ### Dotfiles Management
dotfiles/
├── install.sh # Main installer script | Command | Alias | Description |
├── dotfiles.conf # Central configuration |---------|-------|-------------|
├── zsh/ | `dotfiles-doctor.sh` | `dfd`, `doctor` | Health check |
│ ├── .zshrc # Shell configuration | `dotfiles-doctor.sh --fix` | `dffix` | Auto-fix issues |
│ ├── aliases.zsh # Command aliases | `dotfiles-doctor.sh --quick` | - | Quick essential checks |
│ ├── themes/adlee.zsh-theme # Prompt theme | `dotfiles-sync.sh` | `dfs`, `dfsync` | Sync status |
│ └── functions/ | `dotfiles-sync.sh push` | `dfpush` | Push changes to remote |
│ ├── command-palette.zsh # Ctrl+Space launcher | `dotfiles-sync.sh pull` | `dfpull` | Pull remote changes |
│ ├── motd.zsh # System info display | `dotfiles-update.sh` | `dfu`, `dfupdate` | Update dotfiles |
│ ├── smart-suggest.zsh # Typo correction | `dotfiles-version.sh` | `dfv`, `dfversion` | Version info |
│ ├── password-manager.zsh # LastPass integration | `dotfiles-stats.sh` | `dfstats` | Shell analytics |
│ ├── snapper.zsh # Btrfs snapshots | `dotfiles-vault.sh` | `vault` | Secrets manager |
│ ├── ssh-manager.zsh # SSH profiles | `dotfiles-compile.sh` | `dfcompile` | Compile zsh for speed |
│ ├── tmux-workspaces.zsh # Workspace templates | `source ~/.zshrc` | `reload`, `rl` | Reload shell config |
│ └── python-templates.zsh # Python project scaffolding
├── vim/.vimrc # Vim configuration ### Quick Edit Aliases
├── nvim/ # Neovim configuration
├── tmux/.tmux.conf # Tmux configuration | Alias | Opens |
├── git/.gitconfig.template # Git configuration template |-------|-------|
└── bin/ # Scripts (symlinked to ~/.local/bin) | `v.zshrc` | `~/.zshrc` |
├── dotfiles-doctor.sh # Health checker | `v.conf` | `~/.dotfiles/dotfiles.conf` |
├── dotfiles-sync.sh # Multi-machine sync | `v.alias` | `~/.dotfiles/zsh/aliases.zsh` |
├── dotfiles-stats.sh # Shell analytics | `v.motd` | `~/.dotfiles/zsh/functions/motd.zsh` |
├── dotfiles-update.sh # Update dotfiles | `v.edit` | `~/.dotfiles` directory in editor |
├── dotfiles-vault.sh # Encrypted secrets manager
└── dotfiles-version.sh # Version info ---
## Systemd Helpers
Quick shortcuts for systemd service management.
### Core Commands
| Command | Description |
|---------|-------------|
| `sc <args>` | `sudo systemctl <args>` |
| `scu <args>` | `systemctl --user <args>` |
| `scr <service>` | Restart service and show status |
| `sce <service>` | Enable and start service |
| `scd <service>` | Disable and stop service |
| `sclog <service>` | Follow journal logs (`-f`) |
| `sclogs <service>` | Show recent logs (no follow) |
### Status Commands
| Command | Description |
|---------|-------------|
| `sc-failed` | Show failed services (system + user) |
| `sc-timers` | Show active timers |
| `sc-recent` | Recently started services |
| `sc-boot` | Boot time analysis |
| `sc-search <query>` | Search services by name |
| `sc-info <service>` | Detailed service info |
### Interactive (requires fzf)
| Command | Description |
|---------|-------------|
| `scf` | Interactive service manager with preview |
| `sclogf` | Interactive log viewer |
### Aliases
| Alias | Command |
|-------|---------|
| `scs` | `sc status` |
| `scstart` | `sc start` |
| `scstop` | `sc stop` |
| `screload` | `sc daemon-reload` |
| `jctl` | `journalctl` |
| `jctlf` | `journalctl -f` |
| `jctlb` | `journalctl -b` |
| `jctlerr` | `journalctl -p err -b` |
---
## Btrfs Helpers
Quick commands for btrfs filesystem management (CachyOS defaults to btrfs).
### Information
| Command | Alias | Description |
|---------|-------|-------------|
| `btrfs-usage [mount]` | `btru` | Filesystem usage summary |
| `btrfs-subs [mount]` | `btrs` | List all subvolumes |
| `btrfs-info [mount]` | `btri` | Full filesystem information |
| `btrfs-health [mount]` | `btrh` | Quick health check |
| `btrfs-compress [path]` | `btrc` | Compression stats (requires `compsize`) |
### Maintenance
| Command | Description |
|---------|-------------|
| `btrfs-balance [mount]` | Start balance operation |
| `btrfs-balance-status` | Check balance progress |
| `btrfs-balance-cancel` | Cancel running balance |
| `btrfs-scrub [mount]` | Start scrub (integrity check) |
| `btrfs-scrub-status` | Check scrub progress |
| `btrfs-scrub-cancel` | Cancel running scrub |
| `btrfs-defrag <path>` | Defragment file/directory |
| `btrfs-maintain [mount]` | Full maintenance routine |
### Snapshots
| Command | Description |
|---------|-------------|
| `btrfs-snap-usage` | Show snapshot space usage |
> **Note:** Most commands default to `/` if no mount point is specified. See also `snapper.zsh` for snapshot management.
---
## Snapper Integration
Btrfs snapshot management with limine bootloader sync.
| Command | Alias | Description |
|---------|-------|-------------|
| `snap-create "description"` | `snap` | Create snapshot with validation |
| `snap-list [count]` | `snapls` | List recent snapshots (default: 10) |
| `snap-show <number>` | `snapshow` | Show snapshot details |
| `snap-delete <number>` | `snaprm` | Delete snapshot |
| `snap-check-limine` | `snapcheck` | Verify boot menu sync |
| `snap-sync` | `snapsync` | Manually trigger limine sync |
| `snap-validate-service` | - | Check service status |
### System Update with Snapshot
```bash
sys-update # Creates pre/post snapshot around pacman -Syu
``` ```
## 🎮 Command Palette ---
Press **Ctrl+Space** or **Ctrl+P** to open the fuzzy command launcher: ## Command Palette
Press **`Ctrl+Space`** or **`Ctrl+P`** to open the fuzzy command launcher.
``` ```
╭──────────────────────────────────────────╮ ╭──────────────────────────────────────────╮
@@ -105,23 +199,37 @@ Press **Ctrl+Space** or **Ctrl+P** to open the fuzzy command launcher:
╰──────────────────────────────────────────╯ ╰──────────────────────────────────────────╯
``` ```
**Searches:** aliases, functions, recent commands, bookmarks, git commands, quick actions ### Searches
**Keybindings:** - Aliases and functions
- `Enter` - Execute command - Recent commands
- `Ctrl+E` - Edit before running - Git commands (when in repo)
- `Ctrl+Y` - Copy to clipboard - Docker commands
- Bookmarked directories
- Dotfiles scripts
- Quick actions
### Keybindings
| Key | Action |
|-----|--------|
| `Enter` | Execute command |
| `Ctrl+E` | Edit before running |
| `Ctrl+Y` | Copy to clipboard |
| `Ctrl+R` | Reload entries |
### Directory Bookmarks ### Directory Bookmarks
```bash | Command | Alias | Description |
bookmark projects ~/projects # Save bookmark |---------|-------|-------------|
bookmark list # List all | `bookmark <name> [path]` | `bm` | Save bookmark (default: current dir) |
jump projects # Go to bookmark | `bookmark list` | `bm list` | List all bookmarks |
j # Fuzzy select | `bookmark delete <name>` | `bm rm` | Delete bookmark |
``` | `jump <name>` | `j` | Go to bookmark (fuzzy select if no name) |
## 🔧 Smart Suggestions ---
## Smart Suggestions
Automatic typo correction for 100+ common mistakes: Automatic typo correction for 100+ common mistakes:
@@ -129,10 +237,6 @@ Automatic typo correction for 100+ common mistakes:
$ gti status $ gti status
✗ Command not found: gti ✗ Command not found: gti
→ Did you mean: git? → Did you mean: git?
$ dokcer ps
✗ Command not found: dokcer
→ Did you mean: docker?
``` ```
Alias recommendations for frequently typed commands: Alias recommendations for frequently typed commands:
@@ -142,222 +246,347 @@ Alias recommendations for frequently typed commands:
Consider adding: alias gs='git status' Consider adding: alias gs='git status'
``` ```
## 📊 Shell Analytics ### Supported Typos
Git, Docker, common commands (ls, cat, grep, mkdir, etc.), Python, Node, sudo, ssh, vim, and more.
### Quick Fix
```bash ```bash
dotfiles-stats.sh # Full dashboard fuck # Re-run last command with typo correction
# or use aliases:
dfstats
stats
``` ```
``` ---
╔═══════════════════════════════════════════════════════════════════╗
║ Shell Analytics Dashboard ║
╠═══════════════════════════════════════════════════════════════════╣
║ Total commands: 4,832 ║
║ Unique commands: 847 ║
║ ║
║ Top Commands ║
║ git 847 ████████████████████████░░░░░░ ║
║ cd 412 ████████████░░░░░░░░░░░░░░░░░░ ║
║ ls 398 ███████████░░░░░░░░░░░░░░░░░░░ ║
╚═══════════════════════════════════════════════════════════════════╝
```
## 🔐 Secrets Vault ## MOTD (Message of the Day)
Encrypted storage for API keys and tokens: System info displayed on shell startup.
```bash ### Display Styles
vault set GITHUB_TOKEN ghp_xxxxxxxxxxxx
vault set AWS_SECRET_KEY # Prompts for hidden input
vault get GITHUB_TOKEN
vault list # Shows keys only
vault delete OLD_KEY
# Full command: dotfiles-vault.sh
```
Export to environment: | Style | Command | Description |
```bash
eval $(vault shell) # Load all secrets
```
Uses `age` or `gpg` encryption. Secrets auto-load on shell start.
## 🔑 Password Manager Integration
LastPass CLI for unified password management:
```bash
pw list # List all items
pw get github # Get password
pw get github username # Get specific field
pw otp github # Get TOTP code
pw copy aws # Copy password to clipboard
pw search mail # Search items
pwf # Fuzzy search + copy (requires fzf)
```
### Install LastPass CLI
```bash
# Via AUR with paru (recommended)
paru -S lastpass-cli
# Or with yay
yay -S lastpass-cli
```
## 🖥️ Dynamic MOTD
System info displayed on shell startup:
```
┌──────────────────────────────────────────────────────────────┐
│ ✦ alee@battlestation Mon Dec 15 14:30 │
├──────────────────────────────────────────────────────────────┤
│ ▲ up:4d 7h ◆ load:0.45 ◇ mem:8.2/32G ⊡ 234G free │
└──────────────────────────────────────────────────────────────┘
```
Shows: uptime, load average, memory usage, disk space
**Configuration:**
```bash
ENABLE_MOTD="true" # Enable MOTD
MOTD_STYLE="compact" # compact (box), mini (single line), or off
```
## 🎨 Zsh Theme
```
┌[user@hostname]─[~/projects ⎇ main *]
└%
```
**Features:**
- Two-line prompt for clarity
- Git integration (branch name with dirty indicator `*`)
- Command timer (shows elapsed time for commands >10s)
- Smart path truncation
- Root detection (red for root, blue for users)
## 🔄 Dotfiles Sync
Keep configuration synchronized across machines:
```bash
dotfiles-sync.sh # Interactive sync
dotfiles-sync.sh --status # Show sync status
dotfiles-sync.sh --push # Push changes
dotfiles-sync.sh --pull # Pull changes
dotfiles-sync.sh --watch 300 # Auto-sync every 5 min
```
On shell start, you'll see notifications of available updates.
## 📸 Snapper Integration
Btrfs snapshot management for Arch with limine bootloader:
```bash
snap-create "Before system update" # Create snapshot
snap-list 20 # List recent snapshots
snap-check-limine # Verify boot menu sync
snap-delete 42 # Delete snapshot
snap-validate-service # Check service status
```
Auto-syncs with `limine-snapper-sync` for boot menu entries.
**Install on CachyOS/Arch:**
```bash
paru -S limine-snapper-sync
sudo systemctl enable limine-snapper-sync.service
```
## 🎯 Tmux Workspace Manager
Pre-configured layouts for different workflows:
```bash
tw-create myproject dev # Create dev workspace
tw myproject # Quick attach or create
tw-list # List active workspaces
tw-save my-custom-layout # Save current layout as template
tw-sync # Toggle pane sync for multi-server
twf # Fuzzy search workspaces
```
**Available Templates:**
- `dev` - Vim (50%) + terminal (25%) + logs (25%)
- `ops` - 4-pane monitoring grid
- `ssh-multi` - 4 panes for multi-server management
- `debug` - 2 panes: main (70%) + helper (30%)
- `full` - Single full-screen pane
- `review` - Side-by-side code review panes
## 🌐 SSH Session Manager
Save and manage SSH connections with automatic tmux integration:
```bash
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key
ssh-connect prod # Auto-creates/attaches tmux session
ssh-list # List all profiles
sshf # Fuzzy search and connect
ssh-sync-dotfiles prod # Deploy dotfiles to remote
```
## 🐍 Python Project Templates
Quick project scaffolding with virtual environments:
```bash
py-new myproject # Basic Python project
py-django myblog # Django web app
py-flask myapp # Flask web app
py-fastapi myapi # FastAPI REST API
py-data analysis # Data science project
py-cli mytool # CLI tool with Click
```
All include virtual environment setup, git initialization, and project structure.
## ⌨️ Command Aliases
All dotfiles commands have convenient aliases:
| Alias | Command | Description |
|-------|---------|-------------| |-------|---------|-------------|
| `dfd` | `dotfiles-doctor.sh` | Health check | | Compact | `show_motd` | Box format with stats |
| `dffix` | `dotfiles-doctor.sh --fix` | Auto-fix issues | | Mini | `show_motd_mini` | Single line |
| `dfs` | `dotfiles-sync.sh` | Sync dotfiles | | Full | `show_motd_full` | Extended info with kernel, scheduler |
| `dfpush` | `dotfiles-sync.sh --push` | Push changes |
| `dfpull` | `dotfiles-sync.sh --pull` | Pull changes |
| `dfu` | `dotfiles-update.sh` | Update dotfiles |
| `dfv` | `dotfiles-version.sh` | Version info |
| `dfstats` | `dotfiles-stats.sh` | Shell analytics |
| `vault` | `dotfiles-vault.sh` | Secrets manager |
| `pw` | LastPass password manager | Get/list passwords |
| `tw` | Tmux workspace manager | Quick workspace access |
| `reload` | `source ~/.zshrc` | Reload shell config |
## 🩺 Health Check ### Configuration
In `dotfiles.conf`:
```bash ```bash
dotfiles-doctor.sh # Run diagnostics ENABLE_MOTD="true"
dotfiles-doctor.sh --fix # Auto-fix issues MOTD_STYLE="compact" # compact, mini, full, or none
# Aliases: dfd, doctor, dffix
``` ```
Checks: symlinks, zsh plugins, git config, optional tools, and more ### Force Refresh
## ⚙️ Configuration ```bash
motd # Compact
motd-mini # Mini
motd-full # Full
sysbrief # Quick system overview (callable anytime)
```
Edit `~/.dotfiles/dotfiles.conf` to customize: ---
## Secrets Vault
Encrypted storage for API keys and tokens using `age` or `gpg`.
| Command | Description |
|---------|-------------|
| `vault init` | Initialize vault |
| `vault set <key> [value]` | Store secret (prompts if value omitted) |
| `vault get <key>` | Retrieve secret |
| `vault list` | List all keys |
| `vault delete <key>` | Delete secret |
| `vault shell` | Print as export statements |
| `vault export <file>` | Backup vault (encrypted) |
| `vault import <file>` | Restore from backup |
| `vault status` | Show vault info |
### Aliases
| Alias | Command |
|-------|---------|
| `vls` | `vault list` |
| `vget` | `vault get` |
| `vset` | `vault set` |
### Auto-load on Shell Start
Secrets can be auto-exported to environment. Enable in `.zshrc`:
```bash
eval $(vault shell)
```
---
## Password Manager (LastPass)
Unified interface for LastPass CLI.
| Command | Description |
|---------|-------------|
| `pw list` | List all items |
| `pw get <item> [field]` | Get field (default: password) |
| `pw otp <item>` | Get TOTP code |
| `pw search <query>` | Search items |
| `pw copy <item> [field]` | Copy to clipboard |
| `pw lock` | Logout/lock session |
### Fields
`password`, `username`, `url`, `notes`, or any custom field name.
### Aliases
| Alias | Command |
|-------|---------|
| `pwl` | `pw list` |
| `pwg` | `pw get` |
| `pwc` | `pw copy` |
| `pws` | `pw search` |
### FZF Integration
| Command | Description |
|---------|-------------|
| `pwf` | Fuzzy search and copy password |
| `pwof` | Fuzzy search and copy OTP |
---
## Tmux Workspace Manager
Pre-configured layouts for different workflows.
### Workspace Commands
| Command | Alias | Description |
|---------|-------|-------------|
| `tw <name> [template]` | - | Attach or create workspace |
| `tw-create <name> [template]` | `twc` | Create workspace |
| `tw-attach <name>` | `twa` | Attach to workspace |
| `tw-list` | `twl` | List active workspaces |
| `tw-delete <name>` | `twd` | Delete workspace |
| `tw-save <name>` | `tws` | Save current layout as template |
| `tw-templates` | `twt` | List available templates |
| `tw-template-edit <name>` | `twe` | Edit template |
| `tw-sync` | - | Toggle pane synchronization |
| `tw-rename <old> <new>` | - | Rename workspace |
| `twf` | - | Fuzzy search workspaces |
### Built-in Templates
| Template | Description |
|----------|-------------|
| `dev` | Vim (50%) + terminal (25%) + logs (25%) |
| `ops` | 4-pane monitoring grid |
| `ssh-multi` | 4 panes for multi-server management |
| `debug` | Main (70%) + helper (30%) |
| `full` | Single full-screen pane |
| `review` | Side-by-side code review |
---
## SSH Session Manager
Save and manage SSH connections with automatic tmux integration.
| Command | Alias | Description |
|---------|-------|-------------|
| `ssh-save <name> <user@host> [port] [key] [opts] [desc]` | `sshs` | Save profile |
| `ssh-list` | `sshl` | List all profiles |
| `ssh-connect <name>` | `sshc` | Connect (auto tmux) |
| `ssh-delete <name>` | `sshd` | Delete profile |
| `ssh-reconnect [name]` | `sshr` | Reconnect (default: last) |
| `ssh-sync-dotfiles <name>` | `sshsync` | Deploy dotfiles to remote |
| `sshf` | - | Fuzzy search and connect |
### Configuration
In `dotfiles.conf`:
```bash
SSH_AUTO_TMUX="true" # Auto-create tmux session
SSH_TMUX_SESSION_PREFIX="ssh" # Session naming prefix
SSH_SYNC_DOTFILES="ask" # Sync dotfiles on connect
```
---
## Python Project Templates
Quick project scaffolding with virtual environments.
| Command | Alias | Description |
|---------|-------|-------------|
| `py-new <name>` | `pynew` | Basic Python project |
| `py-django <name>` | `pydjango` | Django web app |
| `py-flask <name>` | `pyflask` | Flask web app |
| `py-fastapi <name>` | `pyfast` | FastAPI REST API |
| `py-data <name>` | `pydata` | Data science project |
| `py-cli <name>` | `pycli` | CLI tool with Click |
### Quick Venv Activation
```bash
venv # Activates venv, .venv, or env if found
```
---
## Shell Analytics
Track command usage and get insights.
| Command | Description |
|---------|-------------|
| `dfstats` | Full dashboard |
| `dfstats top [n]` | Top N commands |
| `dfstats suggest` | Alias suggestions |
| `dfstats breakdown` | Category breakdown |
| `dfstats heatmap` | Activity by hour |
| `dfstats dirs` | Most visited directories |
| `dfstats git` | Git command breakdown |
| `dfstats export` | Export as JSON |
---
## Common Aliases
### Navigation
| Alias | Command |
|-------|---------|
| `..` | `cd ..` |
| `...` | `cd ../..` |
| `....` | `cd ../../..` |
| `~` | `cd ~` |
| `c.` | `cd ~/.dotfiles` |
### Git
| Alias | Command |
|-------|---------|
| `g` | `git` |
| `gs` | `git status` |
| `ga` | `git add` |
| `gc` | `git commit` |
| `gp` | `git push` |
| `gl` | `git pull` |
| `gd` | `git diff` |
| `gco` | `git checkout` |
| `gb` | `git branch` |
| `glog` | `git log --oneline --graph --decorate --all` |
### Docker
| Alias | Command |
|-------|---------|
| `d` | `docker` |
| `dc` | `docker-compose` |
| `dps` | `docker ps` |
| `dpa` | `docker ps -a` |
| `di` | `docker images` |
| `dex` | `docker exec -it` |
### System
| Alias | Command |
|-------|---------|
| `h` | `history` |
| `c` | `clear` |
| `myip` | `curl -s ifconfig.me` |
| `ports` | `netstat -tulanp` |
### Tools (conditional)
| Alias | Command | Condition |
|-------|---------|-----------|
| `ls` | `eza --icons` | if eza installed |
| `ll` | `eza -lah --icons` | if eza installed |
| `la` | `eza -a --icons` | if eza installed |
| `lt` | `eza --tree --level=2 --icons` | if eza installed |
| `cat` | `bat --paging=never` | if bat installed |
---
## Zsh Theme Features
The `adlee` theme provides:
- **Two-line prompt** for clarity
- **Git integration** with branch name and dirty indicator (`*`)
- **Command timer** for commands taking >10 seconds
- **Update indicator** showing available package updates
- **Root detection** (red `#` for root, blue `%` for users)
- **Smart path display**
### Timer Display
| Duration | Color |
|----------|-------|
| >1 hour | Red |
| >1 minute | Orange |
| >10 seconds | Green |
---
## Espanso Text Expansion
Text expansion snippets for quick typing.
### Date/Time
| Trigger | Output |
|---------|--------|
| `..date` | `2025-12-24` |
| `..time` | `14:30:45` |
| `..dt` | `2025-12-24 14:30:45 EST` |
| `..ts` | ISO 8601 timestamp |
| `..epoch` | Unix timestamp |
### Quick Text
| Trigger | Output |
|---------|--------|
| `..shrug` | `¯\_(ツ)_/¯` |
| `..flip` | `(╯°□°)╯︵ ┻━┻` |
| `..lgtm` | `Looks good to me` |
### Code
| Trigger | Output |
|---------|--------|
| `..bash` | Bash shebang + set -euo pipefail |
| `..python` | Python main boilerplate |
| `..mdcode` | Markdown code block |
See [REFERENCE.md](REFERENCE.md) for complete Espanso reference.
---
## Key Bindings
| Binding | Action |
|---------|--------|
| `Ctrl+Space` | Command palette |
| `Ctrl+P` | Command palette (alternative) |
| `Alt+R` | Reload zsh config |
| `Ctrl+→` | Forward word |
| `Ctrl+←` | Backward word |
| `Home` | Beginning of line |
| `End` | End of line |
---
## Configuration
Edit `~/.dotfiles/dotfiles.conf`:
```bash ```bash
# Identity # Identity
@@ -365,71 +594,72 @@ USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com" USER_EMAIL="you@example.com"
USER_GITHUB="yourusername" USER_GITHUB="yourusername"
# Features # MOTD
INSTALL_ZSH_PLUGINS="true" ENABLE_MOTD="true"
INSTALL_FZF="ask" MOTD_STYLE="compact"
INSTALL_NEOVIM="ask"
SET_ZSH_DEFAULT="ask"
# Advanced # Features
ENABLE_SMART_SUGGESTIONS="true" ENABLE_SMART_SUGGESTIONS="true"
ENABLE_COMMAND_PALETTE="true" ENABLE_COMMAND_PALETTE="true"
ENABLE_VAULT="true" ENABLE_VAULT="true"
DOTFILES_AUTO_SYNC_CHECK="true" DOTFILES_AUTO_SYNC_CHECK="true"
# Btrfs
BTRFS_DEFAULT_MOUNT="/"
# Package Manager
AUR_HELPER="auto" # paru, yay, or auto
``` ```
## 🔄 Updating ---
```bash ## Repository Structure
dotfiles-update.sh
# or aliases: ```
dfu ~/.dotfiles/
dfupdate ├── install.sh # Main installer
├── dotfiles.conf # Central configuration
├── bin/ # Scripts (symlinked to ~/.local/bin)
│ ├── dotfiles-doctor.sh
│ ├── dotfiles-sync.sh
│ ├── dotfiles-update.sh
│ ├── dotfiles-vault.sh
│ ├── dotfiles-stats.sh
│ ├── dotfiles-version.sh
│ └── dotfiles-compile.sh
├── zsh/
│ ├── .zshrc
│ ├── aliases.zsh
│ ├── lib/
│ │ └── colors.zsh # Shared color definitions
│ ├── themes/
│ │ └── adlee.zsh-theme
│ └── functions/
│ ├── btrfs-helpers.zsh
│ ├── command-palette.zsh
│ ├── motd.zsh
│ ├── password-manager.zsh
│ ├── python-templates.zsh
│ ├── smart-suggest.zsh
│ ├── snapper.zsh
│ ├── ssh-manager.zsh
│ ├── systemd-helpers.zsh
│ └── tmux-workspaces.zsh
├── vim/.vimrc
├── tmux/.tmux.conf
├── git/.gitconfig.template
├── espanso/ # Text expansion
├── setup/ # Setup scripts
└── .tmux-templates/ # Workspace layouts
``` ```
Check version: ---
```bash
dotfiles-version.sh
# or: dfv
```
## 🗑️ Uninstalling ## License
```bash
./install.sh --uninstall # Remove symlinks
./install.sh --uninstall --purge # Also delete ~/.dotfiles
```
## 📚 Documentation
- [SETUP_GUIDE.md](docs/SETUP_GUIDE.md) - Detailed installation and configuration
- [ESPANSO.md](docs/ESPANSO.md) - Text expansion snippets reference
- [SNAPPER.md](docs/SNAPPER.md) - Btrfs snapshot management guide
- [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) - SSH + Tmux workflow
## 🛠️ Install Options
```bash
./install.sh # Standard install
./install.sh --wizard # Interactive TUI wizard
./install.sh --skip-deps # Re-run without checking deps
./install.sh --uninstall # Remove symlinks
./install.sh --help # Show all options
```
## 🤝 Forking
1. Fork the repo
2. Edit `dotfiles.conf` with your settings
3. Customize files as needed
4. The installer will use your fork's URLs
## 📄 License
MIT – See [LICENSE](LICENSE) MIT – See [LICENSE](LICENSE)
--- ---
**Author:** Aaron D. Lee **Author:** Aaron D. Lee
**Repository:** https://github.com/adlee-was-taken/dotfiles **Repository:** https://github.com/adlee-was-taken/dotfiles
**Arch/CachyOS Only Edition**

531
docs/CONTRIBUTING.md
View File

@@ -1,531 +0,0 @@
# Contributing Guide
Thank you for your interest in contributing to the ADLee dotfiles project! This guide explains how to contribute to our Arch/CachyOS-focused dotfiles repository.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Making Changes](#making-changes)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Submitting Changes](#submitting-changes)
- [Architecture Overview](#architecture-overview)
- [Project Philosophy](#project-philosophy)
---
## Code of Conduct
- Be respectful to all contributors
- Provide constructive feedback
- Ask questions when unclear
- Help others when possible
- Focus on the code, not the person
---
## Getting Started
### Prerequisites
- Arch Linux or CachyOS
- Git
- Bash/Zsh
- Understanding of shell scripting
### Fork and Clone
```bash
# Fork on GitHub (click Fork button)
# Clone your fork
git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles-dev
cd ~/.dotfiles-dev
# Add upstream for syncing
git remote add upstream https://github.com/adlee-was-taken/dotfiles.git
# Create feature branch
git checkout -b feature/your-feature
```
---
## Development Setup
### Install in Development Mode
```bash
cd ~/.dotfiles-dev
# Create a test installation in a temporary directory
export DOTFILES_HOME=/tmp/test-dotfiles
mkdir -p $DOTFILES_HOME
# Link your dev dotfiles
ln -s $(pwd) $DOTFILES_HOME/.dotfiles
# Run installer in test mode
DOTFILES_HOME=$DOTFILES_HOME ./install.sh --skip-deps
```
### Testing Without Overwriting
```bash
# Use Docker or chroot to test in isolated environment
docker run -it archlinux:latest bash
# Inside container:
git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```
### Validate Changes
```bash
./install.sh --help # Verify script runs
./install.sh --skip-deps # Test without dependencies
dotfiles-doctor.sh # Health check
```
---
## Making Changes
### What to Change
**Good areas for contribution:**
- Bug fixes
- Feature additions for Arch/CachyOS
- Zsh enhancements
- Vim/Neovim configuration improvements
- LastPass integration improvements
- Documentation and guides
- Performance improvements
- Error messages and validation
**Areas to avoid:**
- Adding support for other OS (macOS, Ubuntu, etc.)
- Adding other password managers (1Password, Bitwarden, etc.)
- Adding other editors (Emacs, VS Code, etc.)
- Changes that increase complexity
### Code Organization
```
dotfiles/
├── install.sh # Main installer - modify carefully
├── dotfiles.conf # Configuration - add new features here
├── zsh/
│ ├── .zshrc # Core zsh config
│ ├── aliases.zsh # Custom aliases
│ ├── themes/ # Prompt themes
│ └── functions/ # Zsh functions (new features go here)
├── vim/ # Vim configuration
├── nvim/ # Neovim configuration
├── tmux/ # Tmux configuration
├── git/ # Git configuration
├── bin/ # Shell scripts (utilities and tools)
└── docs/ # Documentation
```
### Adding a New Feature
**Example: Add a new command palette action**
1. Create function in `zsh/functions/command-palette.zsh`:
```bash
# Add to _command_palette_entries()
case "$entry" in
"myfeature")
my-command
;;
esac
```
2. Add configuration to `dotfiles.conf`:
```bash
ENABLE_MYFEATURE="ask"
```
3. Add logic to `install.sh`:
```bash
if [[ "$ENABLE_MYFEATURE" == "true" ]]; then
pacman -S myfeature-package
fi
```
4. Document in `docs/SETUP_GUIDE.md`:
```markdown
### My Feature
Description of feature...
```
5. Test thoroughly before submitting PR.
---
## Coding Standards
### Shell Script Style
```bash
# Good practices
#!/bin/bash
set -euo pipefail
# Use descriptive variable names
local readonly config_file="$HOME/.dotfiles/dotfiles.conf"
# Quote all variables
echo "$variable"
# Use functions with local variables
function my_function() {
local readonly required_arg="$1"
local optional_arg="${2:-default}"
# Error handling
if [[ ! -f "$required_arg" ]]; then
echo "Error: File not found: $required_arg" >&2
return 1
fi
# Return explicitly
return 0
}
# Use [[ ]] instead of [ ]
if [[ "$condition" == "true" ]]; then
echo "Good"
fi
# Comment complex logic
# Check if file exists and is readable
if [[ -r "$config_file" ]]; then
source "$config_file"
fi
```
### Zsh Style
```zsh
# Functions in zsh/functions/
function my-feature() {
local -a args=("$@")
# Parse arguments
case "${args[1]}" in
list)
# Implementation
;;
*)
echo "Usage: my-feature {list|create|delete}"
return 1
;;
esac
}
# Aliases in zsh/aliases.zsh
alias mf='my-feature'
# Set shell options
setopt nocaseglob
setopt noshglob
# Use proper quoting
print -P "%F{blue}%Btext%b%f"
```
### Comments and Documentation
```bash
# Comment Why, not What
# BAD: Add 5 to count
count=$((count + 5))
# GOOD: Increment by hardcoded snapshot count limit per policy
count=$((count + 5))
# Use TODO for future work
# TODO: Add support for encrypted backups
# Document functions
# my_function: Create a backup of the dotfiles
# Arguments:
# $1: Backup name
# Returns:
# 0 on success, 1 on error
function my_function() {
# ...
}
```
### Error Handling
```bash
# Always check critical operations
if ! pacman -S package; then
echo "Error: Failed to install package" >&2
return 1
fi
# Use set -e with care (only for critical scripts)
set -euo pipefail
# Provide helpful error messages
if [[ ! -d "$DOTFILES_HOME" ]]; then
echo "Error: Dotfiles not found at $DOTFILES_HOME" >&2
echo "Please run: git clone <repo> $DOTFILES_HOME" >&2
return 1
fi
```
---
## Testing
### Manual Testing
```bash
# Test installer
./install.sh --help
./install.sh --skip-deps
dfd # Run health check
# Test new features
./zsh/functions/my-feature.zsh test
```
### Validation Checklist
- [ ] No errors in `shellcheck` (if available)
- [ ] Script runs without errors
- [ ] `dotfiles-doctor.sh` passes
- [ ] Feature works as documented
- [ ] No breaking changes for existing users
- [ ] Works on both Arch and CachyOS
- [ ] Tested with both bash and zsh
```bash
# Run shellcheck on modified scripts
shellcheck install.sh bin/*.sh zsh/functions/*.zsh
```
### Testing Across Arch/CachyOS
```bash
# Test on Arch Linux
# Test on CachyOS (if available)
# Test on fresh installation
# Test on system with existing dotfiles
# Verify:
# - Installation completes
# - All features work
# - No data loss
# - Can uninstall cleanly
```
---
## Submitting Changes
### Commit Messages
```bash
# Good commit message format
# First line: Brief summary (50 chars max)
# Blank line
# Detailed explanation (if needed)
git commit -m "Add fuzzy search to password manager
- Implement fzf integration for pw command
- Add pwf alias for quick password copy
- Update documentation with examples
- Tested on Arch and CachyOS"
```
### Commit Guidelines
- One logical change per commit
- Commit frequently
- Include related changes together
- Meaningful commit messages
### Before Submitting PR
```bash
# Sync with upstream
git fetch upstream
git rebase upstream/main
# Clean up commits
# (squash, reorder, reword as needed)
# Final validation
./install.sh --help
./install.sh --skip-deps
dotfiles-doctor.sh
```
### Pull Request Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Performance improvement
## Related Issues
Fixes #123
## Testing
- [ ] Tested on Arch Linux
- [ ] Tested on CachyOS
- [ ] All features work
- [ ] No regressions
## Checklist
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] Changes are tested
- [ ] No breaking changes
- [ ] Commits are clean
```
### PR Review Process
1. CI/automated checks pass
2. Code review (expect feedback)
3. Revisions made if needed
4. Final approval
5. Merge to main
---
## Architecture Overview
### Installation Flow
```
install.sh
├── Check OS (Arch/CachyOS only)
├── Load dotfiles.conf
├── Check dependencies
├── Install system packages
├── Create symlinks
├── Configure zsh
├── Initialize git config
└── Run post-install setup
```
### Module Structure
Each feature is mostly self-contained:
```
Feature: Password Manager
├── zsh/functions/password-manager.zsh # Core functions
├── bin/dotfiles-vault.sh # Supporting script
├── dotfiles.conf entries # Configuration
├── install.sh logic # Installation
└── docs/SETUP_GUIDE.md section # Documentation
```
### Configuration Hierarchy
```
install.sh (defaults)
↓
dotfiles.conf (user config)
↓
~/.zshrc (shell execution)
↓
~/.zshrc.local (machine-specific)
```
---
## Project Philosophy
### Design Principles
1. **Arch/CachyOS First** - Optimize for Arch/CachyOS, not other systems
2. **Simplicity** - Reduce complexity over time
3. **Single Tools** - One password manager, one editor, one shell
4. **User Customization** - Easy to customize without modification
5. **Documentation** - Features need good documentation
6. **Backward Compatibility** - Breaking changes discussed first
### What We Value
- ✅ Productivity
- ✅ Clarity
- ✅ Reliability
- ✅ Minimalism (not bloat)
- ✅ User autonomy
### What We Don't Value
- ❌ Supporting many OSes
- ❌ Supporting many tools
- ❌ Complex configuration
- ❌ Undocumented features
- ❌ Breaking user workflows
---
## Getting Help
### Questions
- Check [README.md](../README.md)
- Check [SETUP_GUIDE.md](SETUP_GUIDE.md)
- Check existing GitHub issues
- Ask in a new GitHub issue
### Feature Requests
1. Check if already requested (GitHub issues)
2. Describe use case clearly
3. Explain why it fits project scope
4. Include examples
### Bug Reports
1. Run `dotfiles-doctor.sh`
2. Include error output
3. Include OS and CachyOS/Arch version
4. Include steps to reproduce
5. Include expected vs actual behavior
---
## Recognition
Contributors are recognized in:
- GitHub Contributors page
- [CONTRIBUTORS.md](CONTRIBUTORS.md) file
- Release notes for significant changes
Thank you for contributing! 🙏
---
For more information:
- [README.md](../README.md)
- [SETUP_GUIDE.md](SETUP_GUIDE.md)
- [GitHub Issues](https://github.com/adlee-was-taken/dotfiles/issues)

384
docs/ESPANSO.md
View File

@@ -1,384 +0,0 @@
# Espanso Quick Reference
Text expansion with 100+ pre-configured snippets using `..trigger` syntax.
## Controls
| Action | Shortcut |
|--------|----------|
| Toggle on/off | `ALT+SHIFT+E` |
| Search snippets | `ALT+SPACE` |
| Restart | `espanso restart` |
| Status | `espanso status` |
| View logs | `espanso log` |
---
## Snippet Categories
### Date & Time
| 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 Commands
| Trigger | Output |
|---------|--------|
| `..gstat` | `git status` |
| `..gco` | `git checkout ` |
| `..gcm` | `git commit -m ""` |
| `..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 Commands
| Trigger | Output |
|---------|--------|
| `..dps` | `docker ps` |
| `..dpsa` | `docker ps -a` |
| `..dcup` | `docker-compose up -d` |
| `..dcdown` | `docker-compose down` |
| `..dlog` | `docker logs -f ` |
| `..dexec` | `docker exec -it ` |
| `..dim` | `docker images` |
| `..dprune` | `docker system prune -af` |
### System Info
| Trigger | Output |
|---------|--------|
| `..ip` | Public IP (via curl) |
| `..locip` | Local IP |
### Code Templates
| Trigger | Output |
|---------|--------|
| `..bash` | Bash script with shebang + `set -euo pipefail` |
| `..python` | Python script with main() |
| `..she!` | `#!/usr/bin/env bash` |
### Markdown
| Trigger | Output |
|---------|--------|
| `..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
| Trigger | Output |
|---------|--------|
| `..todo` | `// TODO: ` |
| `..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` |
### 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 |
|---------|--------|
| `..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 |
### Lorem Ipsum
| 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 |
|------|------------|
| teh | the |
| recieve | receive |
| definately | definitely |
| seperator | separator |
| occured | occurred |
| lenght | length |
| wierd | weird |
| thier | their |
---
## 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:
- trigger: "..hw"
replace: "Hello, World!"
```
### With Shell Command
```yaml
- trigger: "..uptime"
replace: "{{output}}"
vars:
- name: output
type: shell
params:
cmd: 'uptime -p'
```
### With Date Formatting
```yaml
- trigger: "..today"
replace: "Today is {{mydate}}"
vars:
- name: mydate
type: date
params:
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 Files
```
~/.config/espanso/ (symlinked to ~/.dotfiles/espanso/)
├── config/
│ └── default.yml # Global settings
└── match/
├── base.yml # Main snippets (100+)
├── personal.yml # Your personal info
└── packages/ # Installed packages
```
---
## Useful Commands
```bash
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
```
---
## 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`

396
docs/INDEX.md
View File

@@ -1,396 +0,0 @@
# Documentation Index
Complete guide to all documentation files for the ADLee dotfiles (Arch/CachyOS).
## 📚 Start Here
### For New Users
1. **[README.md](README.md)** - Feature overview and quick start (5-10 min read)
2. **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command lookup (2 min scan)
3. **[SETUP_GUIDE.md](SETUP_GUIDE.md)** - Installation and configuration (15-20 min read)
### For Existing Users
1. **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Fast command lookup
2. **[CHANGELOG.md](CHANGELOG.md)** - What's new in current version
3. **[SETUP_GUIDE.md](SETUP_GUIDE.md#configuration)** - Configuration section
### For Contributors
1. **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
2. **[CHANGELOG.md](CHANGELOG.md)** - Version history and architecture
3. **[README.md](README.md#-repository-layout)** - Repository structure
---
## 📖 All Documentation Files
### Core Documentation
#### [README.md](README.md) - **Main Documentation**
- Feature overview with examples
- Quick start instructions
- Repository structure
- Command reference (aliases)
- System requirements
- Configuration basics
- License information
**Read if:** You're new to the project
**Time:** 10-15 minutes
**Key sections:**
- ✨ Features table
- 🚀 Quick Start
- 📁 Repository Layout
- ⌨️ Command Aliases
#### [SETUP_GUIDE.md](SETUP_GUIDE.md) - **Installation & Configuration**
- Prerequisites and requirements
- Installation methods (wizard, one-liner, standard)
- Post-install setup checklist
- Configuration file reference
- Detailed feature guides
- Customization examples
- Multi-machine setup
- Troubleshooting guide
**Read if:** You're installing for the first time
**Time:** 20-30 minutes
**Key sections:**
- Installation Methods
- Post-Install Setup
- Configuration
- Features Guide
- Multi-Machine Setup
---
### Specialized Guides
#### [SSH_TMUX_INTEGRATION.md](SSH_TMUX_INTEGRATION.md) - **SSH & Tmux Workflows**
- SSH manager setup and commands
- Tmux workspace basics and templates
- SSH + Tmux integration
- Practical workflow examples
- Multi-server management
- Advanced features
- Troubleshooting
**Read if:** You manage servers or work with multiple machines
**Time:** 15-20 minutes
**Key sections:**
- SSH Manager Overview
- Tmux Workspace Basics
- SSH + Tmux Integration
- Workflow Examples
- Multi-Server Management
#### [SNAPPER.md](SNAPPER.md) - **Btrfs Snapshot Management**
- Installation and setup
- Basic snapshot commands
- Snapshot management (creation, deletion, cleanup)
- Limine boot menu integration
- Automated snapshots
- Recovery workflows
- Troubleshooting
**Read if:** You use Arch/CachyOS with Btrfs and Limine
**Time:** 15-20 minutes
**Key sections:**
- Installation
- Basic Commands
- Snapshot Management
- Limine Boot Menu Integration
- Recovery Workflows
#### [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - **Fast Lookup**
- All commands at a glance
- Keybindings reference
- Common tasks (quick snippets)
- Configuration examples
- System requirements
- Important paths
**Read if:** You need to quickly look up a command
**Time:** 2-5 minutes (reference guide)
**Use:** Ctrl+F to search
---
### Project Information
#### [CONTRIBUTING.md](CONTRIBUTING.md) - **How to Contribute**
- Code of conduct
- Development setup
- Making changes guidelines
- Coding standards
- Testing procedures
- Pull request process
- Architecture overview
- Project philosophy
**Read if:** You want to contribute to the project
**Time:** 15-20 minutes
**Key sections:**
- Getting Started
- Development Setup
- Making Changes
- Coding Standards
- Submitting Changes
#### [CHANGELOG.md](CHANGELOG.md) - **Version History**
- Current version (v3.0.0) - Major Arch/CachyOS focus update
- Breaking changes and migration paths
- Size reduction metrics
- What's preserved
- Upgrade instructions
- Version history
**Read if:** You want to understand what changed
**Time:** 10-15 minutes
**Key sections:**
- Breaking Changes (v3.0.0)
- Migration Paths
- Size Reduction
- What Still Works
---
## 🎯 Documentation by Use Case
### I want to...
#### Get Started
1. [README.md](README.md) - Overview
2. [SETUP_GUIDE.md](SETUP_GUIDE.md) - Installation
3. [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Command lookup
#### Manage Servers via SSH
1. [SSH_TMUX_INTEGRATION.md](SSH_TMUX_INTEGRATION.md) - Full guide
2. [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-ssh-management) - Quick commands
#### Use Snapshots for Recovery
1. [SNAPPER.md](SNAPPER.md) - Complete guide
2. [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-snapper-btrfs-snapshots) - Quick commands
#### Contribute Code
1. [CONTRIBUTING.md](CONTRIBUTING.md) - Full guidelines
2. [CHANGELOG.md](CHANGELOG.md) - Architecture and philosophy
#### Learn What's New
1. [CHANGELOG.md](CHANGELOG.md) - Version history
2. [SETUP_GUIDE.md](SETUP_GUIDE.md) - Updated features
#### Configure Dotfiles
1. [SETUP_GUIDE.md](SETUP_GUIDE.md#configuration) - Configuration section
2. [README.md](README.md#⚙️-configuration) - Config overview
3. [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-customization) - Examples
#### Find a Specific Command
1. [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - All commands
2. [README.md](README.md#⌨️-command-aliases) - Alias list
3. [SETUP_GUIDE.md](SETUP_GUIDE.md#features-guide) - Feature guides
#### Fix an Issue
1. [SETUP_GUIDE.md](SETUP_GUIDE.md#troubleshooting) - General troubleshooting
2. Relevant specialized guide:
- [SSH_TMUX_INTEGRATION.md](SSH_TMUX_INTEGRATION.md#troubleshooting) - SSH issues
- [SNAPPER.md](SNAPPER.md#troubleshooting) - Snapper issues
3. [CONTRIBUTING.md](CONTRIBUTING.md#getting-help) - Getting help
---
## 📊 Documentation Statistics
| Document | Lines | Read Time | Type |
|----------|-------|-----------|------|
| README.md | 450 | 12 min | Overview |
| SETUP_GUIDE.md | 550 | 18 min | Detailed guide |
| SSH_TMUX_INTEGRATION.md | 500 | 15 min | Feature guide |
| SNAPPER.md | 480 | 15 min | Feature guide |
| CONTRIBUTING.md | 420 | 15 min | Guidelines |
| CHANGELOG.md | 350 | 12 min | Reference |
| QUICK_REFERENCE.md | 350 | 8 min | Reference |
| **Total** | **3,100** | **95 min** | |
**Tip:** You don't need to read everything! Use the index above to find what's relevant to you.
---
## 🔄 Reading Paths by Experience Level
### Beginner (Never Used Dotfiles)
```
1. README.md (10 min)
↓
2. SETUP_GUIDE.md - "Installation Methods" section (10 min)
↓
3. SETUP_GUIDE.md - "Post-Install Setup" section (5 min)
↓
4. QUICK_REFERENCE.md for command lookup (ongoing)
```
### Intermediate (Familiar with Dotfiles)
```
1. CHANGELOG.md - What's new (5 min)
↓
2. README.md - Features section (5 min)
↓
3. Relevant specialty guide based on use case (15 min)
↓
4. QUICK_REFERENCE.md for command lookup (ongoing)
```
### Advanced (Contributing or Deep Customization)
```
1. CHANGELOG.md - Architecture section (10 min)
↓
2. CONTRIBUTING.md - Full guide (20 min)
↓
3. SETUP_GUIDE.md - Customization section (10 min)
↓
4. Source code review as needed
```
---
## 🔍 Quick Lookup by Topic
### Installation & Setup
- Main guide: [SETUP_GUIDE.md](SETUP_GUIDE.md)
- Quick start: [README.md](README.md#-quick-start)
- Troubleshooting: [SETUP_GUIDE.md](SETUP_GUIDE.md#troubleshooting)
### Features
- Overview: [README.md](README.md#-features)
- Detailed: [SETUP_GUIDE.md](SETUP_GUIDE.md#features-guide)
- Commands: [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
### Configuration
- Options: [SETUP_GUIDE.md](SETUP_GUIDE.md#configuration)
- Examples: [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-customization)
### SSH & Servers
- Complete guide: [SSH_TMUX_INTEGRATION.md](SSH_TMUX_INTEGRATION.md)
- Quick commands: [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-ssh-management)
### Snapshots & Recovery
- Complete guide: [SNAPPER.md](SNAPPER.md)
- Quick commands: [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-snapper-btrfs-snapshots)
- Recovery: [SNAPPER.md](SNAPPER.md#recovery-workflows)
### Tmux & Workspaces
- Complete guide: [SSH_TMUX_INTEGRATION.md](SSH_TMUX_INTEGRATION.md#tmux-workspace-basics)
- Quick commands: [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-tmux-workspace-manager)
### Password Manager
- Guide: [SETUP_GUIDE.md](SETUP_GUIDE.md#lastpass-integration)
- Quick commands: [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-password-manager-lastpass)
### Customization
- Guide: [SETUP_GUIDE.md](SETUP_GUIDE.md#customization)
- Examples: [QUICK_REFERENCE.md](QUICK_REFERENCE.md#-customization)
### Contributing
- Full guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Architecture: [CONTRIBUTING.md](CONTRIBUTING.md#architecture-overview)
- Coding standards: [CONTRIBUTING.md](CONTRIBUTING.md#coding-standards)
### Version History
- Full history: [CHANGELOG.md](CHANGELOG.md)
- Breaking changes: [CHANGELOG.md](CHANGELOG.md#-removed-breaking-changes)
- Migration: [CHANGELOG.md](CHANGELOG.md#-migration-paths)
---
## 📝 File Organization
```
Documentation/
├── README.md # Main entry point
├── SETUP_GUIDE.md # Installation & configuration
├── QUICK_REFERENCE.md # Command lookup
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── SSH_TMUX_INTEGRATION.md # SSH & Tmux guide
├── SNAPPER.md # Snapshot management
└── docs/
└── INDEX.md # This file
```
---
## 🆘 Getting Help
### Common Questions
**Q: How do I install?**
A: See [SETUP_GUIDE.md](SETUP_GUIDE.md#installation-methods)
**Q: What commands are available?**
A: See [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
**Q: How do I fix issues?**
A: See troubleshooting section in relevant guide or [SETUP_GUIDE.md](SETUP_GUIDE.md#troubleshooting)
**Q: How do I contribute?**
A: See [CONTRIBUTING.md](CONTRIBUTING.md)
**Q: What changed in the latest version?**
A: See [CHANGELOG.md](CHANGELOG.md)
**Q: How do I manage SSH connections?**
A: See [SSH_TMUX_INTEGRATION.md](SSH_TMUX_INTEGRATION.md)
**Q: How do I use Snapper?**
A: See [SNAPPER.md](SNAPPER.md)
### Resources
- **GitHub Issues:** Report bugs or request features
- **GitHub Discussions:** Ask questions and share ideas
- **GitHub Wiki:** Community tips and tricks (if enabled)
---
## 🔄 Document Maintenance
### Last Updated
- README.md - 2025-12-21
- SETUP_GUIDE.md - 2025-12-21
- SSH_TMUX_INTEGRATION.md - 2025-12-21
- SNAPPER.md - 2025-12-21
- CONTRIBUTING.md - 2025-12-21
- CHANGELOG.md - 2025-12-21
- QUICK_REFERENCE.md - 2025-12-21
### Version
All documentation is current for **v3.0.0** (Arch/CachyOS only)
### Feedback
Found an error or want to improve docs? [Contribute via CONTRIBUTING.md](CONTRIBUTING.md)
---
## 📚 Related Resources
### External Documentation
- [Arch Linux Wiki](https://wiki.archlinux.org/)
- [Zsh Documentation](http://zsh.sourceforge.net/Doc/)
- [Tmux Manual](https://man7.org/linux/man-pages/man1/tmux.1.html)
- [Vim Documentation](https://www.vim.org/docs.php)
### Community
- [Arch Linux Forums](https://bbs.archlinux.org/)
- [Arch Linux IRC](https://wiki.archlinux.org/title/IRC_channels)
- [Zsh Community](https://www.zsh.org/)
---
**Quick Navigation:**
- [README.md](README.md) - Start here
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Command lookup
- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Installation guide
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribute
---
*Last updated: 2025-12-21 for v3.0.0*

401
docs/QUICK_REFERENCE.md
View File

@@ -1,401 +0,0 @@
# Quick Reference
Fast lookup for common dotfiles commands and features.
## 🚀 Quick Start
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard
```
---
## 📋 Core Commands
### Installation & Management
| Command | Purpose |
|---------|---------|
| `./install.sh` | Standard install |
| `./install.sh --wizard` | Interactive TUI wizard |
| `./install.sh --skip-deps` | Reinstall without checking deps |
| `./install.sh --uninstall` | Remove symlinks |
| `dotfiles-doctor.sh` | Health check |
| `dotfiles-doctor.sh --fix` | Auto-fix issues |
| `dfd` | Alias for health check |
### Updates
| Command | Purpose |
|---------|---------|
| `dotfiles-update.sh` | Update dotfiles |
| `dotfiles-sync.sh` | Sync across machines |
| `dfpush` | Push local changes |
| `dfpull` | Pull remote changes |
| `dfstatus` | Check sync status |
### Info
| Command | Purpose |
|---------|---------|
| `dotfiles-version.sh` | Show version |
| `dfv` | Alias for version |
---
## 🎯 Command Palette
**Trigger:** `Ctrl+Space` or `Ctrl+P`
Searches: aliases, functions, recent commands, bookmarks, git commands, dotfiles scripts
**Keybindings:**
- `Enter` - Execute
- `Ctrl+E` - Edit before running
- `Ctrl+Y` - Copy to clipboard
---
## 🔑 Password Manager (LastPass)
```bash
pw list # List all items
pw get github # Get password
pw get github username # Get specific field
pw otp github # Get TOTP code
pw copy aws # Copy to clipboard
pw search mail # Search items
pwf # Fuzzy search + copy
pwof # Fuzzy search + copy OTP
pw lock # Logout
```
---
## 📁 Directory Bookmarks
```bash
bookmark <n> [path] # Save bookmark (default: current dir)
bookmark list # List all
bookmark delete <n> # Delete
jump <n> # Go to bookmark
j # Fuzzy select
```
---
## 🔐 Secrets Vault
```bash
vault set KEY "value" # Store (or prompt for value)
vault get KEY # Retrieve
vault list # List all keys
vault delete KEY # Remove
vault shell # Print as export statements
vault export backup.enc # Backup
vault import backup.enc # Restore
```
---
## 📊 Shell Analytics
```bash
dotfiles-stats.sh # Full dashboard
dfstats # Alias for full
stats # Another alias
dotfiles-stats.sh --top 20 # Top 20 commands
dotfiles-stats.sh --suggest # Alias suggestions
```
---
## 📸 Snapper (Btrfs Snapshots)
```bash
snap-create "Description" # Create snapshot
snap-list # Show snapshots
snap-list 20 # Show last 20
snap-show 42 # Show details
snap-delete 42 # Delete
snap-check-limine # Verify boot menu
snap-sync # Manual sync
snap-info # Detailed breakdown
```
---
## 🌐 SSH Management
```bash
ssh-save <n> <conn> # Save profile
ssh-list # List profiles
ssh-connect <n> # Connect (auto-tmux)
sshf # Fuzzy search + connect
ssh-delete <n> # Delete
ssh-sync-dotfiles <n> # Deploy dotfiles to remote
ssh-reconnect # Quick reconnect
```
---
## 🎪 Tmux Workspace Manager
```bash
tw <n> # Quick attach/create
tw-create <n> [tmpl] # Create with template
tw-list # List workspaces
tw-delete <n> # Delete
tw-save <n> # Save as template
tw-sync # Toggle pane sync
twf # Fuzzy select
tw-templates # List available templates
```
**Templates:**
- `dev` - vim (50%) + terminal (25%) + logs (25%)
- `ops` - 4-pane monitoring grid
- `ssh-multi` - 4 synchronized panes
- `debug` - main (70%) + helper (30%)
- `full` - Single fullscreen
- `review` - Side-by-side comparison
---
## ⚡ Aliases (All Commands)
| Alias | Command | Purpose |
|-------|---------|---------|
| `dfd` | `dotfiles-doctor.sh` | Health check |
| `dffix` | `dotfiles-doctor.sh --fix` | Auto-fix |
| `dfs` | `dotfiles-sync.sh` | Sync |
| `dfpush` | `dotfiles-sync.sh --push` | Push |
| `dfpull` | `dotfiles-sync.sh --pull` | Pull |
| `dfu` | `dotfiles-update.sh` | Update |
| `dfv` | `dotfiles-version.sh` | Version |
| `dfstats` | `dotfiles-stats.sh` | Analytics |
| `stats` | `dotfiles-stats.sh` | Analytics |
| `pw` | LastPass manager | Password lookup |
| `pwf` | LastPass fuzzy | Fuzzy password |
| `vault` | `dotfiles-vault.sh` | Secrets |
| `vls` | `vault list` | List secrets |
| `reload` | `source ~/.zshrc` | Reload shell |
| `j` | Fuzzy bookmark | Jump to bookmark |
| `tw` | Tmux workspace | Quick workspace |
| `twf` | Fuzzy tmux | Fuzzy workspace |
| `sshf` | Fuzzy SSH | Fuzzy SSH connect |
---
## 🎨 Customization
**Main config file:** `~/.dotfiles/dotfiles.conf`
**Machine-specific config:** `~/.zshrc.local` (not tracked)
**Text snippets:** `~/.dotfiles/espanso/match/personal.yml`
**Theme:** `~/.dotfiles/zsh/themes/adlee.zsh-theme`
---
## 📚 Common Tasks
### Create Dev Project
```bash
tw-create myproject dev # Create workspace
pw get github # Get credentials
git clone <repo>
```
### Monitor Multiple Servers
```bash
ssh-save web1 user@web1.com
ssh-save web2 user@web2.com
tw-create monitoring ops # 4-pane grid
ssh-connect web1 # In pane 1
ssh-connect web2 # In pane 2
tw-sync # Enable sync
```
### System Backup Before Update
```bash
snap-create "Before pacman update"
sudo pacman -Syu
snap-create "After pacman update"
```
### Recover Lost File
```bash
snap-list # Find relevant snapshot
snap-show 42 # Check timestamp
sudo mount -t btrfs -o subvol=@/.snapshots/42/snapshot /dev/device /mnt/snap
cp /mnt/snap/path/to/file ~/
sudo umount /mnt/snap
```
### Sync Dotfiles to Remote
```bash
ssh-save prod user@prod.com
ssh-sync-dotfiles prod
```
### Fuzzy Find and Execute
```bash
Ctrl+Space # Open command palette
git # Type partial
```
---
## 🔧 Configuration Examples
### Change Default Theme
Edit `~/.dotfiles/dotfiles.conf`:
```bash
ZSH_THEME="adlee" # Already default
```
### Enable More Features
Edit `~/.dotfiles/dotfiles.conf`:
```bash
INSTALL_NEOVIM="true" # Auto-install neovim
INSTALL_FZF="true" # Auto-install fzf
ENABLE_VAULT="true" # Enable secrets
```
### Add Custom Alias
Edit `~/.dotfiles/zsh/aliases.zsh`:
```bash
alias projects='cd ~/projects'
alias k='kubectl'
```
### Machine-Specific Config
Create `~/.zshrc.local`:
```bash
export WORK_EMAIL="me@work.com"
alias vpn='wg-quick up work-vpn'
```
---
## 🆘 Troubleshooting
### Health Check
```bash
dotfiles-doctor.sh
# or
dfd
```
### Reset Zsh
```bash
./install.sh --skip-deps
source ~/.zshrc
```
### Check Version
```bash
dotfiles-version.sh
# or
dfv
```
### View Logs
```bash
dotfiles-doctor.sh --verbose
```
---
## 🎯 Zsh Keybindings
| Key | Action |
|-----|--------|
| `Tab` | Autocomplete |
| `Ctrl+Space` | Command palette |
| `Ctrl+P` | Command palette (alt) |
| `Ctrl+B, C` | New tmux window |
| `Ctrl+B, D` | Detach tmux |
| `Ctrl+L` | Clear screen |
| `Ctrl+U` | Clear line |
| `Ctrl+R` | Search history |
| `Ctrl+A` | Start of line |
| `Ctrl+E` | End of line |
---
## 📦 System Requirements
- **OS:** Arch Linux or CachyOS
- **Shell:** Zsh (auto-installed)
- **Editor:** Vim (required)
- **Optional:** Neovim, LastPass CLI, fzf, bat, eza
- **Bootloader:** Limine (for Snapper)
---
## 🔗 Important Paths
| Path | Purpose |
|------|---------|
| `~/.dotfiles` | Main dotfiles directory |
| `~/.dotfiles/dotfiles.conf` | Main configuration |
| `~/.dotfiles/zsh/functions/` | Shell functions |
| `~/.dotfiles/bin/` | Utility scripts |
| `~/.zshrc.local` | Machine-specific config |
| `~/.dotfiles_backup_*` | Backup of original files |
| `~/.ssh/config` | SSH profiles (generated) |
---
## 📖 Full Documentation
- [README.md](README.md) - Full feature overview
- [SETUP_GUIDE.md](docs/SETUP_GUIDE.md) - Installation and setup
- [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) - SSH and Tmux
- [SNAPPER.md](docs/SNAPPER.md) - Snapshot management
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributing guidelines
- [CHANGELOG.md](CHANGELOG.md) - Version history
---
## 💡 Tips
1. **Reload Shell** - Changes to zsh config:
```bash
reload
# or
source ~/.zshrc
```
2. **Test Commands** - Before committing in tmux:
```bash
command --help
man command
```
3. **Fuzzy Everything** - Most dotfiles tools work with fzf:
```bash
pwf # Fuzzy password
sshf # Fuzzy SSH
twf # Fuzzy tmux
```
4. **Check Health Regularly**:
```bash
dfd # Weekly health check
```
5. **Keep Vault Safe**:
```bash
vault list
vault export ~/backup.enc
# Store backup.enc safely
```
---
**Last Updated:** 2025-12-21
**Version:** 3.0.0
**Platform:** Arch/CachyOS

608
docs/REFERENCE.md Normal file
View File

@@ -0,0 +1,608 @@
# Reference Guide
Complete reference for ADLee's Dotfiles configuration, Espanso triggers, and advanced features.
## Table of Contents
- [Configuration Reference](#configuration-reference)
- [Espanso Triggers](#espanso-triggers)
- [Vim Configuration](#vim-configuration)
- [Tmux Configuration](#tmux-configuration)
- [Git Aliases](#git-aliases)
- [Function Files Reference](#function-files-reference)
- [Color Reference](#color-reference)
---
## Configuration Reference
### dotfiles.conf Options
Complete list of all configuration options in `~/.dotfiles/dotfiles.conf`:
#### Core Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `DOTFILES_VERSION` | `"1.2.0"` | Dotfiles version |
| `DOTFILES_DIR` | `"$HOME/.dotfiles"` | Installation directory |
| `DOTFILES_BRANCH` | `"main"` | Git branch to use |
| `DOTFILES_BACKUP_PREFIX` | `"$HOME/.dotfiles_backup"` | Backup location prefix |
#### GitHub Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `DOTFILES_GITHUB_USER` | `"adlee-was-taken"` | GitHub username |
| `DOTFILES_REPO_NAME` | `"dotfiles"` | Repository name |
#### User Identity
| Variable | Default | Description |
|----------|---------|-------------|
| `USER_FULLNAME` | `""` | Your full name |
| `USER_EMAIL` | `""` | Your email |
| `USER_GITHUB` | `""` | Your GitHub username |
#### Git Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `GIT_USER_NAME` | `""` | Git user.name (falls back to USER_FULLNAME) |
| `GIT_USER_EMAIL` | `""` | Git user.email (falls back to USER_EMAIL) |
| `GIT_DEFAULT_BRANCH` | `"main"` | Default branch name |
#### Feature Toggles
| Variable | Values | Description |
|----------|--------|-------------|
| `INSTALL_DEPS` | `auto/true/false` | Install dependencies |
| `INSTALL_ZSH_PLUGINS` | `true/false` | Install zsh plugins |
| `INSTALL_FZF` | `true/false/ask` | Install fzf |
| `INSTALL_BAT` | `true/false/ask` | Install bat |
| `INSTALL_EZA` | `true/false/ask` | Install eza |
| `INSTALL_NEOVIM` | `true/false/ask` | Install neovim |
| `SET_ZSH_DEFAULT` | `true/false/ask` | Set zsh as default shell |
#### MOTD Settings
| Variable | Values | Description |
|----------|--------|-------------|
| `ENABLE_MOTD` | `true/false` | Enable MOTD display |
| `MOTD_STYLE` | `compact/mini/full/none` | MOTD display style |
| `MOTD_SHOW_FAILED_SERVICES` | `true/false` | Show failed systemd services |
| `MOTD_SHOW_UPDATES` | `true/false` | Show available updates |
#### Theme Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `ZSH_THEME_NAME` | `"adlee"` | Zsh theme name |
| `THEME_TIMER_THRESHOLD` | `10` | Seconds before showing timer |
| `THEME_PATH_TRUNCATE_LENGTH` | `32` | Max path display length |
#### Advanced Features
| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_SMART_SUGGESTIONS` | `true` | Enable typo correction |
| `ENABLE_COMMAND_PALETTE` | `true` | Enable Ctrl+Space palette |
| `ENABLE_SHELL_ANALYTICS` | `false` | Command usage tracking |
| `ENABLE_VAULT` | `true` | Enable secrets vault |
| `DOTFILES_AUTO_SYNC_CHECK` | `true` | Check for updates on start |
#### Btrfs Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `BTRFS_DEFAULT_MOUNT` | `"/"` | Default mount for btrfs commands |
#### Snapper Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `SNAPPER_CONFIG` | `"root"` | Snapper config name |
| `LIMINE_CONF` | `"/boot/limine.conf"` | Limine config path |
#### Tmux Workspace Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `TW_SESSION_PREFIX` | `"work"` | Session naming prefix |
| `TW_DEFAULT_TEMPLATE` | `"dev"` | Default workspace template |
#### Python Template Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `PY_TEMPLATE_BASE_DIR` | `"$HOME/projects"` | Project base directory |
| `PY_TEMPLATE_PYTHON` | `"python3"` | Python executable |
| `PY_TEMPLATE_VENV_NAME` | `"venv"` | Virtual env directory name |
| `PY_TEMPLATE_USE_POETRY` | `false` | Use poetry instead of venv |
| `PY_TEMPLATE_GIT_INIT` | `true` | Initialize git repo |
#### SSH Manager Settings
| Variable | Default | Description |
|----------|---------|-------------|
| `SSH_AUTO_TMUX` | `true` | Auto-create tmux session |
| `SSH_TMUX_SESSION_PREFIX` | `"ssh"` | Session naming prefix |
| `SSH_SYNC_DOTFILES` | `ask` | Sync dotfiles on connect |
#### Package Manager
| Variable | Values | Description |
|----------|--------|-------------|
| `AUR_HELPER` | `auto/paru/yay` | Preferred AUR helper |
---
## Espanso Triggers
Complete list of text expansion triggers.
### Date and Time
| Trigger | Output | Example |
|---------|--------|---------|
| `..date` | Date (YYYY-MM-DD) | `2025-12-24` |
| `..ds` | Same as `..date` | `2025-12-24` |
| `..sds` | Short date (YYYYMMDD) | `20251224` |
| `..time` | Time (HH:MM:SS) | `14:30:45` |
| `..utime` | UTC time | `19:30:45` |
| `..ztime` | Time with timezone | `14:30:45.123 EST` |
| `..uztime` | UTC time with timezone | `19:30:45.123 UTC` |
| `..dt` | Date + time | `2025-12-24 14:30:45 EST` |
| `..udt` | UTC date + time | `2025-12-24 19:30:45 UTC` |
| `..ts` | ISO 8601 timestamp | `2025-12-24T19:30:45.123Z` |
| `..utc` | UTC with milliseconds | `2025-12-24 19:30:45.123 UTC` |
| `..month` | Month name | `December` |
| `..year` | Year | `2025` |
| `..week` | Week number | `Week 52` |
| `..day` | Day of week | `Wednesday` |
| `..epoch` | Unix timestamp | `1735066245` |
| `..epochms` | Unix timestamp (ms) | `1735066245123` |
### Quick Text
| 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 |
### System Information
| Trigger | Output |
|---------|--------|
| `..ip` | Public IP address |
| `..locip` | Local IP address |
| `..branch` | Current git branch |
### Git Commands
| Trigger | Output |
|---------|--------|
| `..gstat` | `git status` |
| `..gco` | `git checkout ` |
| `..gcm` | `git commit -m ""` |
| `..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 .` |
### Docker Commands
| Trigger | Output |
|---------|--------|
| `..dps` | `docker ps` |
| `..dpsa` | `docker ps -a` |
| `..dcup` | `docker-compose up -d` |
| `..dcdown` | `docker-compose down` |
| `..dlog` | `docker logs -f ` |
| `..dexec` | `docker exec -it ` |
| `..dim` | `docker images` |
| `..dprune` | `docker system prune -af` |
### Code Templates
| Trigger | Output |
|---------|--------|
| `..bash` | Bash shebang + `set -euo pipefail` |
| `..python` | Python main boilerplate |
| `..she!` | `#!/usr/bin/env bash` |
### Markdown
| Trigger | Output |
|---------|--------|
| `..mdcode` | Code block (generic) |
| `..mdbash` | Bash code block |
| `..mdpy` | Python code block |
| `..mdjs` | JavaScript code block |
| `..mdtable` | Markdown table template |
| `..mdlink` | `[text](url)` (prompts) |
| `..mdimg` | `![alt](url)` (prompts) |
### Programming Comments
| Trigger | Output |
|---------|--------|
| `..todo` | `// TODO: ` |
| `..fixme` | `// FIXME: ` |
| `..note` | `// NOTE: ` |
| `..hack` | `// HACK: ` |
| `..debug` | `// DEBUG: ` |
### Common 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` |
### 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` |
### Lorem Ipsum
| Trigger | Output |
|---------|--------|
| `..lorem` | One paragraph |
| `..loremlong` | Four paragraphs |
### Clipboard
| Trigger | Output |
|---------|--------|
| `..qp` | Primary clipboard (X11 selection) |
### Typo Corrections
| Trigger | Correction |
|---------|------------|
| `teh` | the |
| `recieve` | receive |
| `seperator` | separator |
| `definately` | definitely |
| `occured` | occurred |
| `lenght` | length |
| `wierd` | weird |
| `thier` | their |
### Emoji Package
| Trigger | Emoji |
|---------|-------|
| `:lol` | 😂 |
| `:sad` | ☹ |
| `:sml` | 😊 |
| `:strong` | 💪 |
| `:ba` | 😎 |
| `:ok` | 👍 |
| `:happy` | 😄 |
| `:cry` | 😭 |
| `:wow` | 😮 |
### Personal (in personal.yml)
| Trigger | Output |
|---------|--------|
| `..myemail` | Your email |
| `..myname` | Your full name |
| `..myphone` | Your phone |
| `..myweb` | Your website |
| `..mygithub` | Your GitHub URL |
| `..sig` | Email signature |
| `..sigfull` | Full signature |
| `..myaddr` | Your address |
| `..workemail` | Work email |
| `..worksig` | Work signature |
---
## Vim Configuration
### Leader Key
The leader key is `,` (comma).
### Key Mappings
| Mapping | Action |
|---------|--------|
| `,w` | Fast save (`:w!`) |
| `:W` | Sudo save |
| `Space` | Search (`/`) |
| `Ctrl+Space` | Backward search (`?`) |
| `,<Enter>` | Disable search highlight |
| `Ctrl+j/k/h/l` | Move between windows |
| `,bd` | Close buffer |
| `,ba` | Close all buffers |
| `,l` / `,h` | Next/previous buffer |
| `,tn` | New tab |
| `,to` | Tab only |
| `,tc` | Close tab |
| `,tm` | Move tab |
| `,tl` | Toggle last tab |
| `,te` | Open tab with buffer's path |
| `,cd` | Switch CWD to buffer dir |
| `Alt+j/k` | Move line down/up |
| `,ss` | Toggle spell checking |
| `,sn` / `,sp` | Next/previous misspelling |
| `,sa` | Add to dictionary |
| `,s?` | Suggest corrections |
| `,pp` | Toggle paste mode |
| `,q` | Open scratch buffer |
| `,x` | Open markdown buffer |
| `0` | First non-blank character |
### Settings
- 4 spaces for indentation
- Tabs expanded to spaces
- Smart indentation
- Line wrapping on word boundaries
- Incremental search with highlighting
- Wild menu for command completion
---
## Tmux Configuration
### Key Bindings
| Binding | Action |
|---------|--------|
| `Prefix + U` | Resize pane up 8 lines |
| `Prefix + D` | Resize pane down 8 lines |
| `Prefix + L` | Resize pane left 8 chars |
| `Prefix + R` | Resize pane right 8 chars |
### Settings
- Default shell: `/usr/bin/zsh`
- Terminal: `tmux-256color`
- XTerm keys enabled
- Escape time: 0 (no delay)
- Pane border status: bottom
---
## Git Aliases
Built-in git aliases from `.gitconfig`:
| Alias | Command |
|-------|---------|
| `git st` | `git status` |
| `git co` | `git checkout` |
| `git br` | `git branch` |
| `git ci` | `git commit` |
| `git lg` | `git log --oneline --graph --decorate --all` |
| `git unstage` | `git reset HEAD --` |
| `git last` | `git log -1 HEAD` |
| `git visual` | `gitk` |
---
## Function Files Reference
### btrfs-helpers.zsh
Btrfs filesystem management utilities.
**Exported functions:** `btrfs-usage`, `btrfs-subs`, `btrfs-balance`, `btrfs-balance-status`, `btrfs-balance-cancel`, `btrfs-scrub`, `btrfs-scrub-status`, `btrfs-scrub-cancel`, `btrfs-defrag`, `btrfs-compress`, `btrfs-info`, `btrfs-health`, `btrfs-snap-usage`, `btrfs-maintain`, `btrfs-help`
**Aliases:** `btru`, `btrs`, `btrh`, `btri`, `btrc`
### command-palette.zsh
Fuzzy command launcher.
**Exported functions:** `command_palette`, `palette`, `p`, `bookmark`, `bm`, `jump`, `j`
**Key bindings:** `Ctrl+Space`, `Ctrl+P`
### motd.zsh
Message of the Day display.
**Exported functions:** `show_motd`, `show_motd_mini`, `show_motd_full`, `sysbrief`
**Aliases:** `motd`, `motd-mini`, `motd-full`
### password-manager.zsh
LastPass CLI integration.
**Exported functions:** `pw`, `pwf`, `pwof`
**Aliases:** `pwl`, `pwg`, `pwc`, `pws`
### python-templates.zsh
Python project scaffolding.
**Exported functions:** `py-new`, `py-django`, `py-flask`, `py-fastapi`, `py-data`, `py-cli`, `venv`
**Aliases:** `pynew`, `pydjango`, `pyflask`, `pyfast`, `pydata`, `pycli`
### smart-suggest.zsh
Typo correction and suggestions.
**Exported functions:** `command_not_found_handler`, `fuck`
### snapper.zsh
Btrfs snapshot management.
**Exported functions:** `snap-create`, `snap-list`, `snap-show`, `snap-delete`, `snap-check-limine`, `snap-sync`, `snap-validate-service`
**Aliases:** `snap`, `snapls`, `snaprm`, `snapshow`, `snapcheck`, `snapsync`
### ssh-manager.zsh
SSH profile management.
**Exported functions:** `ssh-save`, `ssh-list`, `ssh-connect`, `ssh-delete`, `ssh-reconnect`, `ssh-sync-dotfiles`, `sshf`
**Aliases:** `sshl`, `sshs`, `sshc`, `sshd`, `sshr`, `sshsync`
### systemd-helpers.zsh
Systemd service management.
**Exported functions:** `sc`, `scu`, `scr`, `sce`, `scd`, `sclog`, `sclogs`, `sc-failed`, `sc-timers`, `sc-recent`, `sc-boot`, `sc-search`, `sc-info`, `scf`, `sclogf`, `sc-help`
**Aliases:** `scs`, `scstart`, `scstop`, `screload`, `scmask`, `scunmask`, `jctl`, `jctlf`, `jctlb`, `jctlerr`
### tmux-workspaces.zsh
Tmux workspace management.
**Exported functions:** `tw`, `tw-create`, `tw-attach`, `tw-list`, `tw-delete`, `tw-save`, `tw-templates`, `tw-template-edit`, `tw-sync`, `tw-rename`, `twf`
**Aliases:** `twl`, `twc`, `twa`, `twd`, `tws`, `twt`, `twe`
---
## Color Reference
Color variables defined in `zsh/lib/colors.zsh`:
### Standard Colors
| Variable | Description |
|----------|-------------|
| `DF_RED` | Red |
| `DF_GREEN` | Green |
| `DF_YELLOW` | Yellow (bold) |
| `DF_BLUE` | Blue |
| `DF_MAGENTA` | Magenta |
| `DF_CYAN` | Cyan |
| `DF_WHITE` | White |
### Bold Variants
`DF_BOLD_RED`, `DF_BOLD_GREEN`, `DF_BOLD_YELLOW`, `DF_BOLD_BLUE`, `DF_BOLD_MAGENTA`, `DF_BOLD_CYAN`, `DF_BOLD_WHITE`
### Text Styles
| Variable | Description |
|----------|-------------|
| `DF_BOLD` | Bold text |
| `DF_DIM` | Dim/faint text |
| `DF_ITALIC` | Italic text |
| `DF_UNDERLINE` | Underlined text |
| `DF_RESET` / `DF_NC` | Reset formatting |
### 256-Color Palette
| Variable | Description |
|----------|-------------|
| `DF_GREY` | Grey (242) |
| `DF_LIGHT_GREY` | Light grey (248) |
| `DF_DARK_GREY` | Dark grey (239) |
| `DF_ORANGE` | Orange (208) |
| `DF_LIGHT_ORANGE` | Light orange (220) |
| `DF_PINK` | Pink (213) |
| `DF_PURPLE` | Purple (141) |
| `DF_LIGHT_BLUE` | Light blue (39) |
| `DF_LIGHT_GREEN` | Light green (82) |
| `DF_BRIGHT_GREEN` | Bright green (118) |
| `DF_TEAL` | Teal (51) |
### Semantic Colors
| Variable | Maps To |
|----------|---------|
| `DF_SUCCESS` | `DF_GREEN` |
| `DF_ERROR` | `DF_RED` |
| `DF_WARNING` | `DF_YELLOW` |
| `DF_INFO` | `DF_CYAN` |
| `DF_HINT` | `DF_DIM` |
| `DF_ACCENT` | `DF_BLUE` |
| `DF_MUTED` | `DF_GREY` |
### Print Functions
| Function | Description |
|----------|-------------|
| `df_print_step "msg"` | Print step with `==>` prefix |
| `df_print_success "msg"` | Print with ✓ prefix |
| `df_print_error "msg"` | Print with ✗ prefix (stderr) |
| `df_print_warning "msg"` | Print with ⚠ prefix |
| `df_print_info "msg"` | Print with ℹ prefix |
| `df_print_section "title"` | Print section divider |
| `df_print_header "name"` | Print MOTD-style header box |
### Usage in Scripts
```bash
# In bash scripts
source "$HOME/.dotfiles/zsh/lib/colors.zsh"
echo -e "${DF_GREEN}Success!${DF_NC}"
# In zsh functions
source "${0:A:h}/../lib/colors.zsh"
df_print_success "Operation completed"
```
---
## Environment Variables
These are set or used by the dotfiles:
| Variable | Description |
|----------|-------------|
| `DOTFILES_DIR` | Dotfiles installation path |
| `UPDATE_PKG_COUNT` | Available package updates (for prompt) |
| `EDITOR` | Default editor (vim) |
| `VISUAL` | Visual editor (vim) |
| `LANG` / `LC_ALL` | Locale (en_US.UTF-8) |
| `FZF_DEFAULT_OPTS` | FZF appearance settings |
| `FZF_DEFAULT_COMMAND` | FZF file finder command |

661
docs/SETUP_GUIDE.md
View File

@@ -1,661 +0,0 @@
# Setup Guide
Complete guide for installing, configuring, and maintaining your Arch/CachyOS 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:**
- Arch Linux or CachyOS
- Git
- Curl
- Pacman (built-in)
**Optional (for full features):**
- `fzf` - For command palette and fuzzy finding
- `age` or `gpg` - For secrets vault
- `lastpass-cli` - For password manager integration
- `nvim` - For Neovim support (Vim is sufficient)
---
## 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
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh
```
### Method 3: Standard Install
Clone and run with prompts:
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```
### Install Options
```bash
./install.sh # Interactive install
./install.sh --wizard # TUI wizard
./install.sh --skip-deps # Skip dependency installation
./install.sh --deps-only # Only install dependencies, then exit
./install.sh --uninstall # Remove symlinks
./install.sh --uninstall --purge # Remove everything
./install.sh --help # Show all options
```
---
## Post-Install Setup
### 1. Verify Installation
```bash
dotfiles-doctor.sh
```
This checks:
- All symlinks are valid
- Zsh plugins installed
- Git configured
- Theme loaded
- Optional tools present
Fix issues automatically:
```bash
dotfiles-doctor.sh --fix
```
### 2. Restart Shell
```bash
exec zsh
# or just close and reopen your terminal
```
### 3. Configure LastPass (Optional)
```bash
pw list
# First run will prompt you to login
# Enter your LastPass email and master password
```
### 4. Set Up Secrets Vault (Optional)
```bash
vault init
vault set GITHUB_TOKEN "your-token-here"
vault list
```
### 5. Configure Directory Bookmarks (Optional)
```bash
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"
# ============================================================================
# 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_NEOVIM="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
```
---
## 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
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
```
### 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
dotfiles-stats.sh # Full dashboard
dotfiles-stats.sh --top 20 # Top 20 commands
dotfiles-stats.sh --suggest # Alias recommendations
dotfiles-stats.sh --heatmap # Activity by hour
dotfiles-stats.sh --dirs # Most visited directories
dotfiles-stats.sh --git # Git command breakdown
dotfiles-stats.sh --export # Export as JSON
# Aliases
dfstats # Full dashboard
stats # Full dashboard
tophist # Top commands
suggest # Alias suggestions
```
### Secrets Vault
Encrypted storage using `age` or `gpg`:
```bash
dotfiles-vault.sh set KEY "value" # Store (or prompt for value)
dotfiles-vault.sh get KEY # Retrieve
dotfiles-vault.sh list # Show all keys
dotfiles-vault.sh delete KEY # Remove
dotfiles-vault.sh shell # Print as export statements
dotfiles-vault.sh export backup.enc # Backup encrypted vault
dotfiles-vault.sh import backup.enc # Restore vault
dotfiles-vault.sh status # Show vault info
# Aliases
vault set KEY "value"
vault get KEY
vault list
vls # vault list
vget KEY # vault get
vset KEY # vault set
```
**Auto-loading:** Secrets are automatically loaded into your environment on shell start.
### LastPass Integration
Unified interface for LastPass CLI:
```bash
pw list # List all items
pw get <item> # Get password
pw get <item> username # Get specific field
pw otp <item> # Get TOTP/2FA code
pw copy <item> # Copy password to clipboard
pw search <query> # Search items
pw lock # Logout/lock session
pwf # Fuzzy search items, copy password (requires fzf)
pwof # Fuzzy search items, copy OTP (requires fzf)
```
**Install LastPass CLI:**
```bash
# Via AUR with paru (recommended)
paru -S lastpass-cli
# Or with yay
yay -S lastpass-cli
```
### 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
# Aliases
dfs # Interactive sync
dfsync # Interactive sync
dfpush # Push changes
dfpull # Pull changes
dfstatus # Show status
```
**Auto-check:** On shell start, you'll be notified of available updates.
### Dynamic MOTD
System information displayed on shell startup:
```
┌──────────────────────────────────────────────────────────────┐
│ ✦ user@hostname Mon Dec 15 14:30│
├──────────────────────────────────────────────────────────────┤
│ ▲ up:4d 7h ◆ load:0.45 ◇ mem:8.2/32G ⊡ 234G free │
└──────────────────────────────────────────────────────────────┘
```
Shows: uptime, load average, memory, disk space
**Configuration:**
```bash
ENABLE_MOTD="true" # Enable MOTD
MOTD_STYLE="compact" # compact (box), mini (single line), or off
```
**Manual commands:**
```bash
show_motd # Show compact MOTD
show_motd_mini # Show single-line MOTD
motd # Alias for show_motd
```
### Snapper Integration
Btrfs snapshot management for Arch/CachyOS with limine bootloader:
```bash
snap-create "Description" # Create snapshot with validation
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
snap-sync # Manually trigger sync
snap-info # Detailed breakdown by type
snap-validate-service # Check service health
```
**Install limine-snapper-sync:**
```bash
paru -S limine-snapper-sync
sudo systemctl enable limine-snapper-sync.service
```
See [SNAPPER.md](docs/SNAPPER.md) for comprehensive guide.
### Tmux Workspace Manager
```bash
tw <name> # Quick attach or create workspace
tw-create <name> [template] # Create from template
tw-list # List all workspaces
tw-delete <name> # Delete workspace
tw-save <name> # Save current layout as template
tw-sync # Toggle pane synchronization
twf # Fuzzy search workspaces
tw-templates # List available templates
```
**Available Templates:**
- `dev` - 3 panes: vim (50%), terminal (25%), logs (25%)
- `ops` - 4-pane monitoring grid
- `ssh-multi` - 4 panes for multi-server management
- `debug` - 2 panes: main (70%), helper (30%)
- `full` - Single full-screen pane
- `review` - Side-by-side comparison panes
See [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) for advanced workflows.
### SSH Session Manager
```bash
ssh-save <name> <connection> [port] [key] [options] [description]
ssh-connect <name> # Connect with auto-tmux
ssh-list # List all profiles
sshf # Fuzzy search and connect
ssh-delete <name> # Delete profile
ssh-reconnect # Quick reconnect
ssh-sync-dotfiles <name> # Deploy dotfiles to remote
```
---
## 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 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
# Edit files...
dotfiles-sync.sh --push "Added new aliases"
```
**On Machine B (get changes):**
```bash
dotfiles-sync.sh --pull
source ~/.zshrc
```
### Automatic Sync
Enable watch mode (runs in background):
```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) |
| Command palette not working | Install fzf: `paru -S fzf` |
| Vault errors | Install age: `paru -S age` or gpg: `paru -S gnupg` |
| LastPass not working | Install: `paru -S lastpass-cli` |
| Snapper integration broken | Enable service: `sudo systemctl enable limine-snapper-sync.service` |
| 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
dotfiles-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 ~/.config/nvim
rm ~/.oh-my-zsh/themes/adlee.zsh-theme
rm ~/.local/bin/dotfiles-*.sh
# Restore backups (if any)
ls ~/.dotfiles_backup_*
# Remove dotfiles
rm -rf ~/.dotfiles
# Change shell back to bash
chsh -s /bin/bash
```
---
## Security Notes
- `.gitignore` excludes sensitive files (`.env`, `secrets/`, `*.local`, `vault/`)
- Vault uses strong encryption (age/gpg)
- Never commit API keys or tokens
- Personal espanso snippets may contain sensitive info
- Review `git/.gitconfig` before pushing (contains email)
---
## System Requirements Recap
| Component | Requirement |
|-----------|-------------|
| OS | Arch Linux or CachyOS |
| Shell | Zsh (auto-installed) |
| Package Manager | Pacman (built-in) |
| Editor | Vim (required) |
| Editor | Neovim (optional) |
| Password Manager | LastPass CLI (optional) |
| Encryption | age or gpg (optional, for vault) |
---
For more detailed guides, see:
- [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) - SSH and Tmux integration
- [SNAPPER.md](docs/SNAPPER.md) - Btrfs snapshot management
- [ESPANSO.md](docs/ESPANSO.md) - Text expansion snippets

732
docs/SNAPPER.md
View File

@@ -1,732 +0,0 @@
# Snapper Integration Guide
Complete guide to managing Btrfs snapshots with Snapper on Arch/CachyOS with limine bootloader integration.
## Table of Contents
- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Basic Commands](#basic-commands)
- [Snapshot Management](#snapshot-management)
- [Limine Boot Menu Integration](#limine-boot-menu-integration)
- [Automated Snapshots](#automated-snapshots)
- [Recovery Workflows](#recovery-workflows)
- [Troubleshooting](#troubleshooting)
- [Best Practices](#best-practices)
---
## Overview
Snapper is a tool for creating and managing Btrfs filesystem snapshots. Combined with `limine-snapper-sync`, it provides:
- **Point-in-time recovery** - Restore to specific snapshots
- **System rollback** - Boot previous system states
- **Change tracking** - See what changed between snapshots
- **Automated backups** - Create snapshots on schedule or before updates
**Arch/CachyOS Benefits:**
- Native Btrfs support
- Limine bootloader integration for boot menu entries
- Pre-configured subvolume layouts
- Snapshots directly bootable via limine
---
## Prerequisites
### System Requirements
- **OS:** Arch Linux or CachyOS
- **Filesystem:** Btrfs (required for snapshots)
- **Bootloader:** Limine (for boot menu integration)
- **Subvolume Layout:** Standard Arch Btrfs layout
### Check Your Setup
```bash
# Verify Btrfs filesystem
df -T /
# Output: Filesystem Type Mounted on
# /dev/nvme0n1p2 btrfs /
# Check subvolumes
btrfs subvolume list /
# Output should show: @ (root), @home, @var, @cache, etc.
# Verify limine bootloader
cat /proc/cmdline | grep limine
# or check EFI boot entry
efibootmgr
```
---
## Installation
### 1. Install Snapper
```bash
# Via pacman
sudo pacman -S snapper
# Or via AUR (paru or yay)
paru -S snapper
```
### 2. Install Limine Snapper Sync
```bash
# Via AUR
paru -S limine-snapper-sync
# Or yay
yay -S limine-snapper-sync
```
### 3. Configure Snapper
Create config for root subvolume:
```bash
sudo snapper -c root create-config /
```
Create config for home subvolume (optional):
```bash
sudo snapper -c home create-config /home
```
### 4. Enable Service
```bash
# Enable limine-snapper-sync service
sudo systemctl enable limine-snapper-sync.service
sudo systemctl start limine-snapper-sync.service
# Verify it's running
sudo systemctl status limine-snapper-sync.service
```
### 5. Verify Installation
```bash
snap-validate-service
```
Output:
```
✓ snapper installed
✓ limine-snapper-sync installed
✓ limine-snapper-sync enabled
✓ limine-snapper-sync running
✓ Snapper configs: root, home
```
---
## Basic Commands
### Create Snapshots
```bash
# Basic snapshot
snap-create "Initial setup"
# Snapshot with detailed description
snap-create "Before system upgrade - v6.13 → v6.14"
# Multiple snapshots
snap-create "Pre-AUR updates"
# ... do updates ...
snap-create "Post-AUR updates"
```
### List Snapshots
```bash
# Show last 10 snapshots
snap-list
# Show last 20 snapshots
snap-list 20
# Show all snapshots
snap-list all
```
Output:
```
Snapper Snapshots (root):
42 | 2025-12-21 14:30 | single | Before system upgrade
41 | 2025-12-21 10:15 | single | Initial setup
40 | 2025-12-20 23:45 | pre | Auto-snapshot (before pacman)
```
### View Snapshot Details
```bash
snap-show 42
```
Output:
```
Snapshot 42 (root):
Created: 2025-12-21 14:30:14
Type: single
Description: Before system upgrade
Filesystem: btrfs
Subvolume: @
UUID: a1b2c3d4-e5f6...
Space used: 2.3G
```
### Delete Snapshots
```bash
# Delete single snapshot
snap-delete 40
# Delete multiple
snap-delete 38 39 40
# Interactive delete
snap-delete --interactive
```
### Check Boot Menu Sync
```bash
snap-check-limine
```
Verifies:
- Limine config up to date
- All snapshots in boot menu
- Limine file locations correct
Output:
```
✓ Limine config found
✓ 12 boot entries detected
✓ Snapshots synced: 42, 41, 40
✓ Boot menu up to date
```
### Detailed Snapshot Info
```bash
snap-info
```
Shows breakdown by type:
- Pre-snapshots (before package operations)
- Post-snapshots (after package operations)
- Manual snapshots
- Timeline snapshots (if enabled)
### Manually Sync with Boot Menu
```bash
snap-sync
```
Manually trigger sync if you suspect desync between snapshots and boot menu.
---
## Snapshot Management
### Pre-configured Configs
Snapper comes with configs for different subvolumes. Manage them:
```bash
# List all configs
sudo snapper list-configs
# View config details
sudo snapper get-config root
sudo snapper get-config home
```
### Automatic Pre/Post Snapshots
Snapper automatically creates snapshots before/after pacman operations.
**Before update:**
```bash
sudo pacman -Syu
# Snapper auto-creates "pre" snapshot
# ... pacman runs ...
# Snapper auto-creates "post" snapshot
```
**View pre/post pairs:**
```bash
snap-list | grep "pre\|post"
```
### Timeline Snapshots (Optional)
Enable hourly/daily/monthly snapshots (not enabled by default):
```bash
# Edit snapper config
sudo nano /etc/snapper/configs/root
# Find TIMELINE settings:
TIMELINE_CREATE="yes"
TIMELINE_CLEANUP="yes"
# Set cleanup policy
TIMELINE_MIN_AGE="1800" # Min 30 min between timeline snapshots
TIMELINE_LIMIT_HOURLY="10" # Keep 10 hourly
TIMELINE_LIMIT_DAILY="7" # Keep 7 daily
TIMELINE_LIMIT_WEEKLY="0" # Disable weekly
TIMELINE_LIMIT_MONTHLY="12" # Keep 12 monthly
TIMELINE_LIMIT_YEARLY="10" # Keep 10 yearly
```
Enable timeline service:
```bash
sudo systemctl enable snapper-timeline.timer
sudo systemctl start snapper-timeline.timer
```
### Cleanup Policies
Configure what snapshots to keep (in `/etc/snapper/configs/root`):
```bash
# Keep this many... after cleanup runs
ALLOW_USERS=""
ALLOW_GROUPS=""
SYNC_ACL="no"
AUTODETECT_FILESYSTEMS="yes"
BTRFS_QGROUPS=""
BACKGROUND_COMPARISON="yes"
FSTYPE="btrfs"
SUBVOLUME="/"
NUMBER_CLEANUP="yes"
NUMBER_LIMIT="50"
NUMBER_LIMIT_IMPORTANT="10"
TIMELINE_CLEANUP="yes"
TIMELINE_MIN_AGE="1800"
TIMELINE_LIMIT_HOURLY="10"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="0"
TIMELINE_LIMIT_MONTHLY="12"
TIMELINE_LIMIT_YEARLY="10"
EMPTY_PRE_POST_CLEANUP="yes"
EMPTY_PRE_POST_CLEANUP_AGE="604800"
```
Then run cleanup:
```bash
sudo snapper -c root cleanup number
sudo snapper -c root cleanup timeline
sudo snapper -c home cleanup number
```
---
## Limine Boot Menu Integration
### How It Works
`limine-snapper-sync` automatically:
1. Detects all Snapper snapshots
2. Creates boot menu entries for each
3. Updates Limine configuration
4. Manages entries (adds/removes as snapshots change)
### Boot Menu Entries
After syncing, your limine boot menu will show:
```
Limine Boot Menu
────────────────────────────
1. Current System (Arch Linux)
└─ @ (default)
2. Snapshot 42: Before system upgrade
└─ @/.snapshots/42/snapshot
3. Snapshot 41: Initial setup
└─ @/.snapshots/41/snapshot
4. Snapshot 40: Auto-snapshot (before pacman)
└─ @/.snapshots/40/snapshot
```
### Boot from Snapshot
1. Restart computer
2. At Limine menu, select snapshot
3. System boots from snapshot subvolume
4. All changes since snapshot are **not visible**
**Important:** This is **read-only** unless you manually mount it writable.
### Differences Between Subvolume Types
| Subvolume | Path | Bootable | Writable |
|-----------|------|----------|----------|
| Root (`@`) | `/` | Yes | Yes |
| Snapshot | `@/.snapshots/42/snapshot` | Yes | No (default) |
| Read-only snapshot | `@/.snapshots/42/snapshot` | Yes | No |
---
## Automated Snapshots
### Before System Updates
```bash
# Snapper automatically creates pre-snapshot
sudo pacman -Syu
# After update completes, post-snapshot created
# View the pair
snap-list | tail -2
```
### Custom Aliases for Common Operations
```bash
# Before AUR updates
alias aur-update='snap-create "Before AUR update" && paru -Syu && snap-create "After AUR update"'
# Before kernel update
alias kernel-update='snap-create "Before kernel update" && sudo pacman -S linux && snap-create "After kernel update"'
```
### Systemd Unit for Scheduled Snapshots
Create `/etc/systemd/system/snapper-daily.service`:
```ini
[Unit]
Description=Daily Snapper Snapshot
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/bin/snapper -c root create -d "Daily snapshot"
ExecStart=/usr/bin/snapper -c home create -d "Daily snapshot (home)"
```
Create `/etc/systemd/system/snapper-daily.timer`:
```ini
[Unit]
Description=Daily Snapper Snapshot Timer
Requires=snapper-daily.service
[Timer]
OnCalendar=daily
OnCalendar=*-*-* 02:00:00
[Install]
WantedBy=timers.target
```
Enable:
```bash
sudo systemctl daemon-reload
sudo systemctl enable snapper-daily.timer
sudo systemctl start snapper-daily.timer
# Check status
sudo systemctl list-timers
```
---
## Recovery Workflows
### Scenario 1: System Won't Boot After Update
**Steps:**
1. **At Limine menu:**
- Select pre-update snapshot
- Boot from snapshot
2. **Once booted from snapshot:**
```bash
# Now in read-only snapshot environment
# Make notes of what failed
# If you want to apply fixes, remount writable
sudo mount -o remount,rw /
# Fix issues (reinstall package, etc)
sudo pacman -S broken_package
```
3. **Restore full system from snapshot:**
```bash
# Option A: Copy snapshot to live root
sudo btrfs subvolume snapshot /.snapshots/40/snapshot /@.restore
# Option B: Boot live, restore via btrfs
sudo btrfs subvolume delete /
sudo btrfs subvolume snapshot /.snapshots/40/snapshot /
```
4. **Reboot:**
```bash
sudo reboot
```
### Scenario 2: Configuration Accidental Overwrite
**Steps:**
1. **Identify when file changed:**
```bash
snap-list | grep -B5 -A5 "Some change"
```
2. **Find the snapshot before change:**
```bash
snap-show 42
snap-show 41
```
3. **Mount specific snapshot:**
```bash
sudo mkdir -p /mnt/snapshot42
sudo mount -t btrfs -o subvol=@/.snapshots/42/snapshot /dev/nvme0n1p2 /mnt/snapshot42
```
4. **Recover file:**
```bash
sudo cp /mnt/snapshot42/etc/nginx/nginx.conf ~/.config/
# Or view diff
diff /mnt/snapshot42/etc/nginx/nginx.conf /etc/nginx/nginx.conf
```
5. **Cleanup:**
```bash
sudo umount /mnt/snapshot42
sudo rmdir /mnt/snapshot42
```
### Scenario 3: Rollback Entire System
**Complete recovery from snapshot:**
```bash
# Boot from Limine snapshot menu
# At snapshot, create new snapshot of current state (optional backup)
snap-create "Pre-rollback backup"
# Restore from specific snapshot
sudo btrfs subvolume delete @
sudo btrfs subvolume snapshot /.snapshots/40/snapshot @
# Reboot
sudo reboot
```
**After reboot:**
- System is fully restored to snapshot state
- All post-snapshot changes are gone
- Snapshots still exist (you can rollback again)
---
## Troubleshooting
### Verify Snapper Installation
```bash
snap-validate-service
```
### Check Snapper Configs
```bash
sudo snapper list-configs
# Detailed config
sudo snapper -c root get-config
```
### Boot Menu Not Updating
```bash
# Manual sync
sudo snapper list-configs
snap-sync
# Check limine service
sudo systemctl status limine-snapper-sync.service
# View logs
sudo journalctl -u limine-snapper-sync.service -n 20
```
### Can't Mount Snapshot
```bash
# Create temporary mount point
sudo mkdir -p /mnt/snap
# Identify snapshot subvolume
btrfs subvolume list /
# Mount specific snapshot
sudo mount -t btrfs -o subvol=@/.snapshots/42/snapshot /dev/nvme0n1p2 /mnt/snap
# Verify
ls /mnt/snap
# Cleanup when done
sudo umount /mnt/snap
```
### Snapper Disk Usage Growing
```bash
# Check snapshot usage
btrfs filesystem usage /
# Cleanup old snapshots
sudo snapper -c root cleanup number
sudo snapper -c home cleanup number
# Verify disk usage decreased
btrfs filesystem usage /
```
### Service Won't Start
```bash
# Check errors
sudo systemctl start limine-snapper-sync.service
sudo journalctl -xe
# Manually sync
sudo /usr/bin/snapper-limine-sync
# Check limine configuration
ls -la /boot/limine/
cat /boot/limine/limine.conf
```
---
## Best Practices
### Before Major Operations
```bash
# Always snapshot before:
snap-create "Before AUR package X"
snap-create "Before kernel update"
snap-create "Before major configuration change"
# Then perform the operation
# Monitor for issues
# If issues: boot snapshot via Limine
# If success: keep snapshot for point-in-time recovery
```
### Naming Conventions
```bash
# Good names
snap-create "Before pacman system update"
snap-create "After successful AUR update"
snap-create "Backup before /etc/nginx config change"
# Bad names
snap-create "snapshot"
snap-create "test"
snap-create "backup"
```
### Regular Cleanup
Schedule cleanup (weekly):
```bash
# Add to crontab
0 3 * * 0 /usr/bin/snapper -c root cleanup number
0 4 * * 0 /usr/bin/snapper -c home cleanup number
0 5 * * 0 /usr/bin/snapper-limine-sync
```
### Documentation
```bash
# Keep notes of major changes and snapshots
# In ~/Documents/snapshot-history.txt
# 2025-12-21 Snapshot 42: System upgrade 6.13→6.14
# 2025-12-20 Snapshot 41: Initial setup complete
# 2025-12-19 Snapshot 40: Base installation
```
### Backup Critical Data
```bash
# Don't rely only on snapshots
# Backup critical data separately
# Snapshots are for:
# - System recovery
# - Configuration recovery
# - Point-in-time rollback
# Backups are for:
# - Off-site redundancy
# - Long-term retention
# - Disaster recovery
```
---
## Quick Reference
| Command | Purpose |
|---------|---------|
| `snap-create` | Create snapshot |
| `snap-list` | List snapshots |
| `snap-show` | Show snapshot details |
| `snap-delete` | Delete snapshot |
| `snap-check-limine` | Verify boot menu sync |
| `snap-sync` | Manual sync to boot menu |
| `snap-validate-service` | Verify service health |
| `snap-info` | Show snapshot breakdown |
---
## See Also
- [README.md](../README.md) - Main documentation
- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Installation guide
- [Snapper Documentation](https://github.com/openSUSE/snapper)
- [Limine Snapper Sync](https://github.com/terrapkg/limine-snapper-sync)

674
docs/SSH_TMUX_INTEGRATION.md
View File

@@ -1,674 +0,0 @@
# SSH + Tmux Integration Guide
Advanced workflows for managing SSH connections and tmux workspaces on Arch/CachyOS.
## Table of Contents
- [SSH Manager Overview](#ssh-manager-overview)
- [Basic SSH Management](#basic-ssh-management)
- [Tmux Workspace Basics](#tmux-workspace-basics)
- [SSH + Tmux Integration](#ssh--tmux-integration)
- [Workflow Examples](#workflow-examples)
- [Advanced Features](#advanced-features)
- [Multi-Server Management](#multi-server-management)
- [Troubleshooting](#troubleshooting)
---
## SSH Manager Overview
The SSH manager stores connection profiles and integrates seamlessly with tmux for session management.
**Features:**
- Save and organize SSH connections
- Auto-create tmux sessions per connection
- Quick fuzzy search and connect
- Deploy dotfiles to remote machines
- Support for custom SSH options
- No external dependencies (pure bash)
---
## Basic SSH Management
### Saving Connections
```bash
ssh-save <profile> <connection> [port] [key] [description]
```
**Examples:**
```bash
# Basic SSH
ssh-save prod user@prod.example.com
# With custom port
ssh-save prod user@prod.example.com 2222
# With SSH key
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key
# With description
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key "Production server"
# With SSH options
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key "Production" "-v -o ConnectTimeout=5"
```
### Listing Profiles
```bash
ssh-list
```
Output:
```
SSH Profiles:
prod user@prod.example.com:22 [~/.ssh/prod_key]
staging user@staging.example.com:22 [~/.ssh/staging_key]
dev user@dev.example.com:2222 [~/.ssh/dev_key]
backup user@backup.example.com:22 [default]
```
### Connecting to Profiles
```bash
ssh-connect <profile>
# or
ssh <profile>
```
### Fuzzy Search and Connect
```bash
sshf
```
Opens fuzzy selector:
```
prod user@prod.example.com:22
> staging user@staging.example.com:22
dev user@dev.example.com:2222
backup user@backup.example.com:22
```
Select with arrows, press Enter to connect.
### Deleting Profiles
```bash
ssh-delete <profile>
```
### Syncing Dotfiles to Remote
```bash
ssh-sync-dotfiles <profile>
```
This will:
1. SSH into the remote machine
2. Clone your dotfiles repo
3. Run the installer
4. Validate installation
**With custom repo:**
```bash
ssh-sync-dotfiles prod --repo https://github.com/myuser/dotfiles.git
```
### Quick Reconnect
```bash
ssh-reconnect
```
Reconnects to the last SSH connection.
---
## Tmux Workspace Basics
### Quick Workspace Access
```bash
tw <name>
```
Creates or attaches to tmux session. If session exists, attaches. If not, creates with default layout.
### Creating with Templates
```bash
tw-create <name> [template]
tw-create myproject dev
tw-create monitoring ops
tw-create review review
```
**Available Templates:**
| Template | Layout | Use Case |
|----------|--------|----------|
| `dev` | vim (50%) + terminal (25%) + logs (25%) | Development |
| `ops` | 4-pane grid | Monitoring |
| `ssh-multi` | 4 panes (synchronized) | Multi-server ops |
| `debug` | 2 panes: main (70%), helper (30%) | Debugging |
| `full` | Single pane | Fullscreen work |
| `review` | Side-by-side panes | Code review |
### Listing Workspaces
```bash
tw-list
```
Output:
```
Tmux Workspaces:
myproject 3 windows, 7 panes
monitoring 1 window, 4 panes
ssh-ops 2 windows, 5 panes
```
### Deleting Workspaces
```bash
tw-delete <name>
```
### Saving Custom Layout
Current window layout as a reusable template:
```bash
tw-save mytemplate
```
Then use it:
```bash
tw-create newproject mytemplate
```
### Fuzzy Workspace Selection
```bash
twf
```
Fuzzy search all tmux sessions and attach.
### Pane Synchronization
Send commands to all panes simultaneously:
```bash
tw-sync # Toggle on/off
```
When enabled, your typing goes to all panes. Useful for:
- Running same command on multiple servers
- Updating configs in parallel
- Monitoring multiple streams
---
## SSH + Tmux Integration
### Automatic Tmux Session on SSH
When you connect via `ssh-connect`, a tmux session is automatically created:
```bash
ssh-connect prod
# Creates tmux session: ssh_prod
# Loads ssh_prod template if available
# Attaches you to the session
```
**Session naming:** `ssh_<profile>`
### Accessing Your Session
From the remote machine:
```bash
# Attach to your session
tmux attach -t ssh_prod
# Detach (leave session running)
Ctrl+B, D
```
### Pre-configured Remote Tmux
If the remote has tmux installed, you can use its features:
```bash
# In your SSH session, create new window
Ctrl+B, C
# Navigate windows
Ctrl+B, <number>
```
### Deploy Dotfiles + Setup Tmux Remotely
```bash
ssh-sync-dotfiles prod
# Installs dotfiles on remote
# Remote will have same tmux config
```
---
## Workflow Examples
### Example 1: Web Development
**Setup:**
```bash
ssh-save staging deploy@staging.example.com 22 ~/.ssh/staging_key
tw-create webdev dev
# Now in tmux with vim ready
```
**Workflow:**
```
Pane 1 (50%): vim/nvim
- Edit code locally
Pane 2 (25%): Dev terminal
- npm start, python manage.py runserver, etc.
Pane 3 (25%): Logs
- tail -f logs/debug.log
```
**Keybindings:**
```bash
# Move between panes
Ctrl+B, Left/Right/Up/Down
# Zoom pane
Ctrl+B, Z
# Create new window
Ctrl+B, C
# Switch window
Ctrl+B, 0-9
```
### Example 2: Multi-Server Monitoring
```bash
ssh-save web1 ubuntu@web1.prod.com
ssh-save web2 ubuntu@web2.prod.com
ssh-save web3 ubuntu@web3.prod.com
tw-create monitoring ops
```
**Setup in tmux:**
```bash
# In window, split into 4 panes
Ctrl+B, % # Split left/right
Ctrl+B, " # Split top/bottom
# In each pane, open SSH connection
ssh web1
ssh web2
ssh web3
(one more)
# Enable sync for parallel commands
tw-sync
```
Now you can run commands on all 4 servers simultaneously.
### Example 3: Database Backup + Restore
```bash
# Save DB server
ssh-save dbserver ubuntu@db.prod.com 22 ~/.ssh/db_key
# Create workspace
tw-create dbops debug
```
**Workflow:**
```
Pane 1 (70%): Main operations
- mysqldump commands
- pg_dump commands
- Restore operations
Pane 2 (30%): Helper
- Monitoring commands
- Disk space checks
- Backup status
```
### Example 4: Deployment Pipeline
```bash
ssh-save deploy user@deploy.prod.com
tw-create deploy ssh-multi
# Creates 4 synchronized panes
```
**In each pane:**
```bash
ssh-connect prod # Pane 1
ssh-connect staging # Pane 2
ssh-connect dev # Pane 3
ssh-connect backup # Pane 4
# Enable sync
tw-sync
# Now run deployment commands on all
./deploy.sh v1.2.3
```
---
## Advanced Features
### Custom SSH Options
```bash
# Verbose SSH
ssh-save prod user@prod.com 22 ~/.ssh/key "Production" "-v"
# Connection timeout
ssh-save unreliable user@unreliable.com 22 ~/.ssh/key "Unreliable" "-o ConnectTimeout=10"
# Jump host / Bastion
ssh-save internal user@internal.prod.com 22 ~/.ssh/key "Internal" "-o ProxyCommand='ssh -W %h:%p user@bastion.example.com'"
# Multiple options
ssh-save strict user@strict.com 22 ~/.ssh/key "Strict" "-v -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5"
```
### SSH Config Integration
The SSH manager creates entries in `~/.ssh/config`. View them:
```bash
cat ~/.ssh/config
```
Example:
```
Host prod
HostName prod.example.com
User ubuntu
IdentityFile ~/.ssh/prod_key
Port 22
ConnectTimeout 10
```
Use directly:
```bash
ssh prod
# Uses the saved profile from SSH config
```
### Batch Operations
Create a script for multi-server operations:
```bash
#!/bin/bash
# deploy-to-all.sh
servers=("prod" "staging" "dev")
for server in "${servers[@]}"; do
echo "Deploying to $server..."
ssh-connect $server << 'EOF'
cd /app
git pull origin main
./deploy.sh
echo "✓ Deployed to $server"
exit
EOF
done
```
Run:
```bash
chmod +x deploy-to-all.sh
./deploy-to-all.sh
```
---
## Multi-Server Management
### Save Multiple Servers
```bash
# Web servers
ssh-save web1 ubuntu@web1.prod.com
ssh-save web2 ubuntu@web2.prod.com
ssh-save web3 ubuntu@web3.prod.com
# Database servers
ssh-save db-primary ubuntu@db-primary.prod.com
ssh-save db-replica ubuntu@db-replica.prod.com
# Cache servers
ssh-save redis1 ubuntu@redis1.prod.com
ssh-save redis2 ubuntu@redis2.prod.com
```
### Create Management Workspace
```bash
tw-create prod-ops ssh-multi
# Creates workspace with 4 synchronized panes
```
### Connect to All Web Servers
```bash
# In 4 panes of the workspace
ssh-connect web1
ssh-connect web2
ssh-connect web3
# (one extra pane)
# Enable sync
tw-sync
# Run command on all
sudo systemctl restart nginx
# Command runs on all 3 web servers
```
### Monitor All Servers
```bash
tw-create monitoring ops
# Configure 4 panes for monitoring
# Pane 1: web1 - htop
# Pane 2: web2 - htop
# Pane 3: db-primary - iostat -x 1
# Pane 4: redis1 - redis-cli monitor
```
### Environment-Specific Workspaces
```bash
# Production
tw-create prod-dev dev
ssh-sync-dotfiles prod
# Staging
tw-create staging-dev dev
ssh-sync-dotfiles staging
# Development
tw-create dev-local full
```
---
## Troubleshooting
### SSH Connection Issues
```bash
# Test SSH connection
ssh -vvv <profile>
# View saved connection details
ssh-list
# Delete and re-save
ssh-delete <profile>
ssh-save <profile> <connection> [options]
```
### Tmux Session Issues
```bash
# List all tmux sessions
tmux ls
# Kill a session
tmux kill-session -t <name>
# Attach to detached session
tmux attach -t <name>
# Kill all sessions
tmux kill-server
```
### SSH Sync Issues
```bash
# Test dotfiles deployment
ssh-sync-dotfiles <profile> --test
# View detailed output
ssh-sync-dotfiles <profile> --verbose
# Deploy specific branch
ssh-sync-dotfiles <profile> --branch develop
```
### Key Permission Issues
```bash
# Fix SSH key permissions
chmod 600 ~/.ssh/your_key
chmod 700 ~/.ssh
# List keys
ssh-add -l
# Add key to agent
ssh-add ~/.ssh/your_key
```
### Pane Sync Issues
```bash
# Verify sync is enabled
tmux show-window-options synchronize-panes
# Toggle sync manually
Ctrl+B, Shift+X
# Or use script
tw-sync
```
---
## Best Practices
1. **Use Descriptive Profile Names**
```bash
# Good
ssh-save prod-web-01 ubuntu@web01.prod.example.com
ssh-save staging-db ubuntu@db.staging.example.com
# Bad
ssh-save server1 ubuntu@192.168.1.10
```
2. **Store Keys Securely**
```bash
chmod 600 ~/.ssh/your_key
chmod 700 ~/.ssh
```
3. **Use SSH Agent**
```bash
eval $(ssh-agent)
ssh-add ~/.ssh/key
```
4. **Enable Agent Forwarding for Nested SSH**
```bash
ssh-save jumphost user@jump.example.com 22 ~/.ssh/key "" "-A"
```
5. **Test Connections**
```bash
ssh -T <profile>
```
6. **Document Complex Workflows**
```bash
# Create README in ~/.dotfiles/ssh-workflows/README.md
# Document your multi-server setups
```
---
## Quick Reference
| Command | Purpose |
|---------|---------|
| `ssh-save` | Save SSH profile |
| `ssh-list` | List all profiles |
| `ssh-connect` | Connect and create tmux session |
| `sshf` | Fuzzy search and connect |
| `ssh-delete` | Delete profile |
| `ssh-sync-dotfiles` | Deploy dotfiles to remote |
| `tw` | Quick workspace attach/create |
| `tw-create` | Create workspace with template |
| `tw-list` | List all workspaces |
| `tw-delete` | Delete workspace |
| `tw-save` | Save current layout as template |
| `tw-sync` | Toggle pane synchronization |
| `twf` | Fuzzy select workspace |
| `ssh-reconnect` | Quick reconnect to last SSH |
---
For more information on individual features, see:
- [README.md](../README.md) - Main documentation
- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Installation and basic configuration