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 oh-my-zsh, custom aliases and functions
• Editor Setup: Neovim-only configuration with lazy.nvim 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

Standard Installation

./install-dotfiles.sh

Enhanced Installation (Recommended)

# 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

Using Make (Recommended)

make install-dry    # Dry run
make install        # Full installation
make check          # Run all quality checks
make quick-install  # Run checks then install

📁 Structure

dotfiles/
├── .github/workflows/    # CI/CD automation
├── scripts/             # Installation and validation scripts
├── tests/              # Automated tests
├── aliases             # Shell aliases
├── bash_profile        # Bash configuration
├── exports             # Environment variables
├── functions           # Shell functions
├── git/                # Git templates and hooks
├── gitconfig           # Git configuration
├── nvim/               # Neovim configuration
├── zshrc               # Zsh configuration
├── 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 gitconfig --list
zsh -n zshrc

📦 Requirements

Essential

• Git: Version control
• Zsh: Modern shell (oh-my-zsh recommended)
• Homebrew: Package management (macOS)

Optional

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

Installation Commands

# macOS
brew install git zsh neovim shellcheck

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git zsh neovim shellcheck

# Install oh-my-zsh
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

🔄 Neovim-only editor setup

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

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

Supporting Neovim docs:

• nvim/README.md — structure and ownership
• nvim/PLUGIN_AUDIT.md — current plugin inventory
• 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"

Key improvements

• Better plugin support and performance
• Asynchronous processing
• Modern architecture
• Lua configuration support
• No split ownership between 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 the file to the repository
2. Update HOME_FILES or CONFIG_FILES in install scripts
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"

# 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

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.

Oh-my-zsh not loading

# Install oh-my-zsh first
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Restart shell
exec zsh

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
vim 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

• Oh-my-zsh community for shell enhancements
• Vim/Neovim community for editor excellence
• Homebrew maintainers for package management
• Open source contributors who make development better

---

Last updated: $(date) For DevOps recommendations and improvements, see DEVOPS_RECOMMENDATIONS.md