Git Bridge

Trellis and Git can coexist in the same directory.

4.0.0+ (ADR 0038): Git is the sole authority over file bytes. The op-log holds provenance — issues, lanes, milestones, decisions, and vcs:gitSync annotations — but cannot materialize or overwrite disk content. Pre-4.0: Git was a downstream mirror of op-log file state; that path is removed.

Trellis still owns semantics on the causal stream; git owns bytes on disk.

Import from Git

Convert an existing Git repository into a Trellis repository:

trellis import --from /path/to/git-repo

Git commits become Trellis milestones, preserving your history while gaining graph-native capabilities.

Export to Git

Export Trellis milestones back to Git commits:

trellis export --to /path/to/output-dir

This creates a Git repository where each Trellis milestone becomes a Git commit.

Ongoing mirror (3.2.5+)

After lane work is promoted to integration, commit the integration working tree to git main:

trellis git sync              # stage working tree + commit (4.0+: no op-log materialization)
trellis git sync --push       # commit + push to configured remote

4.0.0+: sync stages the actual bytes on disk and records a vcs:gitSync { gitCommitHash, gitBranch } annotation. It never replays file ops from the journal onto disk.

Auto-sync on promote

When enabled in .trellis/config.json (default on trellis init):

{
  "git": {
    "syncOnPromote": true,
    "remote": "origin",
    "pushOnClose": false
  }
}

Successful trellis lane promote runs git sync automatically. Optional trellis issue close --confirm --push pushes after close.

Agent rules

• Do not use git stash or manual conflict resolution inside agent lane workflows — use Trellis promote + sync instead.
• Edit under .trellis/worktrees/<shortId>/ when lanes.worktreeBind is on (4.0+: lane bytes live on the lane git branch; promote merges via git).
• Disk edits to tracked files flow through git commits, not file-materializing ops (trellis git sync does not journal unjournaled edits).

See Agent coordination for the full multi-agent workflow.

Coexistence

The .trellis/ directory is independent of .git/. You can use both systems simultaneously during migration.