Lesson 09 — Git as code truth

Outcome

Build a narrow GitService around the real Git executable and test it against real temporary repositories.

Why this comes now

Worktree/review correctness depends on exact Git semantics. It deserves a dedicated boundary before worktrees are introduced.

Understand

Forge asks Git questions in domain terms—repository valid? current revision? dirty? diff? branch checked out elsewhere?—rather than letting command strings spread through the code. Git is external mutable reality: another terminal can change it, so important Operations should re-check preconditions close to execution.

Build the real project

1. Add real-temp-repository test helpers (git init, configured test identity, initial commit).
2. Implement repository validation, rev-parse, status/dirty check, branch/ref resolution, and worktree list parsing needed next.
3. Return structured errors with command context but avoid logging secrets.
4. Ensure all calls use ProcessRunner.
5. Add tests with paths containing spaces.

Completion gate

All Git tests use real repositories and the installed Git binary. No core behavior test mocks Git output. Invalid repository and ambiguous/missing ref errors are actionable.

Pitfalls to avoid

Do not embed libgit2/go-git because it looks convenient. Do not assume .git is always a directory; linked worktrees commonly use a file.

References

Required: Git worktree documentation, git rev-parse. Vibe Kanban worktree failure: https://github.com/BloopAI/vibe-kanban/issues/287

Checkpoint

You are ready for worktrees only when Git facts come through one service boundary.