README

git-worktree-cli

CLI tool to audit git worktrees in a repository and report whether each worktree's branch has already been merged into the main branch. Includes a clean command to remove merged worktrees and keep the workspace tidy.

Built with Laravel Zero and modeled on the other CLIs in this monorepo.

Requirements

PHP ^8.2
git available on PATH
A git repository with at least one linked worktree

Install

Global (recommended)

composer global require jeffersongoncalves/git-worktree-cli

The binary git-worktree will be on your PATH as long as Composer's global vendor/bin is in it.

From source

git clone https://github.com/jeffersongoncalves/git-worktree-cli.git
cd git-worktree-cli
composer install

Usage

# Audit the current directory (the default command)
git-worktree

# Audit a specific repo
git-worktree check /path/to/repo

# Force a specific main branch (otherwise auto-detected)
git-worktree check --main=develop

# Only show worktree branches that are NOT merged
git-worktree check --only-unmerged

Clean merged worktrees

# Preview — doesn't touch anything
git-worktree clean --dry-run

# Prompt to confirm, then remove
git-worktree clean

# Skip confirmation + also delete the local branch
git-worktree clean --yes --delete-branch

# Force removal (worktrees with dirty state, branches with -D)
git-worktree clean --yes --delete-branch --force

# Only remove branches directly merged (exclude squash/rebase detection)
git-worktree clean --strict

List worktrees

git-worktree list-worktrees

Keep the CLI up to date

When installed from the released PHAR, self-update from the terminal:

git-worktree self-update          # download and install the latest release
git-worktree self-update --check  # only check, don't install

When installed via Composer, use Composer to update:

composer global update jeffersongoncalves/git-worktree-cli

How the merge check works

For each linked worktree (the main worktree and bare repos are skipped) the tool inspects the branch checked out in that worktree and compares it to the main branch:

If the worktree is detached or on the main branch itself, it is skipped.
If branch tip equals main tip → same as main.
If branch tip is an ancestor of main (direct/fast-forward/merge commit) → merged.
Otherwise git cherry main branch is used to detect squash/rebase merges — if every commit on the branch has an equivalent patch on main, the branch is considered merged.
Anything else is reported as not merged.

ahead/behind counts come from git rev-list --left-right --count between the branch and the main branch.

Main branch detection

In order of priority:

--main=<name> flag if provided and the ref exists
The remote default branch (origin/HEAD)
Conventional names: main, master, develop, trunk

Validation

The command fails fast when:

The target path is not a git repository
The repository has no linked worktrees (only the main checkout)
The main branch cannot be resolved

Development

composer install
composer test       # Pest tests + Pint lint
composer lint       # Auto-fix style
composer build      # Build the PHAR into builds/git-worktree

The PHAR is emitted at builds/git-worktree. The build.yml workflow rebuilds and commits it back to main on every push, using the latest git tag as the embedded version.

Fresh git repositories used by the test suite are created under tests/tmp/ (which is gitignored).

Release

Merge changes to main — CI builds a fresh builds/git-worktree against the latest tag and commits it back.
Create a new GitHub release (tag vX.Y.Z).
The publish-phar.yml workflow attaches git-worktree.phar to the release and update-changelog.yml updates CHANGELOG.md + version.txt.

The self-update command pulls the PHAR asset from the latest release.

jeffersongoncalves / git-worktree-cli

Maintainers

Package info

Fund package maintenance!

Statistics

Security