@j4k-oss/worktree-remove (1.4.12)
Installation
@j4k-oss:registry=npm config set @j4k-oss:registry=npm install @j4k-oss/worktree-remove@1.4.12"@j4k-oss/worktree-remove": "1.4.12"About this package
worktree-remove
Source: https://code.j4k.dev/j4k-oss/worktree-remove. github.com/Jercik/worktree-remove is a read-only mirror; open issues and pull requests on the Forge.
Safely remove one or more Git worktrees and their directories, handling uncommitted changes and orphaned folders.
What it does
Running worktree-remove:
- Resolves the target worktree/directory (branch name, worktree path, or parent-directory name; supports
<repo>-<branch>naming). - Checks if the worktree is registered with Git.
- Safely handles "orphaned" directories (directories that exist but Git no longer recognizes as worktrees).
- Checks for uncommitted changes (if registered) and, when found, asks "Remove anyway?" before proceeding.
- Asks for a final confirmation to remove the registered worktree or orphaned directory (unless
--yesor--dry-run). - If you are inside the target directory, warns and switches the process to the main worktree before removal (your shell directory does not change, so after removal it may still point to a directory that no longer exists).
- Moves the directory to the system trash when possible (safer than
rm -rf). - Unregisters the worktree from Git (
git worktree remove/git worktree prune). - Reports the outcome when
--verboseor--dry-runis used.
Requirements
- Node.js ≥ 24.15.0
- Git with
git worktreesupport - Optional: set
WORKTREE_REMOVE_GIT_PATHto override the git executable
Install / run
Each release is published only as @j4k-oss/worktree-remove on the code.j4k.dev registry, which reads anonymously. The unscoped worktree-remove on npmjs.org is deprecated and gets no updates.
Always point the @j4k-oss scope at the code.j4k.dev registry: without that, npm looks on npmjs.org, finds nothing, and fails with a 404. Add this line to ~/.npmrc once:
@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/
For a single npx run, passing --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ on the command is enough, as the examples below do. Keep the ~/.npmrc line for global installs: npm update -g and npm outdated -g read the registry from your configuration, so without the line they look the scoped name up on npmjs.org.
You usually don’t need a global install.
# inside any worktree of /my/path/my-app
# one-off
npx -y --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ @j4k-oss/worktree-remove@latest -i
# or pass a target directly
npx -y --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ @j4k-oss/worktree-remove@latest feature/login-form
# or install globally, which installs the `worktree-remove` command
npm install -g --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ @j4k-oss/worktree-remove
worktree-remove -i
If you installed the unscoped worktree-remove globally before, run npm uninstall -g worktree-remove first. Both packages provide the worktree-remove command, so npm stops with EEXIST.
In a pnpm project, map the scope to its registry and exempt it from minimumReleaseAge in pnpm-workspace.yaml (this mapping replaces the flag), then add the package:
registries:
"@j4k-oss": https://code.j4k.dev/api/packages/j4k-oss/npm/
minimumReleaseAgeExclude:
- "@j4k-oss/*"
pnpm add -D @j4k-oss/worktree-remove
Usage
Run this from any worktree of your project. You can remove a sibling worktree, or even the worktree you are currently in.
By default, the CLI is quiet and requires an explicit target (non-interactive selection). Pass a target explicitly, or use --interactive to pick from a list. In a TTY it will still prompt for confirmations unless --no-interactive, --yes, or --dry-run is used. Use --force to bypass safety prompts around failures and uncommitted changes.
Interactive Mode (Recommended)
Use the -i flag to open an interactive multi-select list of worktrees:
# inside any worktree for the repository
worktree-remove -i
This allows you to select one or more worktrees to remove from a list. All selected worktrees are checked for uncommitted changes upfront, confirmed in a single batch, and removed in parallel.
Manual Mode
You can also specify the worktree directly by:
- branch name (for worktrees on a branch)
- worktree path (works for detached HEAD worktrees)
- directory name in the parent folder (useful when there's no branch)
.(current directory — removes the worktree you are in)
Note: If you pass a path that exists but isn't a registered worktree, it will be treated as an orphaned directory and moved to trash after confirmation. Path targets can point anywhere, so use caution when providing absolute or home-relative paths. For safety, unregistered directories inside the main worktree are refused.
worktree-remove <target...>
The targeting modes above map onto concrete invocations; see Examples for the full command list.
Detached HEAD example:
worktree-remove ../my-app-test-29
Sibling directory name example:
worktree-remove my-app-test-29
Options
-i, --interactiveinteractively select worktrees to remove (multi-select)--no-interactivedisable all prompts and interactive selection-y, --yesassume yes for all confirmation prompts-f, --forceskip safety prompts on failures and uncommitted changes (final confirmation still required unless--yesor--dry-run)--dry-runshow what would be removed without making changes--verboseshow detailed progress output--quietsuppress non-error output
Examples
# remove a worktree by branch name
worktree-remove feature/login-form
# remove multiple worktrees at once
worktree-remove feature/login-form feature/signup hotfix/typo
# preview what would be removed
worktree-remove --dry-run feature/login-form feature/signup
# use an interactive multi-select
worktree-remove --interactive
# remove the worktree you are currently in
worktree-remove . --yes
# pipe a worktree path from git + fzf
git worktree list --porcelain | rg '^worktree ' | sed 's/^worktree //' | fzf | xargs worktree-remove --yes
Automation Notes
In CI or non-interactive shells, pass --yes or --dry-run. Use --no-interactive to prevent any prompts.
Agent Rule
Add to your CLAUDE.md or AGENTS.md:
# Rule: `worktree-remove` Usage
Run `npx -y --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ @j4k-oss/worktree-remove@latest --help` to learn available options. Keep the `--@j4k-oss:registry` flag: without it, `npx` looks on npmjs.org, finds nothing, and fails with a 404.
Use `worktree-remove` when you need to safely remove Git worktrees.
It handles uncommitted changes and orphaned directories, and moves
directories to the system trash. If that move fails for a registered
worktree, `--force` (or `--yes` for a single worktree) lets Git delete
it permanently; without them, removal asks first or fails.
License
MIT
Dependencies
Dependencies
| ID | Version |
|---|---|
| @commander-js/extra-typings | ^15.0.0 |
| @inquirer/prompts | ^8.5.2 |
| chalk | ^5.6.2 |
| commander | ^15.0.0 |
| p-limit | ^7.3.0 |
| trash | ^10.1.1 |
Development dependencies
| ID | Version |
|---|---|
| @j4k-oss/fta-check | ^1.5.10 |
| @j4k/oxlint-config | ^2.14.2 |
| @j4k/semantic-release-forgejo | ^1.2.4 |
| @total-typescript/ts-reset | ^0.6.1 |
| @types/node | ^24.0.0 |
| @vitest/coverage-v8 | ^4.1.8 |
| conventional-changelog-conventionalcommits | ^9.3.1 |
| fta-cli | ^3.0.0 |
| knip | ^6.16.1 |
| oxfmt | ^0.57.0 |
| oxlint | ^1.88.0 |
| oxlint-tsgolint | ^7.0.2004 |
| semantic-release | ^25.0.5 |
| typescript | ^7.0.2 |
| vitest | ^4.1.8 |