Repository design discipline — prevention versus cure

Performance is cheaper at repo creation than retrofitted. Four preventive disciplines: .gitignore, pre-commit hooks, .gitattributes, push protection. The cure is a forced history rewrite that breaks every pinned consumer.

The four disciplines

1. .gitignore. Match dist/, build/, node_modules/, target/, *.bin.
2. Pre-commit hooks. check-added-large-files, check-merge-conflict, check-yaml.
3. .gitattributes. For LFS patterns.
4. Push protection. GitHub/GitLab/gitleaks.

flowchart LR
    A[repo create] --> B[".gitignore"]
    A --> C[".gitattributes"]
    A --> D["pre-commit hooks"]
    A --> E["push protection"]
    B --> F["prevention"]
    C --> F
    D --> F
    E --> F
    F --> G["no rewrite"]

Prevention is four small steps; cure is a forced rewrite that breaks pinned consumers.

Architecture choices

• Monorepo. Cost: large packfile, slow clone. Mitigation: partial + sparse; --depth 1 for CI.
• Multi-repo. Cost: cross-repo refactoring. Mitigation: submodules or tags.
• Hybrid. Monorepo with submodules. Most common in production.

Choice depends on team and release cadence.

When a rewrite is the only fix

• Binary growing. Fix: git lfs migrate.
• Credential committed. Fix: git filter-repo and rotation (PR forks keep old commits).
• Repo split. Fix: git filter-repo --target with subtree filter.

Each rewrite: re-sign tags, notify consumers.

Onboarding runbook

# Onboarding

1. Copy `.gitignore` from `github/gitignore`.
2. Copy `.pre-commit-config.yaml`.
3. Add `.gitattributes`.
4. Enable push protection.
5. Branch protection on `main`.
6. Document architecture.

Six steps, ~30 minutes; prevent rewrites costing 30 engineer-days.

Production discipline

1. Apply the four disciplines at repo creation.
2. Document the architecture choice.
3. Plan rewrites carefully.
4. Audit any merge from outside the discipline.

Cross-course references

• Linux for Production Sysadmins Part XXVI: layout discipline.
• Ansible for Production Sysadmins Part XXXVII: monorepo role layout.
• Terraform for Production Sysadmins Part IX: state version discipline.

Quiz