{"id":42108092,"url":"https://github.com/hamishmorgan/.dotfiles","last_synced_at":"2026-01-26T13:22:58.188Z","repository":{"id":318216725,"uuid":"83802014","full_name":"hamishmorgan/.dotfiles","owner":"hamishmorgan","description":"Cross-platform dotfiles managed with GNU Stow. Automated installation, template-based secrets, and comprehensive testing.","archived":false,"fork":false,"pushed_at":"2026-01-19T17:15:23.000Z","size":4131,"stargazers_count":2,"open_issues_count":26,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-19T23:23:15.006Z","etag":null,"topics":["automation","configuration","dotfiles","shell","stow"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamishmorgan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2017-03-03T13:40:44.000Z","updated_at":"2026-01-11T10:36:26.000Z","dependencies_parsed_at":"2025-10-26T12:18:46.597Z","dependency_job_id":"cfdfb8ff-9b3c-48c2-9a43-3a4838fcdd7d","html_url":"https://github.com/hamishmorgan/.dotfiles","commit_stats":null,"previous_names":["hamishmorgan/.dotfiles"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hamishmorgan/.dotfiles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamishmorgan%2F.dotfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamishmorgan%2F.dotfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamishmorgan%2F.dotfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamishmorgan%2F.dotfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamishmorgan","download_url":"https://codeload.github.com/hamishmorgan/.dotfiles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamishmorgan%2F.dotfiles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28779338,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T11:46:04.308Z","status":"ssl_error","status_checked_at":"2026-01-26T11:46:02.664Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","configuration","dotfiles","shell","stow"],"created_at":"2026-01-26T13:22:57.281Z","updated_at":"2026-01-26T13:22:58.173Z","avatar_url":"https://github.com/hamishmorgan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# .dotfiles\n\n[![CI](https://github.com/hamishmorgan/.dotfiles/workflows/CI/badge.svg)](https://github.com/hamishmorgan/.dotfiles/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Bash](https://img.shields.io/badge/Bash-3.2%2B-green.svg)](https://www.gnu.org/software/bash/)\n[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue.svg)](#prerequisites)\n[![GNU Stow](https://img.shields.io/badge/GNU-Stow-orange.svg)](https://www.gnu.org/software/stow/)\n[![Shell](https://img.shields.io/github/languages/top/hamishmorgan/.dotfiles)](https://github.com/hamishmorgan/.dotfiles)\n\nDotfiles managed with [GNU Stow](https://www.gnu.org/software/stow/).\n\n## Table of Contents\n\n- [.dotfiles](#dotfiles)\n  - [Table of Contents](#table-of-contents)\n  - [Why This Dotfiles Setup?](#why-this-dotfiles-setup)\n  - [Contents](#contents)\n  - [Compatibility](#compatibility)\n  - [Quick Reference](#quick-reference)\n    - [Common Commands](#common-commands)\n    - [Documentation](#documentation)\n    - [Quick Links](#quick-links)\n  - [Packages](#packages)\n  - [Prerequisites](#prerequisites)\n    - [macOS](#macos)\n    - [Linux](#linux)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n  - [Optional Enhancements](#optional-enhancements)\n    - [Git Delta - Enhanced Diff Viewer](#git-delta---enhanced-diff-viewer)\n    - [Set Default Shell](#set-default-shell)\n    - [Modern CLI Tools](#modern-cli-tools)\n      - [eza (modern ls replacement)](#eza-modern-ls-replacement)\n      - [zoxide (smart cd replacement)](#zoxide-smart-cd-replacement)\n  - [Verification](#verification)\n  - [Machine-Specific Configuration](#machine-specific-configuration)\n  - [Updating](#updating)\n  - [Package Management](#package-management)\n  - [Advanced](#advanced)\n  - [Development](#development)\n  - [Disk Cleanup Utility](#disk-cleanup-utility)\n  - [Contributing](#contributing)\n\n## Why This Dotfiles Setup?\n\n- **Safe installation** - Automatic backups before any changes, with rollback on failure\n- **Machine-specific support** - Use `.local` files for per-machine customization without branches\n- **Cross-platform** - Tested on macOS, Ubuntu, and Alpine (BSD-like)\n- **Package-based** - Enable/disable individual configurations as needed\n- **Health monitoring** - Comprehensive diagnostics to verify installation integrity\n- **Standard tooling** - Uses GNU Stow (not custom solution), Bash 3.2 compatible\n\n## Contents\n\n- Installation script with dependency checks\n- Backup of existing files before installation\n- Template-based secrets management\n- macOS and Linux support\n- Health check system for diagnostics and validation\n- Packages: system, git, bash, zsh, fish, tmux, gh, gnuplot, wezterm, bat, rust, ripgrep, cursor\n- CI/CD validation with GitHub Actions\n\n## Compatibility\n\n- **Bash 3.2+**: Works with macOS default bash (no Homebrew bash needed)\n- **Cross-platform**: Tested on Ubuntu, Alpine, and macOS\n- **Bash 3.2 verified**: Explicitly tested in CI to ensure compatibility\n\nThe `dot` script is compatible with Bash 3.2, ensuring it works seamlessly with macOS's default\nbash installation without requiring Homebrew bash. This compatibility is enforced through automated\ntesting on all platforms, including explicit Bash 3.2 validation in CI.\n\n## Quick Reference\n\n### Common Commands\n\n```bash\n./dot install          # Install all dotfiles\n./dot update           # Update and reinstall\n./dot status           # Show status\n./dot health           # Run diagnostics\n./dot packages         # List all packages\n./dot enable rust      # Enable a package\n./dot disable fish     # Disable a package\n```\n\n### Documentation\n\n- **[COMMANDS.md](COMMANDS.md)** - Complete command reference\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute\n- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Developer documentation\n\n### Quick Links\n\n- [Installation](#installation) - Get started in 3 commands\n- [Configuration](#configuration) - Environment variables\n- [Machine-Specific Configuration](#machine-specific-configuration) - Per-machine settings\n- [Package Management](#package-management) - Enable/disable packages\n- [Advanced](#advanced) - Manual stow management\n\n## Packages\n\nAll configurations are organized as packages in the `packages/` directory:\n\n| Package | Description |\n|---------|-------------|\n| **system** | System-wide ignore patterns |\n| **git** | Git configuration and aliases |\n| **bash** | Bash shell configuration |\n| **zsh** | Zsh shell configuration |\n| **fish** | Fish shell configuration |\n| **tmux** | Terminal multiplexer |\n| **gh** | GitHub CLI configuration |\n| **gnuplot** | GNU Plot configuration |\n| **wezterm** | WezTerm terminal emulator |\n| **bat** | Bat syntax highlighter |\n| **rust** | Rust toolchain configuration |\n| **ripgrep** | Ripgrep configuration |\n| **cursor** | Cursor IDE (uses copy-sync) |\n\nEach package has:\n\n- `manifest.toml` - Defines managed files, installation method, and validation rules\n- `README.md` - Package-specific documentation and configuration guide\n\nSee individual package README files for detailed configuration options and usage.\n\n## Prerequisites\n\n### macOS\n\n```bash\n# Install Homebrew (if not already installed)\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Install dependencies\nbrew install stow git tmux zsh\n```\n\nThe `dot` script works with macOS's default bash 3.2, so no additional bash installation is needed.\n\n### Linux\n\n```bash\n# Ubuntu/Debian\nsudo apt update\nsudo apt install stow git tmux zsh\n\n# CentOS/RHEL/Fedora\nsudo yum install stow git tmux zsh\n# or\nsudo dnf install stow git tmux zsh\n```\n\n## Installation\n\n```bash\ngit clone git@github.com:hamishmorgan/.dotfiles.git ~/.dotfiles\ncd ~/.dotfiles\n./dot install\n```\n\nThe installer verifies dependencies, backs up existing files, and creates symlinks. Add `-v` for verbose\nor `-vv` for very verbose output.\n\n## Configuration\n\nEnvironment variables for customization:\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `DOTFILES_MAX_BACKUPS_TO_KEEP` | 10 | Backup retention limit |\n| `DOTFILES_MAX_BACKUPS_TO_DISPLAY` | 5 | Backups shown in status |\n| `DOTFILES_RESTORE_DISPLAY_LIMIT` | 20 | Files shown in restore preview |\n| `DOTFILES_GIT_TIMEOUT` | 60 | Git operation timeout (seconds) |\n| `DOTFILES_CURL_TIMEOUT` | 30 | Curl timeout (seconds) |\n| `DOTFILES_SECRET_FILE_MODE` | 600 | Secret file permissions |\n| `DOTFILES_OUTPUT_PREFIX` | │ | Output indentation character |\n| `DOTFILES_BACKUP_DIR_PREFIX` | backups/dotfiles-backup | Backup directory prefix |\n| `DOTFILES_RESTORE_SAFETY_PREFIX` | backups/dotfiles-pre-restore | Restore safety prefix |\n\n**Examples:**\n\n```bash\n# Keep more backups\nDOTFILES_MAX_BACKUPS_TO_KEEP=20 ./dot install\n\n# Longer timeout for slow networks\nDOTFILES_GIT_TIMEOUT=120 ./dot install\n\n# Plain ASCII output for CI/logs\nDOTFILES_OUTPUT_PREFIX=\"| \" ./dot install\n```\n\n## Optional Enhancements\n\n### Git Delta - Enhanced Diff Viewer\n\n[Git-delta](https://github.com/dandavison/delta) provides syntax-highlighted diffs with side-by-side view.\n\n```bash\n# Install delta\nbrew install git-delta  # macOS\ncargo install git-delta # Other platforms\n\n# Enable in ~/.gitconfig.local\necho '[include]\n    path = ~/.gitconfig.delta' \u003e\u003e ~/.gitconfig.local\n```\n\nSee [packages/git/README.md](packages/git/README.md) for detailed git-delta configuration.\n\n### Set Default Shell\n\n```bash\n# Zsh\nchsh -s $(which zsh)\n\n# Fish\nchsh -s $(which fish)\n\n# Bash (if using Homebrew bash)\nchsh -s /opt/homebrew/bin/bash\n```\n\nLog out and back in for changes to take effect.\n\n### Modern CLI Tools\n\nThe dotfiles include optional integrations for modern CLI tools. These tools are detected automatically and\naliases are configured if installed.\n\n#### eza (modern ls replacement)\n\n[eza](https://github.com/eza-community/eza) - Modern `ls` with icons, git integration, and tree views.\n\n```bash\nbrew install eza      # macOS\ncargo install eza     # Other platforms\n```\n\n**Auto-configured aliases:** `ls`, `ll`, `la`, `lt`, `lta`, `lg`, `lm`, `lz` (falls back to standard `ls` if eza not installed)\n\n#### zoxide (smart cd replacement)\n\n[zoxide](https://github.com/ajeetdsouza/zoxide) - Smarter `cd` command with frecency-based directory jumping.\n\n```bash\nbrew install zoxide      # macOS\ncargo install zoxide    # Other platforms\napk add zoxide          # Alpine\n```\n\n**Auto-configured:** Initializes automatically if installed. Provides `z` command for smart directory navigation and\n`zi` alias for interactive selection.\n\n**Usage:**\n\n```bash\n# Jump to frequently used directories\nz dotfiles              # Jumps to ~/.dotfiles\nz docs                  # Jumps to ~/Documents\nz proj python           # Jumps to ~/projects/python-app\n\n# Interactive selection\nzi dot                  # Shows options matching 'dot'\n\n# Manual database management (optional - zoxide auto-tracks directories)\nzoxide add .            # Add current directory to database\nzoxide remove /path/to/dir  # Remove from database\n```\n\n**Benefits:** Frecency-based navigation (frequent + recent), fuzzy matching, interactive selection, faster navigation\nthan `cd`, learns from usage patterns.\n\n## Verification\n\n```bash\n./dot status    # Quick overview\n./dot health    # Comprehensive diagnostics (9 checks: symlinks, syntax, git, permissions, shell, conflicts, dependencies, backups)\n```\n\nSee [COMMANDS.md](COMMANDS.md) for detailed command documentation.\n\n## Machine-Specific Configuration\n\nThis dotfiles setup supports machine-specific configurations through `.local` files. These files are\ngit-ignored and allow you to customize settings per machine without affecting the shared configuration.\n\n**Setup `.local` files:**\n\n```bash\n# Git (required - name, email, signing)\ncp packages/git/.gitconfig.local.example ~/.gitconfig.local\nnano ~/.gitconfig.local\n\n# Shells (optional - machine-specific aliases, env vars, paths)\ncp packages/bash/.bashrc.local.example ~/.bashrc.local\ncp packages/zsh/.zshrc.local.example ~/.zshrc.local\nnano ~/.config/fish/config_private.fish  # Fish uses different name\n```\n\n**Use cases:** Private API keys, work vs personal customizations, machine-specific tool paths, signing\nconfiguration.\n\n**Auto-appending tools:** Some tools (Shopify dev, tec agent) append to configs. Use `git add -p` to\nskip duplicates when committing.\n\n## Updating\n\n```bash\n./dot update    # Updates gitignore patterns, runs package updates, reinstalls\n```\n\n## Package Management\n\nManage individual packages after installation:\n\n```bash\n./dot packages         # List all packages with status\n./dot enable rust      # Enable a package\n./dot disable fish     # Disable a package\n```\n\n**Copy-sync packages:** The `cursor` package uses copy-sync instead of symlinks. Use `./dot sync cursor`\nto sync settings to Cursor and `./dot pull cursor` to pull changes back.\n\nSee [COMMANDS.md](COMMANDS.md) for complete command documentation.\n\n## Advanced\n\n**Manual stow management:**\n\n```bash\n# Install\nstow --verbose --restow --dir=packages --target=$HOME system git zsh bash fish tmux\n\n# Uninstall  \nstow --verbose --delete --dir=packages --target=$HOME system git zsh bash fish tmux\n```\n\n**Troubleshooting:** Run `./dot health -v` for diagnostics. See [COMMANDS.md](COMMANDS.md) for all commands.\n\n## Development\n\n```bash\nmake deps                # Setup environment\nmake check \u0026\u0026 make test  # Before commit\nmake check               # Before push (fast lint + config validation)\nCLEAN_DOCKER=1 make clean-docker  # Prune Docker cache (opt-in)\nCLEAN_PODMAN=1 make clean-podman  # Prune Podman cache (opt-in)\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [DEVELOPMENT.md](DEVELOPMENT.md) for comprehensive developer documentation.\n\n## Disk Cleanup Utility\n\nDeveloper cache cleanup tool: `./bin/disk-cleanup`\n\n```bash\n./bin/disk-cleanup                      # Interactive\n./bin/disk-cleanup --yes                # Non-interactive (safe)\n./bin/disk-cleanup --yes --aggressive   # Aggressive cleanup\n```\n\n**Cleans:** 25+ tools (Homebrew, npm, Docker, Git, gems, pip, etc.) across 7 categories.\nSee [bin/README.md](bin/README.md) for complete documentation.\n\n## Contributing\n\n**Quick start:**\n\n```bash\ngit clone git@github.com:YOUR_USERNAME/.dotfiles.git ~/.dotfiles\nmake deps\nmake check \u0026\u0026 make test\ngh pr create\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines including adding packages,\nfixing bugs with TDD, and code standards. See [DEVELOPMENT.md](DEVELOPMENT.md) for architecture and\n[COMMANDS.md](COMMANDS.md) for command reference.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamishmorgan%2F.dotfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamishmorgan%2F.dotfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamishmorgan%2F.dotfiles/lists"}