dotfiles

Dotfiles Documentation

This documentation follows the Diátaxis framework combined with Google’s developer documentation style guide. The documentation is organized into four distinct categories to serve different user needs.

Documentation Structure

🎓 Tutorials

Learning-oriented guides that take you through setting up and using these dotfiles from scratch.

• Getting started with dotfiles - First-time setup guide
• Customizing your shell environment - Personalize your terminal experience

🔧 How-to Guides

Task-oriented recipes for solving specific problems.

• How to add a new git alias
• How to configure GPG signing
• How to update shell plugins
• How to backup and restore settings

📖 Reference

Information-oriented technical descriptions of components.

• Git configuration reference
• Zsh configuration reference
• Environment variables reference
• Directory structure reference

💡 Explanations

Understanding-oriented discussions of concepts and architecture.

• Understanding dotfiles architecture
• Why GNU Stow for dotfile management
• Shell startup sequence explained
• Security considerations

Quick Start

If you’re new to these dotfiles:

1. Start with the Getting started tutorial
2. Review the Architecture explanation to understand the structure
3. Check the How-to guides for specific tasks

Project Overview

This dotfiles repository provides a comprehensive, modular configuration system for macOS development environments. Key features include:

• GNU Stow-based management - Symlink management for easy installation/removal
• Modular organization - Separate configurations for git, zsh, vim, etc.
• Security-first approach - GPG signing, secure credential storage
• Cross-machine compatibility - Works across different macOS systems
• Version controlled - Track changes and rollback when needed

Prerequisites

• macOS 12.0 or later
• Homebrew package manager
• Git 2.32 or later
• GNU Stow 2.3 or later

Support

For issues or questions:

• Check the troubleshooting guide
• Review security considerations
• Submit issues on the project repository

This site is open source. Improve this page.