Worktree

A wrapper around git to work with worktrees more efficiently.

Overview

The worktree command includes functionality for:

• worktree: Creates and manages Git worktrees for branch-based development workflows
• worktree clone: Clones a Git repository into project_name/[branch]/ where branch is the default branch (main/master/trunk)

Installation

Run the install script to build and install the binaries:

./install.bash

This builds the Go binaries and installs them to ~/bin/. Ensure ~/bin is in your PATH.

./install_completion.bash

This installs the shell completion.

Uninstallation

./uninstall.bash

Removes binary at ~/bin/worktree

Usage

worktree init

Initialize a new project with worktree structure:

worktree init <project-name>

Creates a project directory with a subdirectory named after the main branch (master/main/trunk) and initializes a git repository in that subdirectory.

Examples:

worktree init myproject
worktree init test_project

The resulting structure will be:

.
└── myproject/
    └── master/  (or main/trunk based on git config)
        └── .git/ (newly initialized git repository)

The main branch name is determined from git config (init.defaultBranch) or defaults to 'master' if not configured.

worktree clone

Clone a Git repository:

worktree clone <repository-url>

The repository will be cloned into a directory structure like:

project_name/[branch]/

Where branch is the repository's default branch (main, master, or trunk).

Examples:

worktree clone https://github.com/user/repo.git
worktree clone git@github.com:user/repo.git

worktree

The worktree command creates and manages worktrees at ../[branch] relative to the main repository.

Create a new worktree

Create a worktree with auto-detection (checks remote first, then local, then creates new from HEAD):

worktree <branch-name>

When both remote and local branches exist, the remote branch is prioritized.

List branches

List all branches (local and remote):

worktree list

Delete a worktree

Delete the worktree directory:

worktree -d <branch-name>

Merge and clean up

Merge a branch into the currently checked-out branch and clean up (dry-run by default):

worktree --merge <branch-name>

The dry-run validates that the worktree branch was created from the current branch's lineage. If it was not, the dry-run errors with a hint to checkout the correct branch.

To actually perform the merge and cleanup:

worktree --merge --confirm <branch-name>

Delete branch and worktree

Delete the local branch, remote branch, and worktree (dry-run by default):

worktree --delete <branch-name>

The dry-run shows unique commits that will be lost -- commits not on any other local branch -- rather than comparing against the current branch.

To actually perform the deletion:

worktree --delete --confirm <branch-name>

Workflow: Long-Lived Feature Branch

worktree supports teams that work on a long-lived feature branch instead of master. The --merge command merges into whichever branch is currently checked out, so you can merge worktree branches back into your feature branch rather than master.

Steps

1. Clone or init the repo (lands on master/main):

   worktree clone https://github.com/user/repo.git

2. Create a long-lived feature branch:

   git checkout -b feature_branch

3. Create worktrees from it:

   worktree my-feature

4. Do work in the worktree, commit, and push.

5. Merge the worktree branch back into feature_branch:

   git checkout feature_branch
   worktree --merge my-feature

6. The dry-run validates that my-feature was created from feature_branch's lineage. If it was, the merge proceeds with --confirm.

7. If someone accidentally checks out master and runs --merge, the dry-run detects the mismatch and errors with a hint:

   FAIL: branch 'my-feature' was not created from 'master'
   HINT: checkout 'feature_branch' and try again
   

Options

Flag	Description
-d, --delete-worktree	Delete the worktree directory and clean up empty parent directories
--merge	Merge branch into the current branch and clean up
--delete	Delete branch, remote branch, and worktree
--confirm	Confirm merge or delete operation (required for --merge and --delete)
-h, --help	Show help message

Subcommands

Command	Description
worktree init <project>	Initialize a new project with worktree structure
worktree clone <repo-url>	Clone a repository into project_name/[branch]/ structure
worktree list	List all branches (local and remote)

Autocompletion

The worktree command supports shell autocompletion through Cobra, including the clone subcommand. The worktree command provides branch name autocompletion - when you type worktree <TAB><TAB>, it will automatically suggest available local and remote branch names.

View completion help:

worktree completion --help

Branch Name Completion

The worktree command provides intelligent branch name completion:

• Tab completion after worktree will show all available local and remote branches
• Branches are filtered as you type (e.g., worktree feat<TAB> will only show branches starting with "feat")
• Both local and remote branches are included, with duplicates removed

Directory Structure

After cloning and creating worktrees, your directory structure will look like:

project_name/
├── main/              # Main branch (or master/trunk)
│   └── ...
├── feat/
│   ├── feature-a/     # Worktree for feature-a branch
│   │   └── ...
│   └── feature-b/     # Worktree for feature-b branch
│       └── ...
├── fix/
│   └── bug-fix/       # Worktree for bug-fix branch
│       └── ...
└── docs/
    └── readme/        # Worktree for docs/readme branch
        └── ...

Worktrees can be created from any branch, not just main. For example, if your team works on a long-lived feature_branch:

project_name/
├── feature_branch/   # Long-lived feature branch (instead of main)
│   └── ...
├── feat/
│   ├── feature-a/     # Worktree for feature-a, created from feature_branch
│   │   └── ...
│   └── feature-b/     # Worktree for feature-b, created from feature_branch
│       └── ...
└── fix/
    └── bug-fix/       # Worktree for bug-fix, created from feature_branch
        └── ...

Notes

• All commands must be run from within the main repository (not from a worktree)
• --merge and --delete require --confirm to execute
• Dry-run mode for --merge and --delete includes worktree and branch existence validation
• Dry-run output uses color-coded messages: green (PASS), red (FAIL), yellow (WARNING), blue (INFO)
• Auto-detection prioritizes remote branches, then local branches, then creates new from HEAD