59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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. |