Skip to main content

​
Git Worktrees

Every run executes in an isolated Git worktree. Your main branch stays clean — no half-finished code, no broken builds, no risk of corruption from a misbehaving agent.

​
How it works

When you run gump run, Gump:
  1. Creates a worktree in .gump/worktrees/run-<uuid>
  2. Attaches it to a temporary branch gump/run-<uuid>
  3. Runs all steps inside this worktree
  4. Commits a snapshot after every agent step
The worktree is a real Git checkout. Agents see the full project — all files, all history. They just work in a separate directory.

​
Snapshots

After each agent step completes, Gump commits the changes with a structured message: 
[gump] step: impl, item: add-healthz, attempt: 1
These commits are internal — you won’t see them on your main branch unless you apply. Each step is tied to a Git commit hash, so you can inspect exactly what any step produced.

​
Parallel worktrees

When parallel: true is set on a foreach, each item gets its own worktree cloned from the current state. Agents work simultaneously in separate directories. After all items complete, Gump merges them back sequentially in declaration order. If two items modify the same file, the merge creates a conflict and the circuit breaker stops the run.

​
Two runs at once

You can run two gump run commands on the same repo simultaneously. Each creates its own worktree and its own run artifacts. No global lock. The only contention point is gump apply — if both runs modify the same files, the second apply will hit a merge conflict (standard Git behavior).

​
Apply

gump apply merges the run’s branch into your current branch: 
gump apply
Gump adds a Gump-Run: <uuid> trailer to the merge commit. You can trace any line of code back to the run that produced it. Gump does not auto-commit on your branch. The merge is staged — you review it and commit (or let Gump’s apply do it with the trailer).

​
Cleanup

Worktrees, branches, and run artifacts accumulate over time. Clean them up: 
# Keep only the last 10 runs
gump gc --keep-last 10
This removes old worktrees and their branches, ledger files, and state bags. Runs that haven’t been applied prompt for confirmation before deletion.

​
Dirty check

Before creating a worktree, Gump checks that your working directory is clean (no uncommitted changes). The .gump/ and .pudding/ directories are excluded from this check — workflow files are config, not source code. If the check fails, Gump tells you what’s dirty and suggests committing or stashing.