How scottames/dots works
Project Type and Purpose
• This is an open-source “dotfiles” repository designed to manage user configuration across multiple machines (Linux and MacOS).
• It leverages chezmoi for templated file deployment, nix flakes on Mac, mage for task automation, aqua for version management, and GitHub Actions for CI/CD.
High-Level Components
a. Source Control (GitHub)
• Repository hosting all code and config files
• GitHub Actions workflows under .github/workflows and Trunk configuration under .trunk
b. Configuration Management Engines
• Chezmoi – renders home/ templates to actual dotfiles in the user’s home directory
• Nix Flake (flake.nix) – MacOS configuration with nix-darwin
c. Task Automation
• Magefiles (magefiles/) – Go-based scripts to build, test, lint, and generate assets
• Shell scripts (scripts/init.sh) – bootstrap installer for initial setup
d. Versioned Toolchain Declarations
• Aqua (aqua/*.yaml) – declarative specification of CLI tool versions
e. Helper Libraries
• Go helper package (pkg/helpers) – utilities for file operations, shell execution, Git interactions
f. Local Target Environment
• User home directory (rendered dotfiles, private vs. public templates, executable scripts in home/bin)
• Private overrides (home/private_dot_config, home/private_dot_zsh, etc.)
g. CI/CD and Testing
• Docker container used by mage test to run linters, Go tests, and a headless chezmoi init
• GitHub Actions for release, semantic versioning, dependency updates
Relationships and Data Flows
• Developer pushes changes → GitHub repo → triggers GitHub Actions → runs linters/tests/mage tasks
• On local machine:
• scripts/init.sh fetches repo → invokes chezmoi → reads home/ templates + .chezmoi.toml configuration → writes actual dotfiles
• On Mac: nix flake (nix run .#install) builds and deploys Mac-specific modules
• Mage commands orchestrate Docker-based tests, code generation, policy checks (via aqua), system tweaks (via gsettings.go)
• Aqua reads its YAML registry → installs or pins CLI tools under ~/.local/share/aqua/
• Helper functions (pkg/helpers) are used by magefiles and by any future Go-based extensions.
Architectural Patterns and Principles
• Template-Driven Configuration: home templates + private overrides facilitate separation of public vs. private settings.
• Infrastructure-as-Code: nix flake and aqua YAML manifest the environment declaratively.
• Task Orchestration via Code: magefiles centralize build, test, and CI logic in Go.
• CI/CD as Code: workflows and trunk analyzers enforce linting and versioning policies automatically.