glossary

Git Worktree

A git feature that allows multiple working directories, each checked out to a different branch, from a single repository, enabling parallel work without stashing or cloning.

explanation

Git worktrees solve the problem of needing to work on two branches simultaneously. Instead of stashing changes, cloning the repository again, or using throwaway merges, you add a worktree: a new working directory linked to the same repository, checked out to a different branch. Each worktree has its own working directory and index, but shares the repository's object store and refs. The main benefit is context switching without overhead. You can have a main worktree on the main branch, a feature branch worktree for active development, and a hotfix worktree for urgent fixes — all side by side, all building independently, without any stashing or commit discarding. Each worktree is just a directory like ../project-hotfix. Worktrees are managed with git worktree add <path> <branch>. Each worktree is recorded in the repository's .git/worktrees directory. When a worktree is no longer needed, git worktree remove <path> cleans it up. A common workflow is to use worktrees for code review: git worktree add ../project-review <pr-branch> creates a side-by-side directory to review a PR branch without disturbing your current work.

examples

git worktree add ../hotfix fix/urgent-login-crash

git worktree add -b new-feature ../feature # create with new branch

git worktree list # list all linked worktrees

git worktree remove ../hotfix # remove a worktree

git worktree prune # clean up stale worktree references

how git-agent helps

git-agent's fast commit workflow complements worktrees nicely. When you finish work in a worktree, git-agent creates atomic commits with conventional messages, keeping each worktree's branch history clean. The consistent commit format also makes it easy to track which worktree produced which commits.

brew install gitagenthq/brew/git-agent

FAQ

Can I have worktrees on the same branch?

No, each worktree must be on a different branch. Git enforces this to prevent conflicts. If you need parallel work on the same branch, use git stash or create a temporary branch from the current state.

Do worktrees use additional disk space?

Each worktree has its own working directory and git index, but they share the repository's object store. This means the actual commit data is not duplicated — only the checked-out files are stored separately, which is the same as having a separate clone.

Can I run git-agent in a worktree?

Yes. Each worktree is a full working directory with its own Git state. git-agent works identically in any worktree — it reads the working-tree diff, plans commits, owns staging, and executes them within the worktree's branch context.

Git stash Git rebase Git merge conflict