Git Worktrees & Safe Isolation
Let December make large or risky changes in a separate git worktree, away from your working folder.
This page tells you how December uses git worktrees to keep large or risky changes away from your working folder.
Overview
A large change can touch many files. If a test fails halfway, your working folder can be left in a broken state. A running dev server or an open editor can also break while files change.
A git worktree is a second working folder that is linked to your repository. December can do its work in a worktree. Your own files and your dev server do not change while December works.
December uses two tools for this: enter_worktree and exit_worktree. Your project must be a git repository.
How Worktree Isolation Works
Your working folder December's worktree
─────────────────── ───────────────────
branch: main branch: worktree/refactor-auth
dev server keeps running December edits files here
your uncommitted files stay December runs tests here
└── on exit: cleanup, keep, or merge
- Enter: December makes a worktree in
.december/worktrees/<name>on a new branch,worktree/<name>. December copies your uncommitted changes and your.envfiles into it. - Work: December edits files and runs commands in the worktree. Your working folder does not change.
- Exit: December leaves the worktree with one of three actions:
- cleanup: Delete the worktree and its branch. December discards the changes.
- keep: Commit the changes, keep the branch, and delete the worktree folder. Use the branch for a review or a pull request.
- merge: Commit the changes, merge the branch into your branch, and delete the worktree and the branch.
When December Uses Worktrees
- Large refactors: For example, a change of ORM or a framework upgrade.
- Experiments: Try a fix without changing your current branch.
- Subagents: A subagent can work in its own worktree, so it does not change the files that other agents use.
Manual Worktree Control
To make December use a worktree, ask for it in your prompt:
Move our database models to Prisma 6 in a separate worktree. Keep the branch so I can review it.
If you want the changes merged, say so in the prompt. If you want to review first, ask December to keep the branch.