Git Worktree Management
Relevant source files
The following files were used as context for generating this wiki page:
Git Worktree Management in Marginalia provides environment isolation for automated code reviews and triage tasks. The system creates a dedicated git worktree for the bot to run headless Claude Code commands without interfering with the developer's active working directory.
This architecture ensures that polling, branch switching, and local commits happen in a containerized git context. The developer continues working on their primary branch while the bot operates on merge request (MR) branches in the background.
Worktree Architecture and Isolation
Marginalia relies on the git worktree feature to manage multiple checkouts of the same repository. The bot operates within a directory defined by the BOT_WORKTREE_DIR environment variable, which is a linked worktree of the main REPO_LOCAL_PATH.
Isolation Mechanics
- Separation of Concerns: The bot never touches the branch checked out in the developer's main working copy.
- Shared Object Database: Because the bot uses a worktree, it shares the git object database with the main repository. This allows the developer to see branches and commits created by the bot (e.g., triage fixes) immediately in the main checkout.
- Symlink Integration: The worktree includes a
.claudesymlink pointing back to the real checkout. This enables the bot to access shared commands, agents, and settings.
Sources: README.md:14-18, README.md:112-118, PRODUCT.md:27-29
Worktree Lifecycle
The following diagram illustrates how the bot prepares and utilizes the worktree during a poll cycle.
The diagram shows the initialization and cleanup steps required to ensure a stable, isolated environment for each review.
Sources: README.md:112-120
Checkout Strategies
Marginalia manages how branches are checked out in the worktree to prevent conflicts and ensure accuracy.
Standard vs. Detached Checkout
- Standard Checkout: The bot attempts to check out the MR branch locally. If the developer has the same branch checked out in their primary working copy, the bot skips the MR to avoid conflicts.
- Detached Checkout (
BOT_CHECKOUT=detached): The bot checks out the MR's head SHA directly without creating or moving a local branch. This allows the bot to process MRs even if the developer is currently working on that specific branch elsewhere.
Stacked MR Management
For stacked merge requests, the bot fetches upper layers locally to refs/marginalia/stack/<iid>. This allows the review command to verify if issues in a lower layer are settled in a later layer of the stack.
Sources: README.md:118-124, README.md:131-137
Triage and Local Branching
When the bot runs a TRIAGE_COMMAND, it applies relevant fixes directly to the code within the worktree.
Local Commit Workflow
- Identify Fixes: The bot identifies relevant reviewer comments.
- Apply and Commit: It applies fixes in the worktree and commits them locally.
- Branch Naming: Fixes land on a local-only branch named
marginalia/<branch-slug>. - Superseding: If a new triage run occurs and commits nothing, the previous fixes move to
refs/marginalia/superseded/<branch-slug>.
Push Operations
The studio provides an interface to push these local commits to the origin. The ALLOW_PUSH=true setting enables the "Fixes to push" card. Pushes are strictly fast-forward to prevent accidental data loss.
| State | Description |
|---|---|
ready | Fixes sit on top of the current head; push will fast-forward. |
pushed | The remote branch already contains the fixes. |
outdated | The remote branch moved since the triage; a re-run is required. |
none | No local fixes exist for this branch. |
Sources: README.md:154-165, studio/public/openapi.yaml:263-280, examples/commands/triage.md:7-12
Environment Configuration
The behavior of the worktree and its interaction with git is controlled via environment variables.
| Variable | Description | Default |
|---|---|---|
REPO_LOCAL_PATH | The path to your primary git checkout. | Required |
BOT_WORKTREE_DIR | The path where the bot's worktree is created. | Required |
BOT_CHECKOUT | Set to detached to checkout SHAs instead of branches. | N/A |
ALLOW_PUSH | Enables the studio to push local triage commits to origin. | false |
CLAUDE_SANDBOX | Confines bash writes to the worktree and review directories. | true |
Sources: README.md:112-124, README.md:310-320
Security and Tool Containment
The bot executes commands within a sandbox that restricts bash writes to the worktree, the repository's .git folder, and the reviews directory. Git operations are restricted to specific allowed subcommands, and git push is never permitted within the automated headless run.
Sources: README.md:310-320
Summary of Worktree Operations
Git Worktree Management facilitates a "local-first" automation strategy. By utilizing linked worktrees, Marginalia achieves high isolation while maintaining the benefits of a shared object database. This allows automated agents to perform complex git operations—such as checking out different branches and committing code fixes—without disrupting the developer's manual workflow. All destructive actions (cleaning and resetting) are confined to the dedicated bot directory, and all network-modifying actions (pushing) require explicit user approval via the studio.
Sources: README.md:10-14, PRODUCT.md:27-32