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:- 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.
- 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.
- 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 bycreate_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 namedtempest-prep/<uuid8>
Step 2: Ensure At Least One Commit Exists
Tempest author identity). This is necessary because git worktree add requires a HEAD reference to branch from.
Step 3: Prune Stale Worktree Metadata
.git/worktrees/<name> references left behind by previous failed or incomplete worktree removals.
Step 4: Register the Worktree (--no-checkout)
.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:
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:Step 7: Link Large Dependency Directories
Rather than copyingnode_modules or .venv (which can be 200-800 MB and tens of thousands of files), Tempest creates links:
On Windows:
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:
The .tempest/ Directory Layout
After worktree creation, the directory structure looks like this:
.git file inside .tempest/workspace-name/ is a text file containing a gitdir reference:
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
branchPrefixset 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)
auth-feature creates:
- A git branch
refs/heads/auth-feature - A worktree at
.tempest/auth-feature/ - Both map to the same workspace session
Symlinks and Junctions: Platform-Specific Linking Strategy
Tempest linksnode_modules and .venv differently on Windows vs Unix to match platform conventions:
Windows: Directory Junctions
On Windows, Tempest uses thejunction crate to create directory junctions:
std::fs::remove_dir(&link) which strips the reparse point without following it into the real directory.
Unix/macOS: Symbolic Links
On Unix, Tempest uses standard symbolic links:rm symlink, which deletes the link without touching the target.
Worktree Removal: Cleanup Order
Removing a worktree is not justrm -rf. Multiple steps ensure directory locks are released and git metadata is cleaned up:
Step 1: Remove Directory Links First
Before any directory deletion, junctions and symlinks are stripped: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/worktrees/.
Step 3: Retry with Direct Removal (Windows Fallback)
Ifgit worktree remove fails (common on Windows due to PTY process handle lag), Tempest retries direct removal up to 6 times with 500 ms gaps:
Step 4: Last Resort: Shell Command (Windows Only)
If Rust’sfs::remove_dir_all fails after retries with the directory still locked, Tempest falls back to the shell:
rmdir can succeed where Rust’s API fails due to subtleties in inherited handle cleanup.
Step 5: Prune Dangling Git Metadata
.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 aprepare-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:write_coauthor_hook):
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.