diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..90c08e7 --- /dev/null +++ b/INSTALL.md @@ -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). diff --git a/README.md b/README.md index 0f70735..53179b0 100644 --- a/README.md +++ b/README.md @@ -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) [![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 | |---------|-------------| -| **Setup Wizard** | Beautiful TUI installer with feature selection | -| **Dynamic MOTD** | System info on shell start (uptime, CPU, memory, updates) | -| **Zsh Theme** | Two-line prompt with git status, command timer, root detection | -| **Command Palette** | Raycast-style fuzzy launcher (Ctrl+Space) | +| **Dynamic MOTD** | System info on shell start (uptime, load, memory, updates) | +| **Two-Line Prompt** | Git status, command timer, update indicator, root detection | +| **Command Palette** | Raycast-style fuzzy launcher (`Ctrl+Space`) | | **Smart Suggestions** | Typo correction + alias recommendations | -| **Shell Analytics** | Track command usage and get insights | -| **Secrets Vault** | Encrypted storage for API keys and sensitive data | -| **LastPass CLI** | Unified password manager integration | -| **Dotfiles Sync** | Keep configuration in sync across machines | -| **Snapper Integration** | Btrfs snapshot management with limine-snapper-sync | +| **Systemd Helpers** | Quick service management shortcuts | +| **Btrfs Helpers** | Filesystem health, scrub, balance commands | +| **Snapper Integration** | Btrfs snapshots with limine boot menu sync | +| **Secrets Vault** | Encrypted storage for API keys (age/gpg) | +| **Password Manager** | LastPass CLI integration | | **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 -```bash -git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh -``` +## Quick Start -### Interactive Wizard (Recommended) -```bash -git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles -cd ~/.dotfiles -./install.sh --wizard -``` - -### Standard Install ```bash git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles cd ~/.dotfiles ./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/ -├── install.sh # Main installer script -├── dotfiles.conf # Central configuration -├── zsh/ -│ ├── .zshrc # Shell configuration -│ ├── aliases.zsh # Command aliases -│ ├── themes/adlee.zsh-theme # Prompt theme -│ └── functions/ -│ ├── command-palette.zsh # Ctrl+Space launcher -│ ├── motd.zsh # System info display -│ ├── smart-suggest.zsh # Typo correction -│ ├── password-manager.zsh # LastPass integration -│ ├── snapper.zsh # Btrfs snapshots -│ ├── ssh-manager.zsh # SSH profiles -│ ├── tmux-workspaces.zsh # Workspace templates -│ └── python-templates.zsh # Python project scaffolding -├── vim/.vimrc # Vim configuration -├── nvim/ # Neovim configuration -├── tmux/.tmux.conf # Tmux configuration -├── git/.gitconfig.template # Git configuration template -└── bin/ # Scripts (symlinked to ~/.local/bin) - ├── dotfiles-doctor.sh # Health checker - ├── dotfiles-sync.sh # Multi-machine sync - ├── dotfiles-stats.sh # Shell analytics - ├── dotfiles-update.sh # Update dotfiles - ├── dotfiles-vault.sh # Encrypted secrets manager - └── dotfiles-version.sh # Version info +### Dotfiles Management + +| Command | Alias | Description | +|---------|-------|-------------| +| `dotfiles-doctor.sh` | `dfd`, `doctor` | Health check | +| `dotfiles-doctor.sh --fix` | `dffix` | Auto-fix issues | +| `dotfiles-doctor.sh --quick` | - | Quick essential checks | +| `dotfiles-sync.sh` | `dfs`, `dfsync` | Sync status | +| `dotfiles-sync.sh push` | `dfpush` | Push changes to remote | +| `dotfiles-sync.sh pull` | `dfpull` | Pull remote changes | +| `dotfiles-update.sh` | `dfu`, `dfupdate` | Update dotfiles | +| `dotfiles-version.sh` | `dfv`, `dfversion` | Version info | +| `dotfiles-stats.sh` | `dfstats` | Shell analytics | +| `dotfiles-vault.sh` | `vault` | Secrets manager | +| `dotfiles-compile.sh` | `dfcompile` | Compile zsh for speed | +| `source ~/.zshrc` | `reload`, `rl` | Reload shell config | + +### Quick Edit Aliases + +| Alias | Opens | +|-------|-------| +| `v.zshrc` | `~/.zshrc` | +| `v.conf` | `~/.dotfiles/dotfiles.conf` | +| `v.alias` | `~/.dotfiles/zsh/aliases.zsh` | +| `v.motd` | `~/.dotfiles/zsh/functions/motd.zsh` | +| `v.edit` | `~/.dotfiles` directory in editor | + +--- + +## Systemd Helpers + +Quick shortcuts for systemd service management. + +### Core Commands + +| Command | Description | +|---------|-------------| +| `sc ` | `sudo systemctl ` | +| `scu ` | `systemctl --user ` | +| `scr ` | Restart service and show status | +| `sce ` | Enable and start service | +| `scd ` | Disable and stop service | +| `sclog ` | Follow journal logs (`-f`) | +| `sclogs ` | 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 ` | Search services by name | +| `sc-info ` | 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 ` | 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 ` | `snapshow` | Show snapshot details | +| `snap-delete ` | `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:** -- `Enter` - Execute command -- `Ctrl+E` - Edit before running -- `Ctrl+Y` - Copy to clipboard +- Aliases and functions +- Recent commands +- Git commands (when in repo) +- 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 -```bash -bookmark projects ~/projects # Save bookmark -bookmark list # List all -jump projects # Go to bookmark -j # Fuzzy select -``` +| Command | Alias | Description | +|---------|-------|-------------| +| `bookmark [path]` | `bm` | Save bookmark (default: current dir) | +| `bookmark list` | `bm list` | List all bookmarks | +| `bookmark delete ` | `bm rm` | Delete bookmark | +| `jump ` | `j` | Go to bookmark (fuzzy select if no name) | -## 🔧 Smart Suggestions +--- + +## Smart Suggestions Automatic typo correction for 100+ common mistakes: @@ -129,10 +237,6 @@ Automatic typo correction for 100+ common mistakes: $ gti status ✗ Command not found: gti → Did you mean: git? - -$ dokcer ps -✗ Command not found: dokcer -→ Did you mean: docker? ``` Alias recommendations for frequently typed commands: @@ -142,222 +246,347 @@ Alias recommendations for frequently typed commands: 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 -dotfiles-stats.sh # Full dashboard -# or use aliases: -dfstats -stats +fuck # Re-run last command with typo correction ``` -``` -╔═══════════════════════════════════════════════════════════════════╗ -║ 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 -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 -``` +### Display Styles -Export to environment: - -```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 | +| Style | Command | Description | |-------|---------|-------------| -| `dfd` | `dotfiles-doctor.sh` | Health check | -| `dffix` | `dotfiles-doctor.sh --fix` | Auto-fix issues | -| `dfs` | `dotfiles-sync.sh` | Sync dotfiles | -| `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 | +| Compact | `show_motd` | Box format with stats | +| Mini | `show_motd_mini` | Single line | +| Full | `show_motd_full` | Extended info with kernel, scheduler | -## 🩺 Health Check +### Configuration + +In `dotfiles.conf`: ```bash -dotfiles-doctor.sh # Run diagnostics -dotfiles-doctor.sh --fix # Auto-fix issues -# Aliases: dfd, doctor, dffix +ENABLE_MOTD="true" +MOTD_STYLE="compact" # compact, mini, full, or none ``` -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 [value]` | Store secret (prompts if value omitted) | +| `vault get ` | Retrieve secret | +| `vault list` | List all keys | +| `vault delete ` | Delete secret | +| `vault shell` | Print as export statements | +| `vault export ` | Backup vault (encrypted) | +| `vault import ` | 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 [field]` | Get field (default: password) | +| `pw otp ` | Get TOTP code | +| `pw search ` | Search items | +| `pw copy [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 [template]` | - | Attach or create workspace | +| `tw-create [template]` | `twc` | Create workspace | +| `tw-attach ` | `twa` | Attach to workspace | +| `tw-list` | `twl` | List active workspaces | +| `tw-delete ` | `twd` | Delete workspace | +| `tw-save ` | `tws` | Save current layout as template | +| `tw-templates` | `twt` | List available templates | +| `tw-template-edit ` | `twe` | Edit template | +| `tw-sync` | - | Toggle pane synchronization | +| `tw-rename ` | - | 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 [port] [key] [opts] [desc]` | `sshs` | Save profile | +| `ssh-list` | `sshl` | List all profiles | +| `ssh-connect ` | `sshc` | Connect (auto tmux) | +| `ssh-delete ` | `sshd` | Delete profile | +| `ssh-reconnect [name]` | `sshr` | Reconnect (default: last) | +| `ssh-sync-dotfiles ` | `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 ` | `pynew` | Basic Python project | +| `py-django ` | `pydjango` | Django web app | +| `py-flask ` | `pyflask` | Flask web app | +| `py-fastapi ` | `pyfast` | FastAPI REST API | +| `py-data ` | `pydata` | Data science project | +| `py-cli ` | `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 # Identity @@ -365,71 +594,72 @@ USER_FULLNAME="Your Name" USER_EMAIL="you@example.com" USER_GITHUB="yourusername" -# Features -INSTALL_ZSH_PLUGINS="true" -INSTALL_FZF="ask" -INSTALL_NEOVIM="ask" -SET_ZSH_DEFAULT="ask" +# MOTD +ENABLE_MOTD="true" +MOTD_STYLE="compact" -# Advanced +# Features ENABLE_SMART_SUGGESTIONS="true" ENABLE_COMMAND_PALETTE="true" ENABLE_VAULT="true" DOTFILES_AUTO_SYNC_CHECK="true" + +# Btrfs +BTRFS_DEFAULT_MOUNT="/" + +# Package Manager +AUR_HELPER="auto" # paru, yay, or auto ``` -## 🔄 Updating +--- -```bash -dotfiles-update.sh -# or aliases: -dfu -dfupdate +## Repository Structure + +``` +~/.dotfiles/ +├── 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 - -```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 +## License MIT – See [LICENSE](LICENSE) --- **Author:** Aaron D. Lee -**Repository:** https://github.com/adlee-was-taken/dotfiles -**Arch/CachyOS Only Edition** +**Repository:** https://github.com/adlee-was-taken/dotfiles diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index f6f3bab..0000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -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 $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) diff --git a/docs/ESPANSO.md b/docs/ESPANSO.md deleted file mode 100644 index 690b66d..0000000 --- a/docs/ESPANSO.md +++ /dev/null @@ -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: "{{name}}" - 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 # 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` diff --git a/docs/INDEX.md b/docs/INDEX.md deleted file mode 100644 index cc12453..0000000 --- a/docs/INDEX.md +++ /dev/null @@ -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* diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md deleted file mode 100644 index 54ca988..0000000 --- a/docs/QUICK_REFERENCE.md +++ /dev/null @@ -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 [path] # Save bookmark (default: current dir) -bookmark list # List all -bookmark delete # Delete -jump # 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 # Save profile -ssh-list # List profiles -ssh-connect # Connect (auto-tmux) -sshf # Fuzzy search + connect -ssh-delete # Delete -ssh-sync-dotfiles # Deploy dotfiles to remote -ssh-reconnect # Quick reconnect -``` - ---- - -## 🎪 Tmux Workspace Manager - -```bash -tw # Quick attach/create -tw-create [tmpl] # Create with template -tw-list # List workspaces -tw-delete # Delete -tw-save # 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 -``` - -### 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 diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md new file mode 100644 index 0000000..de365c4 --- /dev/null +++ b/docs/REFERENCE.md @@ -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 (`?`) | +| `,` | 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 | diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md deleted file mode 100644 index f9c859d..0000000 --- a/docs/SETUP_GUIDE.md +++ /dev/null @@ -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 [path] # Save bookmark (default: current dir) -bookmark list # List all bookmarks -bookmark delete # Remove bookmark -jump # 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 # Get password -pw get username # Get specific field -pw otp # Get TOTP/2FA code -pw copy # Copy password to clipboard -pw search # 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 # Details for specific snapshot -snap-delete # 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 # Quick attach or create workspace -tw-create [template] # Create from template -tw-list # List all workspaces -tw-delete # Delete workspace -tw-save # 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 [port] [key] [options] [description] -ssh-connect # Connect with auto-tmux -ssh-list # List all profiles -sshf # Fuzzy search and connect -ssh-delete # Delete profile -ssh-reconnect # Quick reconnect -ssh-sync-dotfiles # 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 -