dotfiles/docs/SETUP_GUIDE.md

Dotfiles Repository Setup Checklist

Use this checklist to ensure your dotfiles repository is complete and ready to use.

📋 File Structure

Core Files

• README.md - Main documentation (use the artifact provided)
• LICENSE - MIT License file
• .gitignore - Git ignore rules
• install.sh - Main installation script

Zsh Configuration

• zsh/.zshrc - Main zsh config
• zsh/themes/adlee.zsh-theme - Custom theme
• zsh/.zshrc.local.example - Template for local settings (optional)

Espanso Configuration

• espanso/config/default.yml - Espanso settings
• espanso/match/base.yml - Base snippets
• espanso/match/personal.yml - Personal snippets

Git Configuration

• git/.gitconfig - Git settings
• git/.gitignore_global - Global gitignore (optional)

Other Configs

• vim/.vimrc - Vim config (if you use vim)
• tmux/.tmux.conf - Tmux config (if you use tmux)

Utility Scripts

• bin/update-dotfiles - Update script
• bin/setup-espanso.sh - Espanso wizard
• bin/deploy-zshtheme-systemwide.sh - System-wide deployment

Documentation

• docs/SETUP_GUIDE.md - Detailed setup guide
• docs/ESPANSO.md - Espanso reference
• CHECKLIST.md - This file

🔧 Setup Steps

1. Create Directory Structure

cd ~/.dotfiles
mkdir -p zsh/themes
mkdir -p espanso/config espanso/match
mkdir -p git
mkdir -p vim
mkdir -p tmux
mkdir -p bin
mkdir -p docs

2. Create/Copy Configuration Files

• Copy your existing .zshrc to zsh/.zshrc
• Copy your theme to zsh/themes/adlee.zsh-theme
• Copy espanso configs from ~/.config/espanso/ to espanso/
• Copy .gitconfig to git/.gitconfig
• Copy .vimrc to vim/.vimrc (if exists)
• Copy .tmux.conf to tmux/.tmux.conf (if exists)

3. Create Scripts

Download or create these scripts from the artifacts:

• install.sh
• bin/update-dotfiles
• bin/setup-espanso.sh
• bin/deploy-zshtheme-systemwide.sh

Make them executable:

chmod +x install.sh
chmod +x bin/*

4. Create Documentation

• Create README.md (use artifact provided)
• Create docs/SETUP_GUIDE.md (artifact provided earlier)
• Create docs/ESPANSO.md (artifact provided earlier)

5. Create .gitignore

cat > .gitignore << 'EOF'
# OS files
.DS_Store
Thumbs.db

# Backup files
*.backup
*.bak
*~

# Local machine-specific configs
*.local
.zshrc.local

# Sensitive information
.env
.env.*
secrets/

# Optional: Uncomment if personal espanso info is sensitive
# espanso/match/personal.yml

# Espanso backup files
espanso/match/*.backup
EOF

6. Create LICENSE

cat > LICENSE << 'EOF'
MIT License

Copyright (c) 2025 Aaron D. Lee

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
EOF

🐙 GitHub Setup

1. Create Repository

• Go to https://github.com/new
• Name: dotfiles
• Description: "Personal configuration files and automation scripts"
• Visibility: Public or Private
• Don't initialize with README (you already have one)
• Click "Create repository"

2. Initialize Git

cd ~/.dotfiles
git init
git add .
git commit -m "Initial commit: Add dotfiles and custom zsh theme"

3. Add Remote and Push

# Replace adlee-was-taken with your GitHub username
git remote add origin https://github.com/adlee-was-taken/dotfiles.git
git branch -M main
git push -u origin main

4. Update URLs in Files

• Update install.sh - Replace adlee-was-taken in DOTFILES_REPO
• Update README.md - Replace all adlee-was-taken references
• Update docs/SETUP_GUIDE.md - Replace adlee-was-taken

# Quick find all instances
grep -r "adlee-was-taken" .

✅ Verification

Test Local Installation

• Test install script on local machine

  # Dry run first
  bash -n install.sh  # Check for syntax errors
  
  # Then test (will backup existing configs)
  ./install.sh
  

• Verify symlinks were created correctly

  ls -la ~ | grep "^l"  # Show all symlinks in home
  

• Test zsh theme

  source ~/.zshrc
  # Check if prompt looks correct
  

• Test espanso

  espanso status
  # Try typing: ..date
  

Test GitHub Setup

• Clone on a test directory

  cd /tmp
  git clone https://github.com/adlee-was-taken/dotfiles.git test-dotfiles
  cd test-dotfiles
  ./install.sh
  

Test System-wide Deployment

• Check current status

  sudo ./bin/deploy-zshtheme-systemwide.sh --status
  

• Test deployment

  sudo ./bin/deploy-zshtheme-systemwide.sh --current
  

📝 Final Touches

Customize Personal Info

• Edit espanso/match/personal.yml with your info
• Edit git/.gitconfig with your name and email
• Update README.md with your GitHub username
• Update any other personal references

Optional Enhancements

• Add GitHub Actions for linting (optional)
• Add screenshots to README
• Create a demo GIF of the theme
• Add more espanso snippets for your workflow
• Create shell aliases in .zshrc

Security Check

• Ensure no sensitive info in committed files

  # Search for potential secrets
  grep -rE '(password|secret|token|key)' . --exclude-dir=.git
  

• Verify .gitignore is working

  git status  # Should not show .local files or sensitive data
  

🎉 You're Done!

Once all items are checked:

• Commit any final changes

  git add .
  git commit -m "Complete repository setup"
  git push
  

• Test on a second machine (if available)

• Star your own repo (you deserve it! 😄)

• Share with others who might find it useful

📚 Next Steps

• Read through docs/SETUP_GUIDE.md for detailed usage
• Explore docs/ESPANSO.md for all available snippets
• Customize the theme colors in zsh/themes/adlee.zsh-theme
• Add more aliases to .zshrc
• Consider contributing to the espanso community hub

---

Need help? Open an issue in your repository or check the documentation files.