# 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) - **Commit each implementation phase separately.** For multi-phase milestones, commit at each phase boundary with tests passing. Each commit should be self-contained and independently describable. Phase-by-phase commits surface issues early, keep history bisectable, and make later review and reflection far easier than one large end-of-milestone commit. ## Repo Initialization - **Rename default branch immediately after `git init`.** `git init` still creates `master` on many systems despite `main` being the modern default. Run `git branch -m master main` (or configure `init.defaultBranch = main` globally) before first push — otherwise `git push -u origin main` fails with `src refspec main does not match any`. Bake this into any project-bootstrap script. ## 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 - **Copy hook scripts into `.git/hooks/`; don't symlink.** A symlinked hook resolves to the working-tree file, which changes on every branch switch — hooks then run stale (or wrong-branch) logic. Use an `install-hooks.sh` that copies the source script into `.git/hooks/`, and re-run it whenever the source changes. - **Document the sync-then-commit sequence when hooks require an up-to-date main.** If a pre-commit hook requires local `main` to match `origin/main`, the commit silently blocks when local `main` is even one commit behind. Standard sequence: `git checkout main && git pull --ff-only && git checkout && git rebase main`. ## 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 ## Separate Data Repos from Code Repos for GitOps Controllers When a GitOps controller watches a git repo for declarative state (zone files, policy documents, config blobs), keep that data in a **repo separate from the controller's app code**. Mixing the two means every data change triggers CI builds (container rebuilds, test runs) for no reason, and pollutes the code repo's history with non-code churn. Separation yields: - Pure data commits with no CI noise - Cleaner webhook targeting per-repo - Independent access control for data editors vs code maintainers - Simpler rollback semantics — revert a data change without touching the controller image ## Remote Conventions - SSH workflows preferred over HTTPS for Git remotes - Use SSH config host aliases for multi-user setups (e.g., `gitea.example.com-`) - Remote URL format: `git@:/.git` - Optionally push-mirror to GitHub for public visibility - **Prefer internal hostnames for self-hosted Git remotes on the local network.** SSH push to a self-hosted Git server through a public/VPS hostname can return `kex_exchange_identification: read: Connection reset by peer`, especially during heavy agent activity — VPS routes often have connection limits or rate limiting that fail silently under load. On the local network, use the internal hostname in SSH aliases for heavy push workflows; reserve the public hostname for external access or HTTPS. Test with `ssh -T ` immediately after configuring. ## Cross-User Pushes - **Prefer SSH aliases over temp-URL swaps.** When a repo is owned by user A but your default SSH key authenticates as user B, configure a dedicated SSH host alias (`Host gitea.example.com-userA` with matching private key) and use `git@gitea.example.com-userA:org/repo.git`. Avoid temp-URL-swap (embedding an HTTPS token in the remote URL, pushing, then resetting) — it's clunky, prone to shell-quoting errors, and leaks tokens into reflog/history. - **API-created repos need the SSH user as a collaborator.** If a repo is created via API token (user A) but pushes use an SSH alias authenticating as user B, user B has no access by default. Add the SSH-authenticating user as admin collaborator via API before the first push. Applies to Gitea, GitHub, and any platform where API auth and SSH auth use different identities. ## 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. ## Cross-Remote Hygiene for Multi-Remote Projects When a project has divergent remotes (e.g., local Gitea with granular commits + GitHub with squash-merged PRs), histories diverge and naive merges explode. - **Never `git merge / --allow-unrelated-histories`** — it produces 50+ mass conflicts across unrelated files. - **Import specific files instead:** `git checkout / -- ` brings those paths in as a normal local change. - **Always diff after a bulk checkout.** `git checkout` from a remote silently overwrites locally-modified files with older remote versions with zero warning. Run `git status` and review each touched file before staging; restore with `git checkout HEAD -- ` if an unwanted overwrite happened. - **After an upstream PR squash-merge, reset — don't rebase — local branches to main.** Rebase against a squashed history leaves phantom commits; a clean `git reset --hard origin/main` on the local branch is correct. ## 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) ## Placeholder Conventions in Template-Heavy Repos When files contain multiple templating syntaxes (Go templates `{{ .var }}`, CI variables `${{ }}`, Helm `{{ }}`, etc.), use a distinct placeholder convention for your own substitutions that can't be confused with any templating language: - **Double-underscore:** `__CUSTOMER_NAME__`, `__DOMAIN__` - **All-caps curly brace (no spaces):** `{{CUSTOMER_NAME}}` (distinct from Go's `{{ .Title }}` with spaces and dots) Choose one convention per repo and document it. ## Git Worktrees for Parallel Agent Work When running parallel agents or tasks that modify the same repo: - Give each task its own branch and worktree (`git worktree add .worktrees/ -b `) - Tasks with no dependencies branch from HEAD; tasks with one dependency branch from that dependency's branch - Tasks with multiple dependencies get an octopus merge base branch - Worktrees share the `.git` object store — fast creation, minimal disk usage - Keep containers detached (`docker run -d`, not `--rm`) so logs survive for inspection after exit