gws delete

Delete a git worktree and cleanup associated resources.

Usage

gws delete <worktree> [options]

Output:

ℹ This will permanently delete worktree: 'feature-auth' from project 'myapp':
ℹ   - Git worktree directory: ./.worktrees/feature-auth
✔ Delete? … yes
✔ Worktree deleted from 1 repo(s)

Note: This command can be run from anywhere using the -p [project] option.

---

Arguments

Argument	Description	Required
<worktree>	Worktree name to be deleted	Yes

Options

Option	Description	Default
-p, --project <name>	Project name	Auto-detected from current directory
-y, --yes	Skip confirmation prompt	false
--delete-branch	Also delete the associated git branch	false

Examples:

# Skip confirmation
gws delete -w feature-auth -y

# Keep branch
gws delete -w feature-auth --keep-branch

---

Multirepo Behavior

When running gws delete in a multirepo setup, the command deletes the worktree from each repository.

Project Structure Before Delete

myapp/                          # Parent directory
├── .worktrees/                 # Shared worktrees folder
│   └── feature-auth/           # Worktree to delete
│       ├── api/
│       │   └── src/
│       └── app/
│           └── src/
├── api/                        # Git repo 1
│   ├── .git/
│   └── src/
└── app/                        # Git repo 2
    ├── .git/
    └── src/

Deleting Worktree

cd myapp
gws delete -w feature-auth
# or from any directory
gws delete -w feature-auth -p myapp

Output:

ℹ This will permanently delete worktree: 'feature-auth' from project 'myapp':
ℹ   - Git worktree directory: ./.worktrees/feature-auth
✔ Delete? … yes
✔ Worktree deleted from 2 repo(s)

What happens:

1. Deletes .worktrees/feature-auth/ from the parent directory
2. Removes the git worktree registration from each repo
3. Deletes branch env/feature-auth from each repo (unless --delete-branch is omitted)
4. Git commit history is preserved in all repositories

---

Common Errors

Worktree is Currently Deployed

Error:

✖ Cannot delete worktree 'feature-auth'
✖ Deployment is currently running in namespace 'myapp-feature-auth'
✖ Please stop the deployment first with: gws down -w feature-auth

Solution:

# Stop the deployment first
gws down -w feature-auth

# Then delete the worktree
gws delete -w feature-auth

Worktree Not Found

Error:

✖ Worktree 'feature-auth' not found
✖ No worktree directory exists at .worktrees/feature-auth

Solution:

# Check existing worktrees
gws status

# Verify worktree name
git worktree list

---

See Also

• gws fork - Create worktree
• gws down - Stop deployment only
• gws status - View worktrees