Auto-sync from catchthesethighs
This commit is contained in:
adlee-was-taken
531
docs/CONTRIBUTING.md
Normal file
531
docs/CONTRIBUTING.md
Normal file
@@ -0,0 +1,531 @@
|
||||
# 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)
|
||||
396
docs/INDEX.md
Normal file
396
docs/INDEX.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# 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
Normal file
401
docs/QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# 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
|
||||
@@ -1,6 +1,6 @@
|
||||
# Setup Guide
|
||||
|
||||
Complete guide for installing, configuring, and maintaining your dotfiles.
|
||||
Complete guide for installing, configuring, and maintaining your Arch/CachyOS dotfiles.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
@@ -19,14 +19,16 @@ Complete guide for installing, configuring, and maintaining your dotfiles.
|
||||
## Prerequisites
|
||||
|
||||
**Required:**
|
||||
- Arch Linux or CachyOS
|
||||
- Git
|
||||
- Curl
|
||||
- Zsh (installed automatically if missing)
|
||||
- Pacman (built-in)
|
||||
|
||||
**Optional (for full features):**
|
||||
- `fzf` - For command palette and fuzzy finding
|
||||
- `age` or `gpg` - For secrets vault
|
||||
- `gum` - For beautiful setup wizard
|
||||
- `lastpass-cli` - For password manager integration
|
||||
- `nvim` - For Neovim support (Vim is sufficient)
|
||||
|
||||
---
|
||||
|
||||
@@ -54,7 +56,7 @@ The wizard will guide you through:
|
||||
Quick install with defaults:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash
|
||||
git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh
|
||||
```
|
||||
|
||||
### Method 3: Standard Install
|
||||
@@ -73,7 +75,7 @@ cd ~/.dotfiles
|
||||
./install.sh # Interactive install
|
||||
./install.sh --wizard # TUI wizard
|
||||
./install.sh --skip-deps # Skip dependency installation
|
||||
./install.sh --deps-only # Only install dependencies
|
||||
./install.sh --deps-only # Only install dependencies, then exit
|
||||
./install.sh --uninstall # Remove symlinks
|
||||
./install.sh --uninstall --purge # Remove everything
|
||||
./install.sh --help # Show all options
|
||||
@@ -109,14 +111,14 @@ exec zsh
|
||||
# or just close and reopen your terminal
|
||||
```
|
||||
|
||||
### 3. Personalize Espanso (Optional)
|
||||
### 3. Configure LastPass (Optional)
|
||||
|
||||
```bash
|
||||
setup-espanso.sh
|
||||
pw list
|
||||
# First run will prompt you to login
|
||||
# Enter your LastPass email and master password
|
||||
```
|
||||
|
||||
This sets up your personal info for text expansion (email, name, signatures).
|
||||
|
||||
### 4. Set Up Secrets Vault (Optional)
|
||||
|
||||
```bash
|
||||
@@ -155,7 +157,6 @@ USER_GITHUB="yourusername"
|
||||
GIT_USER_NAME="" # Falls back to USER_FULLNAME
|
||||
GIT_USER_EMAIL="" # Falls back to USER_EMAIL
|
||||
GIT_DEFAULT_BRANCH="main"
|
||||
GIT_CREDENTIAL_HELPER="store"
|
||||
|
||||
# ============================================================================
|
||||
# Feature Toggles
|
||||
@@ -167,7 +168,7 @@ INSTALL_ZSH_PLUGINS="true" # zsh-autosuggestions, syntax-highlighting
|
||||
INSTALL_FZF="ask"
|
||||
INSTALL_BAT="ask"
|
||||
INSTALL_EZA="ask"
|
||||
INSTALL_ESPANSO="ask"
|
||||
INSTALL_NEOVIM="ask"
|
||||
SET_ZSH_DEFAULT="ask"
|
||||
|
||||
# ============================================================================
|
||||
@@ -260,7 +261,6 @@ 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 --docker # Docker command breakdown
|
||||
dotfiles-stats.sh --export # Export as JSON
|
||||
|
||||
# Aliases
|
||||
@@ -284,7 +284,7 @@ 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 (defined in aliases.zsh)
|
||||
# Aliases
|
||||
vault set KEY "value"
|
||||
vault get KEY
|
||||
vault list
|
||||
@@ -295,6 +295,32 @@ 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
|
||||
@@ -316,73 +342,19 @@ dfstatus # Show status
|
||||
|
||||
**Auto-check:** On shell start, you'll be notified of available updates.
|
||||
|
||||
### Password Manager Integration
|
||||
|
||||
Unified interface for 1Password, LastPass, and Bitwarden:
|
||||
|
||||
```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 provider # Show which CLI is being used
|
||||
pw lock # Lock session
|
||||
```
|
||||
|
||||
**Interactive selection (requires fzf):**
|
||||
|
||||
```bash
|
||||
pwf # Fuzzy search items, copy password
|
||||
pwof # Fuzzy search items, copy OTP
|
||||
```
|
||||
|
||||
**Configuration in `dotfiles.conf`:**
|
||||
|
||||
```bash
|
||||
INSTALL_1PASSWORD="ask" # Install 1Password CLI (op)
|
||||
INSTALL_LASTPASS="ask" # Install LastPass CLI (lpass)
|
||||
INSTALL_BITWARDEN="ask" # Install Bitwarden CLI (bw)
|
||||
PASSWORD_MANAGER="auto" # auto, 1password, lastpass, or bitwarden
|
||||
```
|
||||
|
||||
**Manual CLI installation:**
|
||||
|
||||
```bash
|
||||
# 1Password
|
||||
brew install --cask 1password-cli # macOS
|
||||
# See: https://1password.com/downloads/command-line/
|
||||
|
||||
# LastPass
|
||||
brew install lastpass-cli # macOS
|
||||
sudo apt install lastpass-cli # Ubuntu
|
||||
|
||||
# Bitwarden
|
||||
brew install bitwarden-cli # macOS
|
||||
npm install -g @bitwarden/cli # Any platform
|
||||
```
|
||||
|
||||
### Dynamic MOTD
|
||||
|
||||
System information displayed on shell start:
|
||||
System information displayed on shell startup:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ ✦ user@hostname Mon Dec 15 14:30│
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ ▲ up:4d 7h ◆ cpu:12% ◇ mem:8.2/32G ⊡ 234G free │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ ◉4 containers ⎇2 dirty ↑3 updates ●dotfiles:✓ │
|
||||
│ ▲ up:4d 7h ◆ load:0.45 ◇ mem:8.2/32G ⊡ 234G free │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Shows:**
|
||||
- Uptime, CPU usage, memory, disk space
|
||||
- Docker containers running
|
||||
- Git repos with uncommitted changes
|
||||
- Available system updates
|
||||
- Dotfiles sync status
|
||||
Shows: uptime, load average, memory, disk space
|
||||
|
||||
**Configuration:**
|
||||
|
||||
@@ -399,120 +371,65 @@ show_motd_mini # Show single-line MOTD
|
||||
motd # Alias for show_motd
|
||||
```
|
||||
|
||||
---
|
||||
### Snapper Integration
|
||||
|
||||
## Command Aliases
|
||||
|
||||
All dotfiles commands have convenient aliases defined in `~/.dotfiles/zsh/aliases.zsh`:
|
||||
|
||||
### Core Commands
|
||||
|
||||
| Alias | Full Command | Description |
|
||||
|-------|--------------|-------------|
|
||||
| `dotfiles` / `dfcd` | `cd ~/.dotfiles` | Go to dotfiles directory |
|
||||
| `dfd` / `doctor` | `dotfiles-doctor.sh` | Run health check |
|
||||
| `dffix` | `dotfiles-doctor.sh --fix` | Auto-fix issues |
|
||||
| `dfs` / `dfsync` | `dotfiles-sync.sh` | Interactive sync |
|
||||
| `dfpush` | `dotfiles-sync.sh --push` | Push local changes |
|
||||
| `dfpull` | `dotfiles-sync.sh --pull` | Pull remote changes |
|
||||
| `dfstatus` | `dotfiles-sync.sh --status` | Show sync status |
|
||||
| `dfu` / `dfupdate` | `dotfiles-update.sh` | Update dotfiles |
|
||||
| `dfv` / `dfversion` | `dotfiles-version.sh` | Show version |
|
||||
| `dfstats` / `stats` | `dotfiles-stats.sh` | Shell analytics |
|
||||
| `tophist` | `dotfiles-stats.sh --top` | Top commands |
|
||||
| `suggest` | `dotfiles-stats.sh --suggest` | Alias suggestions |
|
||||
| `dfcompile` | `dotfiles-compile.sh` | Compile zsh for speed |
|
||||
|
||||
### Vault Commands
|
||||
|
||||
| Alias | Full Command | Description |
|
||||
|-------|--------------|-------------|
|
||||
| `vault` | `dotfiles-vault.sh` | Vault CLI |
|
||||
| `vls` | `dotfiles-vault.sh list` | List secrets |
|
||||
| `vget` | `dotfiles-vault.sh get` | Get secret |
|
||||
| `vset` | `dotfiles-vault.sh set` | Set secret |
|
||||
|
||||
### Quick Edit
|
||||
|
||||
| Alias | Description |
|
||||
|-------|-------------|
|
||||
| `zshrc` | Edit ~/.zshrc |
|
||||
| `dfconf` | Edit dotfiles.conf |
|
||||
| `dfedit` | Open dotfiles in editor |
|
||||
| `reload` / `rl` | Reload shell config |
|
||||
|
||||
### CLI Wrapper
|
||||
|
||||
The `dotfiles-cli` (alias: `dfc`) provides a unified interface:
|
||||
Btrfs snapshot management for Arch/CachyOS with limine bootloader:
|
||||
|
||||
```bash
|
||||
dfc doctor # Run health check
|
||||
dfc sync # Sync dotfiles
|
||||
dfc update # Update dotfiles
|
||||
dfc version # Show version
|
||||
dfc stats # Shell analytics
|
||||
dfc vault # Secrets manager
|
||||
dfc compile # Compile zsh for speed
|
||||
dfc edit # Open in editor
|
||||
dfc cd # Go to dotfiles dir
|
||||
dfc help # Show help
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shell Optimization
|
||||
|
||||
The `.zshrc` is optimized for fast startup while maintaining full functionality.
|
||||
|
||||
### Measuring Startup Time
|
||||
**Install limine-snapper-sync:**
|
||||
|
||||
```bash
|
||||
# Quick measurement
|
||||
time zsh -i -c exit
|
||||
|
||||
# More accurate (requires hyperfine)
|
||||
hyperfine 'zsh -i -c exit'
|
||||
paru -S limine-snapper-sync
|
||||
sudo systemctl enable limine-snapper-sync.service
|
||||
```
|
||||
|
||||
### Compile Zsh Files
|
||||
See [SNAPPER.md](docs/SNAPPER.md) for comprehensive guide.
|
||||
|
||||
Pre-compile `.zsh` files to bytecode for 20-50ms speedup:
|
||||
### Tmux Workspace Manager
|
||||
|
||||
```bash
|
||||
dfcompile # Compile all zsh files
|
||||
dfcompile --clean # Remove compiled files
|
||||
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
|
||||
```
|
||||
|
||||
### Loading Strategy
|
||||
**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
|
||||
|
||||
| Phase | What Loads | Timing |
|
||||
|-------|------------|--------|
|
||||
| **Immediate** | PATH, history, oh-my-zsh, basic aliases, keybindings | Blocks prompt |
|
||||
| **Deferred** | Tool aliases (eza, bat), FZF, smart-suggest, snapper, vault | After first prompt |
|
||||
| **Background** | Dotfiles sync check | Fully async |
|
||||
| **Lazy** | NVM, kubectl, virtualenvwrapper | When first used |
|
||||
See [SSH_TMUX_INTEGRATION.md](docs/SSH_TMUX_INTEGRATION.md) for advanced workflows.
|
||||
|
||||
### Profiling
|
||||
### SSH Session Manager
|
||||
|
||||
To debug slow startup, edit `~/.zshrc`:
|
||||
|
||||
```zsh
|
||||
# Uncomment at the TOP of file:
|
||||
zmodload zsh/zprof
|
||||
|
||||
# Uncomment at the BOTTOM of file:
|
||||
zprof
|
||||
```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
|
||||
```
|
||||
|
||||
Then run `zsh -i -c exit` to see timing breakdown.
|
||||
|
||||
### Tips for Fast Startup
|
||||
|
||||
1. **Run `dfcompile`** after installation
|
||||
2. **Avoid adding** `command -v` checks in `.zshrc` (use `_has_cmd` cache instead)
|
||||
3. **Use lazy loading** for heavy tools (NVM, kubectl already lazy-loaded)
|
||||
4. **Keep `.zshrc.local`** minimal
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
@@ -534,7 +451,6 @@ Create `~/.zshrc.local` (not tracked by git):
|
||||
|
||||
```bash
|
||||
# Work machine
|
||||
export CORP_PROXY="http://proxy:8080"
|
||||
export WORK_EMAIL="me@company.com"
|
||||
|
||||
# Local paths
|
||||
@@ -628,11 +544,11 @@ dotfiles-doctor.sh --fix
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Theme not loading | Check `ZSH_THEME="adlee"` in .zshrc, run `source ~/.zshrc` |
|
||||
| Zsh plugins missing | Run `./install.sh` (auto-installs plugins now) |
|
||||
| Command palette not working | Install fzf: `./install.sh` will prompt |
|
||||
| Vault errors | Install age: `brew install age` or `pacman -S age` |
|
||||
| Espanso not expanding | Run `espanso status`, then `espanso restart` |
|
||||
| Sync conflicts | Run `dotfiles-sync.sh --conflicts` to see conflicts |
|
||||
| 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
|
||||
@@ -669,7 +585,7 @@ chmod +x ~/.dotfiles/bin/*
|
||||
./install.sh --help
|
||||
vault --help
|
||||
dotfiles-sync.sh --help
|
||||
shell-stats.sh --help
|
||||
dotfiles-stats.sh --help
|
||||
```
|
||||
|
||||
---
|
||||
@@ -699,10 +615,9 @@ This also removes the `~/.dotfiles` directory.
|
||||
|
||||
```bash
|
||||
# Remove symlinks
|
||||
rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
|
||||
rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf ~/.config/nvim
|
||||
rm ~/.oh-my-zsh/themes/adlee.zsh-theme
|
||||
rm -rf ~/.config/espanso
|
||||
rm ~/.local/bin/dotfiles-*.sh ~/.local/bin/vault.sh ~/.local/bin/shell-stats.sh
|
||||
rm ~/.local/bin/dotfiles-*.sh
|
||||
|
||||
# Restore backups (if any)
|
||||
ls ~/.dotfiles_backup_*
|
||||
@@ -710,86 +625,37 @@ ls ~/.dotfiles_backup_*
|
||||
# Remove dotfiles
|
||||
rm -rf ~/.dotfiles
|
||||
|
||||
# Optional: Remove oh-my-zsh
|
||||
rm -rf ~/.oh-my-zsh
|
||||
|
||||
# Change shell back to bash
|
||||
chsh -s /bin/bash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Reference
|
||||
|
||||
### Symlinks Created
|
||||
|
||||
| Source | Target |
|
||||
|--------|--------|
|
||||
| `~/.dotfiles/zsh/.zshrc` | `~/.zshrc` |
|
||||
| `~/.dotfiles/zsh/themes/adlee.zsh-theme` | `~/.oh-my-zsh/themes/adlee.zsh-theme` |
|
||||
| `~/.dotfiles/git/.gitconfig` | `~/.gitconfig` |
|
||||
| `~/.dotfiles/vim/.vimrc` | `~/.vimrc` |
|
||||
| `~/.dotfiles/tmux/.tmux.conf` | `~/.tmux.conf` |
|
||||
| `~/.dotfiles/espanso/` | `~/.config/espanso` |
|
||||
| `~/.dotfiles/bin/dotfiles-*.sh` | `~/.local/bin/dotfiles-*.sh` |
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/.dotfiles/
|
||||
├── bin/ # Core scripts (symlinked to ~/.local/bin)
|
||||
│ ├── dotfiles-doctor.sh
|
||||
│ ├── dotfiles-stats.sh
|
||||
│ ├── dotfiles-sync.sh
|
||||
│ ├── dotfiles-update.sh
|
||||
│ ├── dotfiles-vault.sh
|
||||
│ └── dotfiles-version.sh
|
||||
├── setup/ # Setup scripts (not symlinked)
|
||||
│ ├── setup-wizard.sh
|
||||
│ └── setup-espanso.sh
|
||||
├── zsh/
|
||||
│ ├── .zshrc
|
||||
│ ├── aliases.zsh # Dotfiles command aliases
|
||||
│ ├── themes/
|
||||
│ │ └── adlee.zsh-theme
|
||||
│ └── functions/
|
||||
│ ├── command-palette.zsh
|
||||
│ ├── motd.zsh
|
||||
│ ├── password-manager.zsh
|
||||
│ ├── smart-suggest.zsh
|
||||
│ └── snapper.zsh
|
||||
├── espanso/
|
||||
│ └── match/
|
||||
│ ├── base.yml
|
||||
│ └── personal.yml
|
||||
├── vault/ # Encrypted secrets (gitignored)
|
||||
├── docs/
|
||||
├── dotfiles.conf
|
||||
└── install.sh
|
||||
```
|
||||
|
||||
### Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `dotfiles.conf` | Central configuration |
|
||||
| `zsh/.zshrc` | Main shell config |
|
||||
| `zsh/aliases.zsh` | Command aliases |
|
||||
| `zsh/themes/adlee.zsh-theme` | Prompt theme |
|
||||
| `zsh/functions/smart-suggest.zsh` | Typo correction |
|
||||
| `zsh/functions/command-palette.zsh` | Fuzzy launcher |
|
||||
| `zsh/functions/motd.zsh` | Dynamic MOTD |
|
||||
| `zsh/functions/password-manager.zsh` | Password manager integration |
|
||||
| `espanso/match/base.yml` | Text expansion snippets |
|
||||
| `espanso/match/personal.yml` | Personal snippets |
|
||||
| `vault/` | Encrypted secrets (gitignored) |
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
- `.gitignore` excludes sensitive files (`.env`, `secrets/`, `*.local`, `vault/`)
|
||||
- Vault uses strong encryption (age/gpg)
|
||||
- Never commit API keys or tokens
|
||||
- Review `git/.gitconfig` before pushing (contains email)
|
||||
- Personal espanso snippets may contain sensitive info
|
||||
- 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 (1).md
Normal file
732
docs/SNAPPER (1).md
Normal file
@@ -0,0 +1,732 @@
|
||||
# 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)
|
||||
895
docs/SNAPPER.md
895
docs/SNAPPER.md
@@ -1,283 +1,732 @@
|
||||
# Snapper Snapshot Management
|
||||
# Snapper Integration Guide
|
||||
|
||||
Zsh functions for managing btrfs snapshots with limine-snapper-sync integration on CachyOS/Arch.
|
||||
Complete guide to managing Btrfs snapshots with Snapper on Arch/CachyOS with limine bootloader integration.
|
||||
|
||||
## Requirements
|
||||
## Table of Contents
|
||||
|
||||
- Btrfs filesystem with snapper configured
|
||||
- `limine-snapper-sync` package (AUR)
|
||||
- Snapper config named "root"
|
||||
- Limine bootloader
|
||||
- [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)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
## Overview
|
||||
|
||||
| Command | Alias | Description |
|
||||
|---------|-------|-------------|
|
||||
| `snap-create "desc"` | `snap` | Create snapshot + validate limine entry |
|
||||
| `snap-list [n]` | `snapls` | Show last n snapshots (default: 10) |
|
||||
| `snap-show <num>` | `snapshow` | Details for specific snapshot |
|
||||
| `snap-delete <num>` | `snaprm` | Delete snapshot + update limine |
|
||||
| `snap-check-limine` | `snapcheck` | Verify boot menu sync status |
|
||||
| `snap-sync` | `snapsync` | Manually trigger limine sync |
|
||||
| `snap-info` | `snapinfo` | Detailed breakdown by type |
|
||||
| `snap-validate-service` | - | Check service health |
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
## Prerequisites
|
||||
|
||||
### Create Before Updates
|
||||
### 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
|
||||
snap-create "Before system update"
|
||||
# or using alias:
|
||||
snap "Before system update"
|
||||
# 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 Snapshot Creation & Validation ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
|
||||
==> Checking limine.conf state before snapshot
|
||||
✓ Before: 5 snapshot entries
|
||||
✓ Before checksum: a1b2c3d4...
|
||||
|
||||
==> Creating snapshot: "Before system update"
|
||||
✓ Snapshot created: #42
|
||||
|
||||
==> Triggering limine-snapper-sync service...
|
||||
✓ Service triggered successfully
|
||||
|
||||
==> Validating limine.conf update
|
||||
✓ limine.conf was updated
|
||||
✓ Added 1 new snapshot entry
|
||||
✓ Found snapshot #42 in limine.conf
|
||||
|
||||
╔════════════════════════════════════════════════════════════╗
|
||||
║ Summary ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
Snapshot Number: #42
|
||||
Description: "Before system update"
|
||||
Status: ✓ VALIDATED
|
||||
✓ snapper installed
|
||||
✓ limine-snapper-sync installed
|
||||
✓ limine-snapper-sync enabled
|
||||
✓ limine-snapper-sync running
|
||||
✓ Snapper configs: root, home
|
||||
```
|
||||
|
||||
### Check Boot Menu Sync
|
||||
---
|
||||
|
||||
## Basic Commands
|
||||
|
||||
### Create Snapshots
|
||||
|
||||
```bash
|
||||
snap-check-limine
|
||||
# or:
|
||||
snapcheck
|
||||
# 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"
|
||||
```
|
||||
|
||||
Shows:
|
||||
- All snapshots in limine.conf
|
||||
- Comparison with snapper list
|
||||
- Missing entries (if any)
|
||||
- Sync status
|
||||
|
||||
### List Recent Snapshots
|
||||
### List Snapshots
|
||||
|
||||
```bash
|
||||
snap-list # Last 10
|
||||
snap-list 20 # Last 20
|
||||
# or:
|
||||
snapls 20
|
||||
# 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
|
||||
# or:
|
||||
snapshow 42
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Snapshot info from snapper
|
||||
- Corresponding entry in limine.conf
|
||||
|
||||
### Delete Snapshot
|
||||
|
||||
```bash
|
||||
snap-delete 42
|
||||
# or:
|
||||
snaprm 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
|
||||
```
|
||||
|
||||
Automatically:
|
||||
- Deletes snapshot from snapper
|
||||
- Triggers limine-snapper-sync
|
||||
- Verifies removal from boot menu
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **`snap-create`** calls `snapper -c root create`
|
||||
2. Triggers `limine-snapper-sync.service`
|
||||
3. Validates that `/boot/limine.conf` was updated
|
||||
4. Shows the new boot entry
|
||||
|
||||
The limine bootloader can then boot any snapshot directly from the boot menu.
|
||||
|
||||
---
|
||||
|
||||
## Snapshot Types
|
||||
|
||||
| Type | Created By |
|
||||
|------|------------|
|
||||
| `single` | Manual (your `snap-create` calls) |
|
||||
| `pre` | Auto before package operations |
|
||||
| `post` | Auto after package operations |
|
||||
|
||||
View breakdown with `snap-info` or `snapinfo`.
|
||||
|
||||
---
|
||||
|
||||
## Pre/Post System Changes Workflow
|
||||
### Delete Snapshots
|
||||
|
||||
```bash
|
||||
# Before risky change
|
||||
snap "Before kernel update"
|
||||
# Delete single snapshot
|
||||
snap-delete 40
|
||||
|
||||
# Make changes
|
||||
# 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
|
||||
|
||||
# If something breaks:
|
||||
# 1. Reboot
|
||||
# 2. Select snapshot from limine boot menu
|
||||
# 3. System restored to pre-update state
|
||||
# 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
|
||||
|
||||
### Snapshot Created but Not in Boot Menu
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
snap-validate-service
|
||||
|
||||
# Manual sync
|
||||
snap-sync
|
||||
# or:
|
||||
snapsync
|
||||
|
||||
# Verify
|
||||
snap-check-limine
|
||||
```
|
||||
|
||||
### Service Not Running
|
||||
|
||||
```bash
|
||||
sudo systemctl enable limine-snapper-sync.service
|
||||
sudo systemctl start limine-snapper-sync.service
|
||||
```
|
||||
|
||||
### Boot Menu Has Stale Entries
|
||||
|
||||
```bash
|
||||
# Delete old snapshot
|
||||
snap-delete 42
|
||||
|
||||
# This auto-triggers sync to remove from limine.conf
|
||||
```
|
||||
|
||||
### Check Service Logs
|
||||
|
||||
```bash
|
||||
sudo journalctl -u limine-snapper-sync.service -n 50
|
||||
```
|
||||
|
||||
### Validate Everything
|
||||
### Verify Snapper Installation
|
||||
|
||||
```bash
|
||||
snap-validate-service
|
||||
```
|
||||
|
||||
This checks:
|
||||
- Service unit exists
|
||||
- Service is enabled
|
||||
- Snapper config exists
|
||||
- limine.conf exists
|
||||
- Current sync status
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Functions are sourced from `~/.dotfiles/zsh/functions/snapper.zsh`.
|
||||
|
||||
Settings in `~/.dotfiles/dotfiles.conf`:
|
||||
### Check Snapper Configs
|
||||
|
||||
```bash
|
||||
SNAPPER_CONFIG="root"
|
||||
LIMINE_CONF="/boot/limine.conf"
|
||||
```
|
||||
sudo snapper list-configs
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
- Only works with **limine bootloader**
|
||||
- Requires snapper config named **"root"**
|
||||
- `limine-snapper-sync` typically limits boot entries to recent snapshots (intentional to prevent menu clutter)
|
||||
|
||||
---
|
||||
|
||||
## Installing limine-snapper-sync
|
||||
|
||||
On Arch/CachyOS:
|
||||
|
||||
```bash
|
||||
# If using paru
|
||||
paru -S limine-snapper-sync
|
||||
|
||||
# If using yay
|
||||
yay -S limine-snapper-sync
|
||||
|
||||
# Enable service
|
||||
sudo systemctl enable limine-snapper-sync.service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manual Snapper Commands
|
||||
|
||||
If you need to use snapper directly:
|
||||
|
||||
```bash
|
||||
# List all snapshots
|
||||
sudo snapper -c root list
|
||||
|
||||
# Create snapshot
|
||||
sudo snapper -c root create --description "My snapshot"
|
||||
|
||||
# Delete snapshot
|
||||
sudo snapper -c root delete 42
|
||||
|
||||
# Compare snapshots
|
||||
sudo snapper -c root diff 41..42
|
||||
|
||||
# Show snapper config
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Boot Recovery
|
||||
## Best Practices
|
||||
|
||||
If your system won't boot:
|
||||
### Before Major Operations
|
||||
|
||||
1. At limine boot menu, select a snapshot
|
||||
2. System boots into that snapshot state
|
||||
3. Once booted, you can:
|
||||
- Fix the issue
|
||||
- Roll back permanently with `snapper rollback`
|
||||
- Create a new snapshot of the working state
|
||||
```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
Normal file
674
docs/SSH_TMUX_INTEGRATION.md
Normal file
@@ -0,0 +1,674 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user