# Git & Source Control

## Commit Practices

- Use meaningful commit messages; prefer small, focused commits over large batches
- Never commit secrets in plaintext — use SOPS + age or equivalent encryption
- Enable pre-commit hooks where appropriate (secret detection, linting, formatting)

## Pre-Commit Hooks

- Block `local_secrets/` and similar directories from being committed
- Auto-encrypt files matching `.sops.yaml` rules that aren't yet encrypted
- Enable with `git config core.hooksPath .githooks`
- Consider secret detection, linting, and formatting hooks

## GitOps Workflow

- All infrastructure changes should be tracked in Git
- No manual changes without corresponding GitOps manifests — anything applied manually (e.g., `kubectl apply`, `helm install`) should immediately get a corresponding tracked manifest
- For ArgoCD-managed clusters: edit in Git, push, sync — never edit live resources directly

## Remote Conventions

- SSH workflows preferred over HTTPS for Git remotes
- Use SSH config host aliases for multi-user setups (e.g., `gitea.example.com-<user>`)
- Remote URL format: `git@<host-alias>:<org>/<repo>.git`
- Optionally push-mirror to GitHub for public visibility

## Access and Clone Gotchas

- **Org repos require explicit collaborator grants.** Don't assume organizational membership implies write access — verify permissions before setting up automation or CI/CD.
- **Shallow clones break push operations.** `git clone --depth 1` is fine for read-only CI jobs, but pipelines that push artifacts, tags, or mirror to other remotes need full clones.

## Version Management

- Use the latest stable version of dependencies unless pinned for a reason
- Verify versions from live sources (`helm search repo`, upstream docs, package registries) — don't rely on memory
- Document the reason in a comment if a version is intentionally pinned below latest
- Check compatibility matrices before upgrading (e.g., Talos ↔ Kubernetes, framework ↔ runtime)