Skip to content

AI coding · A practical explainer

Git worktrees for AI coding: a local example

Worktrees let two coding attempts start from the same commit in separate directories. They separate working files; they do not create separate machines or cloud accounts.

Edited by Clinton FeyisitanPublished

Review scope: Official Git documentation and four local checks in a disposable repository.

What does a Git worktree isolate?

Git's worktree documentation describes linked working trees with their own HEAD and index while sharing repository data. That lets you inspect one branch in a second directory without switching the files in your original checkout. Git normally refuses to check out the same branch in another worktree.

This is useful for a controlled coding comparison: pin the starting commit, create a branch per attempt and give each attempt the same task. It does not isolate processes, ports, environment variables, credentials or external databases. Shared repository configuration also requires care.

Our executed local example

The script creates a new, disposable repository with one file containing “baseline”. It commits that file, creates trial-a and trial-b from the same commit, then writes “candidate A” only in trial-a. It makes no network calls and invokes no AI assistant.

Four assertions passed: the main file stayed unchanged; trial-b's file stayed unchanged; both trials started at the same commit; and all three directories pointed to a shared Git common directory. The saved output records Git 2.50.1 (Apple Git-155) and the exact starting commit. These are results of this small Git fixture, not evidence of an assistant's code quality.

python3 worktree-demo.py

Set up a real comparison deliberately

  1. Start from a known commit and record its hash. Deal with changes already in your checkout before deciding what belongs in the starting state.
  2. Give each candidate a distinct branch and directory. Use the same task brief and acceptance checks.
  3. Review local configuration and dependency setup. A second directory does not automatically contain ignored files or a configured environment.
  4. Use separate local ports and synthetic data when the applications run at the same time.
  5. Review the final diff and test output from each directory. Save failed attempts and manual repairs as part of the record.

What can still interfere?

Two processes can talk to the same database even when their source files live in different directories. A migration run by one attempt can change the state seen by the other. Both attempts can also use the same credential, model account or quota. A fair comparison must record those shared resources and decide whether to reset or separate them.

The demo avoids these problems by using only a text file. It does not demonstrate a full application, concurrent agent execution, dependency installation or a database rollback. Its narrow scope makes the four assertions easy to inspect and reproduce.

Clean up without discarding evidence

Save the needed diff and outputs first. Git documents removal of clean linked worktrees with git worktree remove; a dirty tree needs attention before removal. Do not force removal as a routine way to finish an experiment. Our script removes only the disposable directory it created through Python's temporary-directory context.

Continue with the repository evaluation protocol and the permission and sandbox checklist. File separation and action permissions solve different parts of the setup.

Sources and scope

Factual explanation and local teaching examples. Source reads and local executions have separate scopes. No native provider workflow, send, payment, deliverability result or comparative winner is claimed. Send a correction.