Git and Worktrees

Git is code source of truth. Forge uses the user's installed git executable rather than an embedded Git implementation.

Why the real Git executable

Worktrees, repository edge cases, Git config, credential helpers, and platform behavior are subtle. Mature agent tools have encountered bugs when Git abstractions made incorrect assumptions about worktrees. Using the actual executable keeps behavior aligned with the user's repository and Git version.

Git service boundary

Only the Git infrastructure package should know raw Git command invocations. Other packages ask for domain-oriented operations such as:

• inspect repository;
• resolve revision;
• status/dirty state;
• create/remove worktree;
• diff revisions;
• branch information;
• merge/rebase operations when those are introduced.

Commands run through the single controlled ProcessRunner boundary.

Stable worktree paths

Do not use mutable Task titles as path identity.

Preferred form:

$XDG_DATA_HOME/forge/worktrees/<project-id>/<task-id>/

The display title can change without invalidating provider state keyed to the path.

Worktree creation is a pipeline

A worktree is not Ready merely because git worktree add returned zero.

Conceptual pipeline:

inspect repository
    ↓
resolve base revision
    ↓
choose stable branch/path
    ↓
add worktree
    ↓
verify expected worktree/revision
    ↓
optional trusted project setup
    ↓
READY

Represent it as a durable operation/lifecycle so partial failure can be reconciled.

Dirty-work invariant

Forge never automatically removes a worktree containing uncommitted/unrecoverable work.

Cleanup eligibility is derived from safety conditions, for example:

Task terminal
+ no active run
+ no pending operation
+ clean/recoverable state
+ no retain flag
= cleanup eligible

Age may influence suggestions but is never the sole permission to destroy work.

Branch/merge edge cases

Git can refuse operations when a target branch is checked out in another worktree. Merge integration must inspect reality and present an actionable state rather than swallowing the error.

Early versions should prefer simple integration rules over speculative stacking/branching optimizations.

Checkpoints

If internal rollback snapshots are later required, prefer hidden refs or another mechanism that does not create fake commits in the user's visible history.

A filesystem/workspace checkpoint is not equivalent to a provider-conversation checkpoint. Revert is permitted only when the selected strategy/environment can keep both sides coherent or when the user explicitly understands the weaker semantics.

Tests

Git tests use real temporary repositories and the installed Git executable. Do not mock Git command output for core behavioral tests.