Gerardo Santoveña's dotfiles

My personal dotfiles for a consistent development environment across machines.

🚀 Quick Start

# Clone the repository
git clone git@github.com:gsantovena/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Run quality checks
make check

# Install dotfiles
make install

📋 Features

• Shell Configuration: Zsh with zinit-managed plugins, Oh My Posh prompt, custom aliases, and functions
• Editor Setup: Neovim-only configuration with lazy.nvim plugin management
• Terminal Multiplexer: Tmux configuration with TPM plugin management
• Git Configuration: Custom aliases and templates for efficient workflows
• Package Management: Comprehensive Brewfile for development tools
• Security: Proper secrets management and validation
• Testing: Automated installation validation and security checks

🔧 Installation Options

Using Make (Recommended)

make install-dry       # Preview symlink and backup changes
make install           # Full installation with backup and validation
make quick-install     # Run checks, then install
make install-no-backup # Install only if no existing targets need backup

Direct Script Usage

# Dry run to see what will be changed
./scripts/install-enhanced.sh --dry-run

# Install with backup and validation
./scripts/install-enhanced.sh --backup --verbose

# Force installation (skip validation)
./scripts/install-enhanced.sh --force

📁 Structure

dotfiles/
├── .github/workflows/    # CI/CD automation
├── scripts/             # Installation, test, and validation scripts
├── tests/              # Automated tests
├── home/               # Files symlinked into ~/.* plus shell support
│   ├── aliases         # Shell aliases
│   ├── bash_profile    # Bash configuration
│   ├── exports         # Environment variables
│   ├── functions       # Shell functions
│   ├── git/            # Git templates and hooks
│   ├── gitconfig       # Git configuration
│   ├── screenrc        # GNU Screen configuration
│   ├── zsh/            # Modular Zsh configuration
│   └── zshrc           # Zsh module loader
├── config/             # Directories symlinked into ~/.config/*
│   ├── ghostty/        # Ghostty terminal configuration
│   ├── nvim/           # Neovim configuration
│   ├── ohmyposh/       # Oh My Posh prompt themes
│   └── tmux/           # Tmux configuration
├── docs/               # Extended project documentation
├── Brewfile            # Package management
└── Makefile            # Build automation

🔒 Security Features

Secrets Management

• Environment variables for sensitive data
• Encrypted storage support (GPG/age)
• Pre-commit secret detection
• Comprehensive .gitignore patterns

Automated Security Checks

make security          # Run security validation
./scripts/security-check.sh

Best Practices

• No hardcoded credentials in version control
• Proper file permissions validation
• Email address externalization
• Secure backup procedures

🧪 Testing & Validation

Automated Testing

make test             # Run installation tests
make lint             # Shell script linting
make check            # Complete quality validation

Manual Testing

# Test installation in safe environment
./scripts/test-install.sh

# Validate configurations
git config --file home/gitconfig --list
zsh -n home/zshrc
zsh -n home/zsh/*.zsh

📦 Requirements

Essential

• Git: Version control
• Zsh: Modern shell
• zinit: Zsh plugin manager (bootstrapped automatically by home/zsh/00-zinit.zsh)
• Oh My Posh: Prompt engine using configs from config/ohmyposh/
• Homebrew: Package management (macOS)

Optional

• Neovim: Modern text editor
• shellcheck: Script linting
• bats: Testing framework

Installation Commands

# macOS
brew install git zsh neovim shellcheck oh-my-posh

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git zsh neovim shellcheck
# Install Oh My Posh with your platform package manager or from https://ohmyposh.dev

# Install all Homebrew-managed tools on macOS
brew bundle --file=Brewfile

🔄 Neovim-only editor setup

This repository now uses Neovim as the only tracked editor configuration. The active runtime lives under config/nvim/, with:

• config/nvim/init.vim as the thin entrypoint
• config/nvim/lua/config/* for general editor behavior
• config/nvim/lua/plugins/* for grouped lazy.nvim plugin specs
• config/nvim/coc-settings.json for CoC settings

Supporting Neovim docs:

• docs/nvim/README.md — structure and ownership
• docs/nvim/PLUGIN_AUDIT.md — current plugin inventory
• docs/nvim/PLUGIN_REEVALUATION.md — keep/remove/replace decisions

Setup Neovim Plugins

# Plugins are managed by lazy.nvim and install automatically
# Open Neovim to trigger plugin installation
nvim

# Or manually trigger lazy.nvim
nvim -c "Lazy install" -c "qa"

🧩 Tmux plugin setup

The installer bootstraps TPM into ~/.config/tmux/plugins/tpm. Other tmux plugins are declared in config/tmux/tmux.conf and installed by TPM.

# After installation, reload tmux config
tmux source-file ~/.config/tmux/tmux.conf

# Then press prefix + I inside tmux to install declared plugins

Key improvements

• Better plugin support and performance
• Asynchronous processing
• Modern architecture
• Lua configuration support
• No split ownership between config/nvim/ and legacy Vim files

🏗️ CI/CD & Automation

GitHub Actions

• Automated testing on multiple OS platforms
• Shell script linting with shellcheck
• Security scanning and validation
• Configuration syntax checking

Quality Gates

• Installation validation
• Security compliance
• Cross-platform compatibility
• Performance checks

📚 Customization

Personal vs Work Configuration

# Set environment-specific variables
export WORK_ENVIRONMENT="true"  # in secrets file

# Use in configurations
if [[ "$WORK_ENVIRONMENT" == "true" ]]; then
    # Work-specific settings
fi

Adding New Configurations

1. Add home-level dotfiles under home/, or XDG config directories under config/
2. Update HOME_FILES or CONFIG_FILES in scripts/install-enhanced.sh
3. Test with make test
4. Document any dependencies

🔄 Maintenance

Regular Updates

# Update packages
brew bundle --file=Brewfile

# Update plugins
nvim -c "Lazy update" -c "qa"

# Update tmux plugins
# Press prefix + U inside tmux

# Run health checks
make check

Backup & Recovery

# Create backup before changes
./scripts/install-enhanced.sh --backup

# Restore from backup
cp -r ~/.dotfiles-backup-YYYYMMDD_HHMMSS/.* ~/

🚨 Troubleshooting

Common Issues

Installation fails with permission errors

# Fix ownership
sudo chown -R $USER:$USER ~/.dotfiles

# Check permissions
./scripts/security-check.sh

Symlinks not working

# Verify installation
./scripts/test-install.sh

# Manual verification
ls -la ~/.zshrc ~/.gitconfig ~/.config/nvim ~/.config/ohmyposh

Neovim statusline icons look wrong

# Install a Nerd Font if needed
brew install --cask font-hack-nerd-font

Then select Hack Nerd Font in your terminal profile. In iTerm2: Settings → Profiles → Text → Font.

Zsh prompt or plugins not loading

# Ensure Oh My Posh is installed and the prompt config is linked
brew install oh-my-posh
ls -la ~/.config/ohmyposh/zen.toml

# Re-run the installer if the symlink is missing
make install

# Restart shell
exec zsh

The zinit bootstrap in home/zsh/00-zinit.zsh installs zinit into ${XDG_DATA_HOME:-$HOME/.local/share}/zinit/zinit.git on first shell startup.

Getting Help

• Check GitHub Issues for known problems
• Run make check for comprehensive validation
• Review logs in ~/.logs/ directory

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run quality checks: make check
5. Submit a pull request

Development Workflow

# Set up development environment
git clone your-fork
cd dotfiles

# Make changes
nvim some-config-file

# Test changes
make test

# Run security checks
make security

# Commit and push
git add .
git commit -m "feat: add new configuration"
git push origin feature-branch

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• zinit, Oh My Posh, and Oh My Zsh snippet/plugin communities for shell enhancements
• Vim/Neovim community for editor excellence
• Homebrew maintainers for package management
• Open source contributors who make development better

---

For the current improvement backlog, see docs/DEVOPS_RECOMMENDATIONS.md.