# 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. - **Reset shallow clones against `HEAD`, not `origin/main`.** A single-branch shallow clone (`--depth N`) creates no remote-tracking refs for other branches, so `origin/main` does not exist unless `main` is the branch being cloned. Init/reset logic that does `git reset --hard origin/main` fails on any other branch. Reset against `HEAD` instead — it is branch-agnostic and works regardless of which branch was shallow-cloned. ## 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 ## Rebase Before Manual Commits to a CI-Auto-Bumped Branch/Deploy Repo When CI auto-commits back to the same branch you push to — `[skip ci]` dependency-sync commits, deploy manifests with an image `newTag` bumped by a build job, ArgoCD `chore: deploy` commits — your push races those bots. A push made just after your fetch is rejected as non-fast-forward (`! [rejected] ... (fetch first)`), and on a deploy repo the running image can silently lag `origin/main` by many builds with no obvious error. - **Standard sequence:** `git pull --rebase origin && git push origin `. Rebase (not merge) keeps history linear against the bot commits. - **Expect conflicts in bot-managed files** (dependency manifests, version pins, image tags). Resolve by taking the higher/newer value. - This race also fires immediately after *you* trigger a dependency-sync that CI auto-commits — pull-rebase before pushing your own follow-up. ## Gitea: Use `workflow_dispatch`, Not `repository_dispatch`, for API-Triggered Builds On Gitea (observed 1.25.x), `POST /api/v1/repos///dispatches` (the `repository_dispatch` trigger) returns 404 and never fires the workflow. Trigger builds instead via `POST /api/v1/repos///actions/workflows/.yaml/dispatches` with body `{"ref":"main","inputs":{...}}` (the `workflow_dispatch` trigger). Also don't point a Gitea webhook at the `/dispatches` endpoint to chain builds: Gitea webhooks send the full push-event body (not `{"event_type": ...}`, which the endpoint ignores) and carry no auth header (so the call 401s). Chain builds from an in-CI dispatch step instead. ## PR Governance on Protected Branches - **Don't bypass a `required_approvals` gate to unblock automation.** On a branch protected with `required_approvals: N`, do not self-approve a PR through a second bot account/token to let automation merge. That approval gate is a deliberate production-publish guardrail set by the repo owner; bypassing it defeats its intent. Leave the PR open for a human to approve. (This is distinct from a merge-whitelist misconfiguration, which is a config bug to fix — an approval gate is intentional.) - **Promote a targeted change with a feature branch, never by merging the whole staging branch.** When a protected `main` requires approvals and you need to publish one targeted change, do not push/merge the entire integration branch (e.g. `staging → main`) — that promotes *all* accumulated changes at once. Push a feature branch containing only the targeted change and open a PR against `main`. Keeps the diff reviewable and prevents accidental bulk promotion.