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

Dotfiles update 2025-12-24 17:46

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

531
docs/CONTRIBUTING.md
View File

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

384
docs/ESPANSO.md
View File

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

396
docs/INDEX.md
View File

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

401
docs/QUICK_REFERENCE.md
View File

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

608
docs/REFERENCE.md Normal file
View File

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

661
docs/SETUP_GUIDE.md
View File

@@ -1,661 +0,0 @@
# Setup Guide
Complete guide for installing, configuring, and maintaining your Arch/CachyOS dotfiles.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation Methods](#installation-methods)
- [Post-Install Setup](#post-install-setup)
- [Configuration](#configuration)
- [Features Guide](#features-guide)
- [Customization](#customization)
- [Multi-Machine Setup](#multi-machine-setup)
- [Troubleshooting](#troubleshooting)
- [Uninstalling](#uninstalling)
---
## Prerequisites
**Required:**
- Arch Linux or CachyOS
- Git
- Curl
- Pacman (built-in)
**Optional (for full features):**
- `fzf` - For command palette and fuzzy finding
- `age` or `gpg` - For secrets vault
- `lastpass-cli` - For password manager integration
- `nvim` - For Neovim support (Vim is sufficient)
---
## Installation Methods
### Method 1: Interactive Wizard (Recommended)
The wizard provides a beautiful TUI to customize your installation:
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard
```
The wizard will guide you through:
1. Identity setup (name, email, GitHub)
2. Git configuration
3. Feature selection
4. Theme choice
5. Advanced options
### Method 2: One-liner
Quick install with defaults:
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh
```
### Method 3: Standard Install
Clone and run with prompts:
```bash
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```
### Install Options
```bash
./install.sh # Interactive install
./install.sh --wizard # TUI wizard
./install.sh --skip-deps # Skip dependency installation
./install.sh --deps-only # Only install dependencies, then exit
./install.sh --uninstall # Remove symlinks
./install.sh --uninstall --purge # Remove everything
./install.sh --help # Show all options
```
---
## Post-Install Setup
### 1. Verify Installation
```bash
dotfiles-doctor.sh
```
This checks:
- All symlinks are valid
- Zsh plugins installed
- Git configured
- Theme loaded
- Optional tools present
Fix issues automatically:
```bash
dotfiles-doctor.sh --fix
```
### 2. Restart Shell
```bash
exec zsh
# or just close and reopen your terminal
```
### 3. Configure LastPass (Optional)
```bash
pw list
# First run will prompt you to login
# Enter your LastPass email and master password
```
### 4. Set Up Secrets Vault (Optional)
```bash
vault init
vault set GITHUB_TOKEN "your-token-here"
vault list
```
### 5. Configure Directory Bookmarks (Optional)
```bash
bookmark projects ~/projects
bookmark work ~/work
bookmark list
```
---
## Configuration
### Main Configuration File
All settings are in `~/.dotfiles/dotfiles.conf`:
```bash
# ============================================================================
# Identity
# ============================================================================
USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com"
USER_GITHUB="yourusername"
# ============================================================================
# Git Configuration
# ============================================================================
GIT_USER_NAME="" # Falls back to USER_FULLNAME
GIT_USER_EMAIL="" # Falls back to USER_EMAIL
GIT_DEFAULT_BRANCH="main"
# ============================================================================
# Feature Toggles
# ============================================================================
# Values: "true", "false", or "ask"
INSTALL_DEPS="auto" # Auto-skip if already installed
INSTALL_ZSH_PLUGINS="true" # zsh-autosuggestions, syntax-highlighting
INSTALL_FZF="ask"
INSTALL_BAT="ask"
INSTALL_EZA="ask"
INSTALL_NEOVIM="ask"
SET_ZSH_DEFAULT="ask"
# ============================================================================
# Advanced Features
# ============================================================================
ENABLE_SMART_SUGGESTIONS="true" # Typo correction
ENABLE_COMMAND_PALETTE="true" # Ctrl+Space launcher
ENABLE_SHELL_ANALYTICS="false" # Command stats
ENABLE_VAULT="true" # Encrypted secrets
DOTFILES_AUTO_SYNC_CHECK="true" # Check for updates on shell start
```
### Applying Configuration Changes
After editing `dotfiles.conf`:
```bash
./install.sh --skip-deps
# or just
source ~/.zshrc
```
---
## Features Guide
### Command Palette
**Trigger:** `Ctrl+Space` or `Ctrl+P`
The command palette searches:
- ⚡ Aliases
- λ Functions
- ↺ Recent commands
- 📁 Bookmarked directories
- ⚙ Dotfiles scripts
- ★ Quick actions
- ⎇ Git commands (context-aware)
- ◉ Docker commands
**Keybindings in palette:**
| Key | Action |
|-----|--------|
| `Enter` | Execute command |
| `Ctrl+E` | Edit command first |
| `Ctrl+Y` | Copy to clipboard |
| `Ctrl+R` | Refresh entries |
| `Esc` | Cancel |
**Bookmarks:**
```bash
bookmark <name> [path] # Save bookmark (default: current dir)
bookmark list # List all bookmarks
bookmark delete <name> # Remove bookmark
jump <name> # Go to bookmark
j # Fuzzy select bookmark
```
### Smart Suggestions
Automatically corrects 100+ common typos:
```bash
gti → git
dokcer → docker
sl → ls
pytohn → python
```
Suggests aliases for frequently typed commands:
```bash
💡 You've typed 'git status' 50 times
You already have an alias: gs
```
**Commands:**
```bash
fuck # Re-run last command with typo fixed
```
### Shell Analytics
```bash
dotfiles-stats.sh # Full dashboard
dotfiles-stats.sh --top 20 # Top 20 commands
dotfiles-stats.sh --suggest # Alias recommendations
dotfiles-stats.sh --heatmap # Activity by hour
dotfiles-stats.sh --dirs # Most visited directories
dotfiles-stats.sh --git # Git command breakdown
dotfiles-stats.sh --export # Export as JSON
# Aliases
dfstats # Full dashboard
stats # Full dashboard
tophist # Top commands
suggest # Alias suggestions
```
### Secrets Vault
Encrypted storage using `age` or `gpg`:
```bash
dotfiles-vault.sh set KEY "value" # Store (or prompt for value)
dotfiles-vault.sh get KEY # Retrieve
dotfiles-vault.sh list # Show all keys
dotfiles-vault.sh delete KEY # Remove
dotfiles-vault.sh shell # Print as export statements
dotfiles-vault.sh export backup.enc # Backup encrypted vault
dotfiles-vault.sh import backup.enc # Restore vault
dotfiles-vault.sh status # Show vault info
# Aliases
vault set KEY "value"
vault get KEY
vault list
vls # vault list
vget KEY # vault get
vset KEY # vault set
```
**Auto-loading:** Secrets are automatically loaded into your environment on shell start.
### LastPass Integration
Unified interface for LastPass CLI:
```bash
pw list # List all items
pw get <item> # Get password
pw get <item> username # Get specific field
pw otp <item> # Get TOTP/2FA code
pw copy <item> # Copy password to clipboard
pw search <query> # Search items
pw lock # Logout/lock session
pwf # Fuzzy search items, copy password (requires fzf)
pwof # Fuzzy search items, copy OTP (requires fzf)
```
**Install LastPass CLI:**
```bash
# Via AUR with paru (recommended)
paru -S lastpass-cli
# Or with yay
yay -S lastpass-cli
```
### Dotfiles Sync
```bash
dotfiles-sync.sh # Interactive sync
dotfiles-sync.sh --status # Show sync status
dotfiles-sync.sh --push # Push local changes
dotfiles-sync.sh --pull # Pull remote changes
dotfiles-sync.sh --diff # Show local changes
dotfiles-sync.sh --watch 300 # Auto-sync every 5 minutes
dotfiles-sync.sh --log # Show sync history
# Aliases
dfs # Interactive sync
dfsync # Interactive sync
dfpush # Push changes
dfpull # Pull changes
dfstatus # Show status
```
**Auto-check:** On shell start, you'll be notified of available updates.
### Dynamic MOTD
System information displayed on shell startup:
```
┌──────────────────────────────────────────────────────────────┐
│ ✦ user@hostname Mon Dec 15 14:30│
├──────────────────────────────────────────────────────────────┤
│ ▲ up:4d 7h ◆ load:0.45 ◇ mem:8.2/32G ⊡ 234G free │
└──────────────────────────────────────────────────────────────┘
```
Shows: uptime, load average, memory, disk space
**Configuration:**
```bash
ENABLE_MOTD="true" # Enable MOTD
MOTD_STYLE="compact" # compact (box), mini (single line), or off
```
**Manual commands:**
```bash
show_motd # Show compact MOTD
show_motd_mini # Show single-line MOTD
motd # Alias for show_motd
```
### Snapper Integration
Btrfs snapshot management for Arch/CachyOS with limine bootloader:
```bash
snap-create "Description" # Create snapshot with validation
snap-list [n] # Show last n snapshots (default: 10)
snap-show <num> # Details for specific snapshot
snap-delete <num> # Delete snapshot + update limine
snap-check-limine # Verify boot menu sync
snap-sync # Manually trigger sync
snap-info # Detailed breakdown by type
snap-validate-service # Check service health
```
**Install limine-snapper-sync:**
```bash
paru -S limine-snapper-sync
sudo systemctl enable limine-snapper-sync.service
```
See [SNAPPER.md](docs/SNAPPER.md) for comprehensive guide.
### Tmux Workspace Manager
```bash
tw <name> # Quick attach or create workspace
tw-create <name> [template] # Create from template
tw-list # List all workspaces
tw-delete <name> # Delete workspace
tw-save <name> # Save current layout as template
tw-sync # Toggle pane synchronization
twf # Fuzzy search workspaces
tw-templates # List available templates
```
**Available Templates:**
- `dev` - 3 panes: vim (50%), terminal (25%), logs (25%)
- `ops` - 4-pane monitoring grid
- `ssh-multi` - 4 panes for multi-server management
- `debug` - 2 panes: main (70%), helper (30%)
- `full` - Single full-screen pane
- `review` - Side-by-side comparison panes
See [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) for advanced workflows.
### SSH Session Manager
```bash
ssh-save <name> <connection> [port] [key] [options] [description]
ssh-connect <name> # Connect with auto-tmux
ssh-list # List all profiles
sshf # Fuzzy search and connect
ssh-delete <name> # Delete profile
ssh-reconnect # Quick reconnect
ssh-sync-dotfiles <name> # Deploy dotfiles to remote
```
---
## Customization
### Adding Aliases
Edit `~/.dotfiles/zsh/.zshrc`:
```bash
# Custom aliases
alias projects='cd ~/projects'
alias k='kubectl'
alias tf='terraform'
```
### Machine-Specific Config
Create `~/.zshrc.local` (not tracked by git):
```bash
# Work machine
export WORK_EMAIL="me@company.com"
# Local paths
export PATH="$HOME/work-tools/bin:$PATH"
```
### Custom Espanso Snippets
Edit `~/.dotfiles/espanso/match/personal.yml`:
```yaml
matches:
- trigger: "..myemail"
replace: "your.email@example.com"
- trigger: "..sig"
replace: |
Best regards,
Your Name
```
### Theme Customization
Edit `~/.dotfiles/zsh/themes/adlee.zsh-theme`:
```zsh
# Change colors
typeset -g COLOR_GREEN='%{$FG[118]%}'
typeset -g COLOR_BLUE='%{$FG[069]%}'
# Change timer threshold (seconds)
typeset -g TIMER_THRESHOLD=10
```
---
## Multi-Machine Setup
### Initial Setup on New Machine
```bash
# Clone your dotfiles
git clone https://github.com/YOUR_USER/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```
### Syncing Changes
**On Machine A (make changes):**
```bash
cd ~/.dotfiles
# Edit files...
dotfiles-sync.sh --push "Added new aliases"
```
**On Machine B (get changes):**
```bash
dotfiles-sync.sh --pull
source ~/.zshrc
```
### Automatic Sync
Enable watch mode (runs in background):
```bash
dotfiles-sync.sh --watch 300 # Check every 5 minutes
```
Or add to crontab:
```bash
*/30 * * * * ~/.dotfiles/bin/dotfiles-sync.sh --auto
```
---
## Troubleshooting
### Run the Doctor First
```bash
dotfiles-doctor.sh --fix
```
### Common Issues
| Issue | Solution |
|-------|----------|
| Theme not loading | Check `ZSH_THEME="adlee"` in .zshrc, run `source ~/.zshrc` |
| Zsh plugins missing | Run `./install.sh` (auto-installs plugins) |
| Command palette not working | Install fzf: `paru -S fzf` |
| Vault errors | Install age: `paru -S age` or gpg: `paru -S gnupg` |
| LastPass not working | Install: `paru -S lastpass-cli` |
| Snapper integration broken | Enable service: `sudo systemctl enable limine-snapper-sync.service` |
| Symlinks broken | Run `./install.sh --skip-deps` to recreate |
### Manual Fixes
**Reinstall zsh plugins:**
```bash
rm -rf ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
rm -rf ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
./install.sh --skip-deps
```
**Reset git config:**
```bash
rm ~/.gitconfig
./install.sh --skip-deps
```
**Fix permissions:**
```bash
chmod +x ~/.dotfiles/install.sh
chmod +x ~/.dotfiles/bin/*
```
### Getting Help
```bash
# Any script
<script> --help
# Examples
./install.sh --help
vault --help
dotfiles-sync.sh --help
dotfiles-stats.sh --help
```
---
## Uninstalling
### Quick Uninstall
```bash
./install.sh --uninstall
```
This will:
1. Remove all symlinks
2. Find and offer to restore backups
3. Keep ~/.dotfiles directory
### Complete Removal
```bash
./install.sh --uninstall --purge
```
This also removes the `~/.dotfiles` directory.
### Manual Uninstall
```bash
# Remove symlinks
rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf ~/.config/nvim
rm ~/.oh-my-zsh/themes/adlee.zsh-theme
rm ~/.local/bin/dotfiles-*.sh
# Restore backups (if any)
ls ~/.dotfiles_backup_*
# Remove dotfiles
rm -rf ~/.dotfiles
# Change shell back to bash
chsh -s /bin/bash
```
---
## Security Notes
- `.gitignore` excludes sensitive files (`.env`, `secrets/`, `*.local`, `vault/`)
- Vault uses strong encryption (age/gpg)
- Never commit API keys or tokens
- Personal espanso snippets may contain sensitive info
- Review `git/.gitconfig` before pushing (contains email)
---
## System Requirements Recap
| Component | Requirement |
|-----------|-------------|
| OS | Arch Linux or CachyOS |
| Shell | Zsh (auto-installed) |
| Package Manager | Pacman (built-in) |
| Editor | Vim (required) |
| Editor | Neovim (optional) |
| Password Manager | LastPass CLI (optional) |
| Encryption | age or gpg (optional, for vault) |
---
For more detailed guides, see:
- [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) - SSH and Tmux integration
- [SNAPPER.md](docs/SNAPPER.md) - Btrfs snapshot management
- [ESPANSO.md](docs/ESPANSO.md) - Text expansion snippets

732
docs/SNAPPER.md
View File

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

674
docs/SSH_TMUX_INTEGRATION.md
View File

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