# Git conventions

- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
- Never force-push `main` or `master`.
- Keep commits atomic. Each commit should represent one logical, independently reviewable and reversible change.
- Ensure every commit leaves the repository in a working state (buildable/testable where practical).
- Commit messages explain **why**, not **what**. The diff already documents what changed.
- Never commit secrets, credentials, or environment-specific config.
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
- Reference related issues, ADRs or design documents using Git trailers when applicable.

## Submodules

- When working with submodules: commit and push the submodule first, then update and push the parent repo. Pushing the parent while the submodule commit doesn't exist on the remote breaks `git submodule update` for anyone who pulls.
- Always use `rtk git` for parent repo operations; drop into the submodule directory for submodule-specific git commands.
- After adding a submodule, check `git status` in both the parent and the submodule — a `-dirty` flag means the submodule has uncommitted local changes that need to be committed before the parent pointer is updated.