Why Your Worktree Directory Becomes Unmanageable Past Ten Active Tasks

What unmanageable looks like

Run git worktree list in your repo. If you see more than ten entries and cannot say what each one is for, your setup has become a problem.

The first three worktrees are easy. You remember what each one is for. The fifth is when you start using ls to remember. The tenth is when you delete worktrees you do not recognize, and one of them had uncommitted work.

The pattern is always the same. Worktrees pile up. They do not clean themselves. Each one holds a branch, some untracked files, and sometimes a running agent. Without clear rules, they live forever.

The three rules I use

A worktree is a second copy of your repo where you can work on a branch at the same time as the main copy.

Rule one: worktrees live outside the repo, not inside. A subfolder inside the repo gets indexed by your editor, scanned by your test runner, and picked up by globs. A sibling directory at ../<repo>-worktrees avoids all of that.

Rule two: every worktree is named after its task. Not the date, not the agent, not the file. The task ID is the only name that stays useful for the whole life of the work.

Rule three: cleanup is a separate command, and it never runs by default. Listing and removing are different operations. Dirty worktrees survive one removal attempt and need a second explicit one.

Why each rule exists

The sibling directory exists because of editor indexing. My typecheck once broke in the main repo because an inner worktree held a stale .ts file. The fix is structural, not behavioral.

Task-based naming exists because date-based names stop being meaningful two days later. A date tells me nothing. A task ID like dev-23-epic-add-nestjs-api tells me everything.

Two-step cleanup exists because I have lost work to a single typo. The default is safe. The explicit opt-in is the dangerous path. That is the right default for any operation that deletes files.

What worktree organization does not solve

Organized worktrees do not mean organized work. You can have ten clean worktrees and ten branches that conflict at merge time. Organization is about the filesystem. Coordination is about the plan.

You will still hit merge conflicts. You will still hit logical dependencies between branches. Worktree organization makes cleanup survivable. It does not make the plan correct.

List yours

Run git worktree list. For each entry, write one sentence about the task it belongs to. If any row is blank, that worktree is either finished and should be removed, or forgotten and should be investigated.