bw-copilot-resources/docs/git-bootstrap-hygiene.md

Git Bootstrap Hygiene

Purpose

This guidance helps when a repository is being created, normalized, or cleaned up early in its life so temporary local material does not leak into shared Git history and the first committed shape of the repo is intentional.

Why This Matters

Early repository mistakes tend to persist. Temporary import trees, scratch directories, local caches, and vendor copies are easy to commit accidentally when ignore rules and branch decisions are still unsettled. A small amount of bootstrap hygiene keeps those mistakes out of long-term history.

Core Guidance

• Identify scratch, cache, vendor-copy, and other temporary paths before the first shared commit and keep them untracked unless there is an explicit decision to promote them.
• Confirm the intended default branch before the first shared commit. Use the project's branch policy when one exists; otherwise use a consistent default such as main.
• Make the first tracked commit only after the repository's ignore rules and basic bootstrap layout reflect the intended long-term structure.
• If temporary content later becomes real project content, move or regenerate it into the correct tracked location instead of committing the original scratch tree as-is.
• Keep repo-specific exceptions in repo-local setup notes or docs instead of putting one-off paths, hashes, or names into shared guidance.

Good Outcomes

• The initial history starts from an intentional branch and file layout.
• Local-only material stays local until it is deliberately promoted.
• Repositories keep fewer one-off cleanup commits related to accidental early tracking.
• Shared guidance stays reusable because repo-specific details remain local.

What This Is Not

• It is not a replacement for project-specific setup documentation.
• It does not tell a team which branch policy to adopt; it only says to choose that policy intentionally before the first shared commit.
• It does not forbid generated or vendor content from being tracked when a project intentionally relies on that model.

Typical Signals That This Guidance Applies

• A repository is brand new and the first commit has not happened yet.
• A local import or migration dropped temporary files into the repo root.
• Scratch or cache directories are present and the ignore rules are not settled.
• The team is still deciding how bootstrap files and initial layout should look.

Local Exceptions

When a repository intentionally tracks generated assets, mirrored vendor code, or unusual bootstrap files, document that exception in the repo's own setup or contributing docs instead of weakening the shared rule for every other project.