feat(overrides): fork-friendly customization system #145
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Introduces a wrapper task that checks for three override levels before
running each role:
- vars: loads overrides/{role}/vars/main.yml to merge/override variables
- files: sets _files_path for file operations
- tasks: replaces role entirely with override tasks
Based on approach from PR #144 but centralized in a single wrapper.
Replace direct include_role with include_tasks calling the new wrapper. Tag filtering continues to work via tags: always on wrapper tasks.
Update 7 roles to use _files_path variable with fallback to role_path:
- neovim, claude, opencode, glab: symlink source paths
- zsh, bash, taskfile: stat path checks for OS-specific configs
Pattern: {{ _files_path | default(role_path ~ '/files') }}
Maintains backward compatibility when _files_path is not set.
Create gitignored overrides directory for fork customizations: - README.md documents three override levels (vars, files, tasks) - .gitkeep ensures directory is tracked - Fork users can customize without modifying upstream files
Ignore override content while preserving structure files: - overrides/*/ ignored (user customizations) - .gitkeep and README.md preserved for structure
Convert all roles with implicit file references to use explicit
_files_path variable, enabling fork users to override any role's
config files via overrides/{role}/files/ directory.
Changes across 25 roles:
- Simplify 7 roles that had verbose fallback pattern
- Add _files_path to 18 new roles with copy/synchronize tasks
- Update wrapper to always set _files_path before role execution
Roles updated: 1password, alacritty, awesomewm, bash, bat, borders,
btop, claude, gh, ghostty, git, glab, hammerspoon, kitty, lsd,
neofetch, neovim, opencode, sesh, system, taskfile, tmux, zsh
Make the override system discoverable with prominent documentation: - README.md: Add "Fork This Project" section after Quick Start with override types table and common customizations - overrides/README.md: Expand from 66 to 143 lines with Quick Start workflow, debugging guide, partial override warnings, migration guide for existing forkers - CLAUDE.md: Add override row to "Where to Look" table - docs/README.md: Add Forking & Customization section with link
Ignore personal Claude Code files while preserving custom content: - Ignore: settings, projects/, notepads/, temp .md files - Keep: agents/, skills/, commands/ for repo-specific customizations
Allow forkers to customize the bootstrap script without merge conflicts: - Add DOTFILES_GITHUB_USER and DOTFILES_REPO_NAME variables - Source overrides/dotfiles.conf if present for runtime overrides - Update clone URL to use variables instead of hardcoded values - Update help/version output to reflect configured user - Add dotfiles.conf.example with documented settings - Document bootstrap customization in overrides/README.md Forkers can either edit bin/dotfiles directly or use the config file approach for cleaner upstream merges.
Reorganize overrides directory for clarity and extensibility:
Structure:
overrides/
├── roles/{role}/ # Per-role overrides (vars, files, tasks)
├── config/ # Bootstrap configuration
│ └── dotfiles.conf # User settings (gitignored)
└── README.md
Changes:
- Move role overrides under overrides/roles/ subdirectory
- Move dotfiles.conf to overrides/config/
- Update wrapper task, bin/dotfiles, and all documentation
- Update gitignore patterns for new structure
This schema allows clean separation between role overrides, config,
and future override types (group_vars, pre_tasks, etc).
Wrap file glob patterns in backticks to prevent markdownlint from interpreting them as emphasis markers (*, __tests__, etc).
TechDufus
force-pushed
the
feat/fork-friendly-overrides
branch
from
fbf1340 to
a4963c3
Compare
The freedesktop.org documentation site returns 418 status to automated link checkers (bot detection). Add to ignore patterns since the link is valid but blocked for CI bots.
TechDufus
force-pushed
the
feat/fork-friendly-overrides
branch
from
a4963c3 to
28a4d99
Compare
Document how to create new roles that only exist in overrides/, run via the -t flag. Useful for personal tools or workflows that don't need to be upstreamed.
Document that vars overrides persist in play scope for all subsequent roles. Includes best practices for avoiding variable name collisions.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Inspired by #144 from @noneel - this is a complete implementation of fork-friendly overrides that lets users customize any role without modifying upstream files.
What This Enables
Fork maintainers can now:
All customizations live in
overrides/(gitignored), so pulling upstream is always clean.Directory Schema
Implementation
Uses a wrapper task that intercepts every role execution:
tasks/run_role_with_overrides.ymlchecks for overrides before each role_files_pathvariable so roles use override files when present_files_pathinstead of implicitrole_path/filesDOTFILES_GITHUB_USERfor fork cloningOverride Levels
overrides/roles/{role}/vars/main.ymloverrides/roles/{role}/files/overrides/roles/{role}/tasks/main.ymloverrides/config/dotfiles.confDocumentation
overrides/README.md: Complete guide with debugging, migration, and bootstrap docsChanges
Closes #144