Worktree

worktree is a CLI for people who use Git worktrees as part of their daily development flow and do not want to keep typing the same setup, cleanup, and editor-opening commands over and over.

It wraps the most common worktree tasks into a small workflow-oriented tool:

• create a new worktree from your default base branch
• check out an existing remote branch into its own worktree
• copy local env files into the new worktree
• open the result in your editor automatically
• list, reopen, remove, and clean up worktrees later

This README focuses on the fast path. The documentation website will cover deeper examples, advanced workflows, integrations, and troubleshooting.

Why This Exists

Git worktrees are great when you want multiple branches checked out at once, but the raw commands are still a bit awkward for everyday use. In practice, teams usually want a repeatable flow like this:

1. branch off origin/main
2. create a sibling worktree directory
3. copy .env files
4. open it in the editor
5. clean up stale worktrees later

worktree turns that into a few commands with sensible prompts.

By default, worktrees are created in a sibling folder named <repo>.worktrees, so your main repository stays clean while related worktrees stay easy to find.

Context Switching Without The Tax

One of the biggest wins with worktrees is how fast context switching becomes.

Instead of juggling one checkout and constantly doing this dance:

1. stash current changes
2. switch branches
3. do quick fix
4. switch back
5. unstash and resolve surprises

you keep each task in its own directory and jump between them directly.

That means:

• fewer stash/unstash cycles
• less risk of stash conflicts or forgotten stashes
• less accidental cross-branch contamination
• faster interrupts, reviews, and hotfixes

In short: stop paying a context-switching penalty and stop stashing just to move between tasks.

Install

npm install -g @burglekitt/worktree

Or run it without a global install:

npx @burglekitt/worktree --help

Quick Start

Run the initial configuration once inside a Git repository:

worktree config

The setup flow can configure:

• defaultSourceBranch for new worktrees, such as origin/main
• codeEditor for automatically opening a worktree, such as code

Then create your first worktree:

worktree branch feature/improve-readme

That will:

1. create a new branch from your configured source branch
2. add a Git worktree under <repo>.worktrees/feature/improve-readme
3. copy .env and .env.local files from the main repository
4. open the new worktree in your configured editor, if one is set

Common Workflows

Start a new branch in its own worktree

worktree branch feature/add-bulk-actions

Create from a different source branch:

worktree branch feature/add-bulk-actions --source origin/release/1.4

Check out an existing remote branch

worktree checkout feature/fix-login-timeout

You can also pass the full remote name:

worktree checkout origin/feature/fix-login-timeout

This creates a local tracking branch in a dedicated worktree.

See what worktrees already exist

worktree list

Reopen a worktree in your editor

worktree open feature/add-bulk-actions

If you omit the branch name, the CLI shows an interactive picker.

Remove a worktree

worktree remove feature/add-bulk-actions

Force removal when you already know what you are doing:

worktree remove feature/add-bulk-actions --force

Aliases are also available:

worktree rm feature/add-bulk-actions

Clean up stale worktrees

worktree cleanup

The cleanup command targets worktrees that are considered safe to remove, for example branches whose remote no longer exists or local worktrees with no tracked remote and no pending work.

Commands

Command	What it does
worktree config	Configure defaults like source branch and editor
worktree branch <name>	Create a new branch in a new worktree
worktree checkout <remote-branch>	Check out an existing remote branch into a worktree
worktree list	List known worktrees
worktree open [branch]	Open an existing worktree in your editor
worktree remove [branch]	Remove one or more worktrees
worktree cleanup	Remove stale worktrees that are safe to delete

For command help at any time:

worktree help
worktree help branch

Configuration

Configuration is stored in local Git config under the burglekitt.worktree.* namespace.

Examples:

worktree config defaultSourceBranch origin/main
worktree config codeEditor code
worktree config --list
worktree config --missing

What The README Covers

The README is intentionally optimized for onboarding and everyday usage.

The documentation website should be the place for:

• in-depth walkthroughs
• team conventions and naming strategies
• integration guides
• edge cases and troubleshooting
• richer examples for different repository layouts

Requirements

• Git installed and available on your PATH
• Node.js available to run the CLI
• an existing Git repository where you want to manage worktrees

If you want automatic editor launching, make sure your editor command is available in the shell, for example code for Visual Studio Code.

License

MIT

TODO

• Add config command to configure everything needed
• Add branch command to create new worktrees
• Add remove command to delete worktrees
• Add checkout command to create worktree from a remote branch
• Add list command to list all worktrees
• Add open command to open a worktree in a code editor
• Add cleanup command to cleanup stale worktrees
• Integrate with JIRA for automated branch naming
• Integrate with ClickUp for automated branch naming
• Integrate with Trello for automated branch naming