Download the PHP package jeffersongoncalves/git-worktree-cli without Composer

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)

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

From source

Usage

Add a worktree

Resolution order: existing local branch → existing remote branch (creates a tracking branch) → new branch from --from or the auto-detected main.

If the repository declares submodules (a .gitmodules file is present), the new worktree runs git submodule update --init --recursive automatically. Disable this with --no-submodules.

--copy and --run make a new worktree usable immediately: copy the local config a fresh checkout lacks (.env, auth.json, signing keys) and run setup commands (composer install, …). Both can be made persistent per repo via the add section of the config file (see Per-repo config):

Clean merged worktrees

Protected branches

Some branches stay merged but should never be cleaned (long-lived develop, staging, release/*, …). The main branch is always skipped automatically; protection is for the extra branches you want to keep.

Two ways to protect, combined as a union on every clean run:

1. Per-run flag — --protect=<branch-or-glob> (repeatable).
2. Per-repo config file — persistent, managed with config:* commands.

The config lives at ~/.config/git-worktree/<owner>-<repo>.json (honoring XDG_CONFIG_HOME; the slug is derived from the origin remote, falling back to the directory name plus a short hash when there is no remote):

--no-config ignores the file for a single run; config:disable (or "enabled": false) turns it off persistently. Either way, --protect flags still apply.

Remove a single worktree

clean removes merged worktrees in bulk; remove targets one by branch name or path, regardless of merge status:

Auto-unlink Herd before removing

If worktrees get linked into Laravel Herd, Herd's nginx site config can linger after the worktree folder is gone. Enable auto-unlink (global setting, applies to remove and clean):

Off by default. When enabled, remove and clean run herd unlink on the worktree path before removing it — warns (does not fail the command) if the herd CLI is missing or the unlink itself errors.

List worktrees

Prune stale records

After a worktree directory is deleted manually, git keeps a stale admin record. Clear them:

Jump to a worktree (shell integration)

path prints a worktree's absolute path so your shell can cd into it:

Install the gwt helper so gwt cd <branch> changes directory for you:

Then: gwt cd feature/login. Any other gwt <args> forwards to git-worktree.

Open a worktree in your editor

Keep the CLI up to date

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

When installed via Composer, use Composer to update:

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:

1. If the worktree is detached or on the main branch itself, it is skipped.
2. If branch tip equals main tip → same as main.
3. If branch tip is an ancestor of main (direct/fast-forward/merge commit) → merged.
4. 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.
5. 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:

1. --main=<name> flag if provided and the ref exists
2. The remote default branch (origin/HEAD)
3. 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

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

1. Merge changes to main — CI builds a fresh builds/git-worktree against the latest tag and commits it back.
2. Create a new GitHub release (tag X.Y.Z, no v prefix).
3. 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.