Repository Hygiene for Distributed Infra Teams
In distributed teams, the Git repository is not just a storage bin for code; it is the communication backbone. When you have engineers across time zones, a messy repo isn't just annoying—it's an outage waiting to happen. Here are the policies and guardrails I implement to keep infrastructure repos clean, auditable, and safe.
The "Main" Branch is Sacred
The default branch (main) must always be deployable. If main is broken, the team is blocked. To protect it:
- No direct commits. All changes come via Pull Requests.
- Squash and Merge. We value a clean history over a detailed one. One feature = one commit on
main. - Automated Checks. Linting, unit tests, and security scans (trivy, checkov) must pass before merge.
Commit Discipline
A commit message is a note to your future self (or the poor soul debugging your code at 3 AM). I enforce the Conventional Commits standard:
feat:for new capabilitiesfix:for bug repairschore:for maintenance tasks
This structured format allows us to automate changelog generation and semantic versioning.
Rewriting History (Safely)
Sometimes, you mess up. You commit a secret, or you commit to the wrong branch. Knowing how to surgically repair history is a required skill for senior engineers.
Scenario: Resetting a polluted branch
If a feature branch has diverged too far or contains sensitive data, it is often cleaner to reset it to main and replay the valid changes.
# Backup current state just in case
git branch feat-backup
# Reset local branch to match remote main
git fetch origin
git reset --hard origin/main
Scenario: The "Time Travel" Commit
Occasionally, for audit or migration purposes, we need to backdate a commit (e.g., importing legacy code while preserving original dates). Git allows this via environment variables:
GIT_AUTHOR_DATE="2023-01-01 12:00:00 +0000" \
GIT_COMMITTER_DATE="2023-01-01 12:00:00 +0000" \
git commit -m "Import legacy module"
Note: Use this power sparingly. Manipulating history in shared branches is a fast way to lose team trust.
Tooling as Guardrails
Policies rely on willpower; tooling relies on automation. I use:
- Pre-commit hooks: To format code (prettier, black, gofmt) before it leaves the developer's machine.
- Husky: To enforce commit message standards.
- CODEOWNERS: To automatically request reviews from the right subject matter experts (e.g., security team for IAM changes).
Conclusion
A clean repository is a sign of a disciplined team. It reduces cognitive load, speeds up onboarding, and makes incidents easier to debug. Treat your git history with the same respect you treat your production database.