December v0.4.19

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
  1. Enter: December makes a worktree in .december/worktrees/<name> on a new branch, worktree/<name>. December copies your uncommitted changes and your .env files into it.
  2. Work: December edits files and runs commands in the worktree. Your working folder does not change.
  3. 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.