pi-worktrees/DOMAIN.md

DOMAIN.md — Git Worktree Concepts

Git Worktrees

A git worktree is a linked working directory that shares the same repository but checks out a different branch. Multiple worktrees can exist simultaneously, each on its own branch, without switching branches in any of them.

Key Commands

• git worktree list — show all linked worktrees with paths and branches
• git worktree add <path> [branch] — create a new linked worktree
• git worktree add -b <new-branch> <path> — create with a new branch
• git worktree remove <path> — remove a linked worktree (refuses if uncommitted changes)
• git worktree prune — clean up stale entries for deleted worktrees

Terminology

Term	Definition
Main repo	The original repository directory (where .git/ lives for non-bare repos)
Linked worktree	An additional working directory linked to the same repo via git worktree add
Bare repo	A .git/ without a working tree — used as the central store when all worktrees are linked
Detached HEAD	When a worktree checks out a commit directly instead of a branch

Constraints (from git itself)

• You cannot create a nested worktree (worktree inside a worktree).
• Multiple worktrees on the same branch is possible with -f but dangerous and not recommended.
• git worktree remove refuses if there are uncommitted or untracked changes.
• The main repo counts as a "worktree" in git worktree list.

pi Session Concepts

Term	Definition
Session	A conversation context within pi, tied to a specific cwd/branch
Cwd change	When pi changes its working directory (e.g., switching worktrees)
Branch display	The footer indicator showing which git branch pi is tracking
Back-switching	Restoring the previous session when returning to the main repo from a worktree

How Sessions Relate to Worktrees

• Each worktree can have its own session for focused context.
• Switching worktrees updates the branch display automatically (pi reads HEAD from the new cwd).
• Users are offered a choice: create a fresh session or keep the current one.
• Back-switching restores the session that was active before leaving the main repo.