Skip to main content

Git Worktrees in Tempest

Git worktrees are Tempest’s foundation for isolated, parallel development. Each workspace operates in its own git worktree, allowing you to work on multiple branches simultaneously without stashing, switching contexts, or losing uncommitted changes. This page explains exactly how Tempest implements worktrees and manages the supporting infrastructure.

What Are Git Worktrees and Why Tempest Uses Them

A git worktree is a git feature that lets you check out multiple branches into separate directories simultaneously. Unlike traditional branch switching, which requires the working tree to be clean (committing or stashing uncommitted work), worktrees bypass this friction entirely. Tempest uses worktrees for three reasons:
  1. Isolation: Each agent workspace is a separate branch checked out into its own directory. The agent can work freely without affecting your main branch or other open workspaces.
  2. No stashing required: When you open a workspace on branch A, work on branch B in a second workspace, then return to the first, your uncommitted changes on branch A are still there. No git stash pop needed.
  3. Parallel work: Run multiple agents simultaneously on different branches. Each operates in its own worktree and can commit, push, and create pull requests independently.

Worktree Creation: The Complete Flow

When you create a workspace, Tempest runs a series of git and file system operations. The flow below is implemented by create_terminal_worktree_sync in src-tauri/src/lib.rs. Its defining feature is a warm pool: Tempest keeps up to three pre-created worktree slots ready, so starting a session is near-instant instead of waiting on a full checkout.

Step 1: Claim a Warm Worktree (When Available)

Tempest maintains a pool of pre-created worktree slots:
  • Up to 3 slots, each with a 5-minute TTL
  • Staging directories live at .tempest/.warm-<uuid8> on branches named tempest-prep/<uuid8>
If a warm slot is available, claiming it is a rename plus branch reset — session start takes a fraction of a second. If the pool is empty (cold start or pool exhausted), Tempest creates the worktree directly, as described in the next steps.

Step 2: Ensure At Least One Commit Exists

If the repository has no commits, Tempest creates an initial commit (staging all files and committing with a Tempest author identity). This is necessary because git worktree add requires a HEAD reference to branch from.

Step 3: Prune Stale Worktree Metadata

This removes dangling .git/worktrees/<name> references left behind by previous failed or incomplete worktree removals.

Step 4: Register the Worktree (--no-checkout)

This creates the branch, registers the worktree in .git/worktrees/<name>/, and creates the worktree directory without checking out files yet. The materialization (the actual file checkout) then finishes in the background, so the session can spawn immediately rather than blocking on a full checkout. On a cold start this is what makes creation fast: git registers the worktree instantly, and the working tree fills in asynchronously.

Step 5: Exclude the .tempest-pid Sidecar

Tempest writes to the worktree’s git metadata to exclude a process ID sidecar:
The info/exclude file is git’s local-only equivalent to .gitignore. Entries here never enter version control. This prevents the .tempest-pid file (which tracks the session’s shell PID) from showing up as an untracked file in git status.

Step 6: Copy Gitignored-but-Needed Files

Environment files that exist in the project root are copied into the worktree so the agent can access them without committing them:
These files are gitignored in the main project, so git won’t carry them into a newly checked-out worktree. Copying them manually ensures the agent sees credentials and environment configuration without modifying git history. Rather than copying node_modules or .venv (which can be 200-800 MB and tens of thousands of files), Tempest creates links: On Windows:
On Unix/macOS:
Links are instantaneous and share a single on-disk copy. If linking fails (for example, a permission error on Windows), Tempest logs a warning and continues — the worktree is still usable, and the agent can run npm install or create a .venv itself.

Step 8: Validate the Worktree Is Not Empty

If the worktree contains only the .git file and nothing else, Tempest returns an error:
This prevents the agent from opening in a completely empty workspace. If this error appears, commit at least some project files to the main branch first.

The .tempest/ Directory Layout

After worktree creation, the directory structure looks like this:
The .git file inside .tempest/workspace-name/ is a text file containing a gitdir reference:
This tells git where the worktree’s metadata lives, allowing git operations to work correctly from inside the worktree.

Branches and Worktrees: One-to-One Mapping

Tempest creates one worktree per workspace, and each worktree has exactly one associated branch. The mapping is:
  • Worktree name = Branch name (a branchPrefix set in Settings → Git is prepended to branch names)
  • The branch is created at worktree creation time
  • Deleting the worktree does not delete the branch (delete it separately via the Diff pane’s branch menu)
For example, creating a workspace named auth-feature creates:
  • A git branch refs/heads/auth-feature
  • A worktree at .tempest/auth-feature/
  • Both map to the same workspace session
Tempest links node_modules and .venv differently on Windows vs Unix to match platform conventions:

Windows: Directory Junctions

On Windows, Tempest uses the junction crate to create directory junctions:
A junction is a reparse point that appears as a directory shortcut. It is atomic and does not require administrator privileges (unlike NTFS symbolic links which do). The OS treats it as pointing to the target, so reads and writes work transparently. When removing a worktree, Tempest calls std::fs::remove_dir(&link) which strips the reparse point without following it into the real directory. On Unix, Tempest uses standard symbolic links:
These are files that contain a path reference. Following the symlink is the OS’s job; removing it is just rm symlink, which deletes the link without touching the target.

Worktree Removal: Cleanup Order

Removing a worktree is not just rm -rf. Multiple steps ensure directory locks are released and git metadata is cleaned up: Before any directory deletion, junctions and symlinks are stripped:
This is critical on Windows: if you follow a junction into the real node_modules and then call remove_dir_all, the OS will traverse into the target and delete the real dependency directory, corrupting the project.

Step 2: Remove the Worktree via Git

Git removes the worktree directory and deregisters it from .git/worktrees/.

Step 3: Retry with Direct Removal (Windows Fallback)

If git worktree remove fails (common on Windows due to PTY process handle lag), Tempest retries direct removal up to 6 times with 500 ms gaps:
This rides out the PTY child process releasing its CWD handle asynchronously.

Step 4: Last Resort: Shell Command (Windows Only)

If Rust’s fs::remove_dir_all fails after retries with the directory still locked, Tempest falls back to the shell:
The Windows shell’s rmdir can succeed where Rust’s API fails due to subtleties in inherited handle cleanup.

Step 5: Prune Dangling Git Metadata

Removes any .git/worktrees/<name> references left behind if the above steps partially succeeded.

Edge Cases and Error Handling

Uncommitted Changes

When you open a workspace on branch A, make changes, then open a second workspace on branch B, the changes on branch A are preserved in the worktree. They do not affect branch B because each worktree has its own working tree. If you try to delete a worktree with uncommitted changes, Tempest uses --force to ignore them. The uncommitted changes are discarded. If you want to preserve them, commit or stash them first via the Diff pane or terminal.

Detached HEAD State

Worktrees are always on a branch created at creation time. If you manually check out a commit (detaching HEAD), git operations still work; you can commit to the detached HEAD, then switch back to the branch or create a new branch.

Repository With No Commits Yet

If the repository has never been committed to, Tempest creates an initial commit before creating the worktree. This happens during workspace creation and ensures git operations work.

Git Hooks: Co-Author Attribution

When attribution is enabled, Tempest installs a prepare-commit-msg git hook that automatically appends a co-author line to commits. This identifies work done through Tempest.

Hook Installation

The hook is written to the main repository’s hooks directory:
The hook content (installed via write_coauthor_hook):
This hook runs before every commit. It appends the co-author line if it is not already present, ensuring each commit is credited.
The hook is per-repository, not per-worktree. Because all of a project’s worktrees share the same .git directory, the hook affects commits made in any worktree of that repository.

Disabling the Hook

The co-author line is controlled by the Attribution setting (Settings → Attribution). When off, the hook block is removed from the commit flow.

Hook Removal

remove_coauthor_hook strips the Tempest block from .git/hooks/prepare-commit-msg. If nothing else remains, the hook file is deleted entirely. The operation is idempotent — if the hook file is missing or the Tempest block is not present, it succeeds silently.

Summary

Git worktrees in Tempest provide isolated, stash-free parallel development. Each workspace is a separate branch registered at .tempest/<name>/ — often claimed instantly from a warm pool of pre-created slots — with node_modules and .venv linked for performance. Worktree creation validates repository state, copies environment files, and (when attribution is on) installs a repository-level co-author hook. Removal cleans up links, git metadata, and handles Windows process handle lag with retries and fallbacks. The whole system is transparent to the user; the Diff pane and right sidebar provide a high-level view of branches, changes, and commits.