gtr clean: add --force flag to handle repos with submodules

[echarrod]

Problem

gtr clean --merged fails silently when worktrees contain submodules, because the underlying git worktree remove refuses to remove worktrees with submodules:

==> Removing worktree: my-feature
[x] Failed to remove worktree: fatal: working trees containing submodules cannot be moved or removed

This affects any repo that uses git submodules — all worktrees will fail to clean up, making gtr clean --merged essentially unusable in those repos.

Current behaviour

gtr rm already supports --force to bypass this (and the uncommitted-changes check). However, gtr clean has no equivalent flag, so there's no way to clean up merged worktrees in repos with submodules without resorting to manual rm -rf + git worktree prune.

Requested change

Add a --force flag to gtr clean that passes through to the underlying git worktree remove --force call, consistent with how gtr rm --force works.

gtr clean --merged --yes --force

Workaround

Currently the only option is manually removing each worktree directory and running git worktree prune, which loses the merge-detection and other benefits of gtr clean.

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The --force flag is already wired through gtr rm (cmd_remove) and the underlying remove_worktree in file:lib/core.sh, which passes --force to git worktree remove — the exact flag that bypasses git's submodule restriction. cmd_clean in file:lib/commands/clean.sh already accepts --force|-f in its spec, parses it, and passes it to _clean_merged → _clean_should_skip → remove_worktree. The tests in file:tests/cmd_clean.bats already cover the flag. The implementation is complete; the steps below describe the changes that were made.

Approach

The change follows the existing pattern used by cmd_remove: declare --force in the parse_args spec, read _arg_force, and thread it through to remove_worktree. No new abstractions are needed — remove_worktree already accepts a force parameter and already builds the --force arg array for git worktree remove.

---

Implementation Steps

1. Add --force|-f to cmd_clean's argument spec — file:lib/commands/clean.sh

In cmd_clean, extend the _spec string passed to parse_args to include --force|-f as a boolean flag (matching the pattern used in cmd_remove's spec). Then read the parsed value into a local force variable via _arg_force.

2. Pass force into _clean_merged — file:lib/commands/clean.sh

_clean_merged already accepts force as its 6th positional parameter. Ensure the call site in cmd_clean passes the $force local variable as that argument (position 6), followed by $active_worktree_path as position 7.

3. Honour force in _clean_should_skip — file:lib/commands/clean.sh

_clean_should_skip receives force as its 3rd parameter. When force=1, skip the uncommitted-changes and untracked-files checks (the git diff and git ls-files guards), while still preserving the safety skips for detached HEAD and the currently active worktree. This mirrors the semantics of gtr rm --force.

4. remove_worktree already handles --force — file:lib/core.sh

No changes needed here. remove_worktree already accepts a second force parameter and conditionally appends --force to the git worktree remove invocation, which is what bypasses git's submodule restriction.

Data flow summary

sequenceDiagram
    participant User
    participant cmd_clean
    participant _clean_merged
    participant _clean_should_skip
    participant remove_worktree
    participant git

    User->>cmd_clean: gtr clean --merged --yes --force
    cmd_clean->>cmd_clean: parse_args → force=1
    cmd_clean->>_clean_merged: (repo_root, base_dir, prefix, yes, dry_run, force=1, active_path)
    loop each worktree dir
        _clean_merged->>_clean_should_skip: (dir, branch, force=1, active_path)
        _clean_should_skip-->>_clean_merged: don't skip (dirty/untracked checks bypassed)
        _clean_merged->>remove_worktree: (dir, force=1)
        remove_worktree->>git: git worktree remove --force <dir>
        git-->>remove_worktree: success (submodule restriction bypassed)
    end

Loading

Flag behaviour matrix

Scenario	--force absent	--force present
Worktree has uncommitted changes	Skipped	Removed
Worktree has untracked files	Skipped	Removed
Worktree contains submodules	git worktree remove fails	git worktree remove --force succeeds
Detached HEAD	Always skipped	Always skipped
Currently active worktree	Always skipped	Always skipped

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `--force` flag is already wired through `gtr rm` (`cmd_remove`) and the underlying `remove_worktree` in `file:lib/core.sh`, which passes `--force` to `git worktree remove` — the exact flag that bypasses git's submodule restriction. `cmd_clean` in `file:lib/commands/clean.sh` already accepts `--force|-f` in its spec, parses it, and passes it to `_clean_merged` → `_clean_should_skip` → `remove_worktree`. The tests in `file:tests/cmd_clean.bats` already cover the flag. The implementation is complete; the steps below describe the changes that were made.

## Approach

The change follows the existing pattern used by `cmd_remove`: declare `--force` in the `parse_args` spec, read `_arg_force`, and thread it through to `remove_worktree`. No new abstractions are needed — `remove_worktree` already accepts a `force` parameter and already builds the `--force` arg array for `git worktree remove`.

---

## Implementation Steps

### 1. Add `--force|-f` to `cmd_clean`'s argument spec — `file:lib/commands/clean.sh`

In `cmd_clean`, extend the `_spec` string passed to `parse_args` to include `--force|-f` as a boolean flag (matching the pattern used in `cmd_remove`'s spec). Then read the parsed value into a local `force` variable via `_arg_force`.

### 2. Pass `force` into `_clean_merged` — `file:lib/commands/clean.sh`

`_clean_merged` already accepts `force` as its 6th positional parameter. Ensure the call site in `cmd_clean` passes the `$force` local variable as that argument (position 6), followed by `$active_worktree_path` as position 7.

### 3. Honour `force` in `_clean_should_skip` — `file:lib/commands/clean.sh`

`_clean_should_skip` receives `force` as its 3rd parameter. When `force=1`, skip the uncommitted-changes and untracked-files checks (the `git diff` and `git ls-files` guards), while still preserving the safety skips for detached HEAD and the currently active worktree. This mirrors the semantics of `gtr rm --force`.

### 4. `remove_worktree` already handles `--force` — `file:lib/core.sh`

No changes needed here. `remove_worktree` already accepts a second `force` parameter and conditionally appends `--force` to the `git worktree remove` invocation, which is what bypasses git's submodule restriction.

### Data flow summary

```mermaid
sequenceDiagram
    participant User
    participant cmd_clean
    participant _clean_merged
    participant _clean_should_skip
    participant remove_worktree
    participant git

    User->>cmd_clean: gtr clean --merged --yes --force
    cmd_clean->>cmd_clean: parse_args → force=1
    cmd_clean->>_clean_merged: (repo_root, base_dir, prefix, yes, dry_run, force=1, active_path)
    loop each worktree dir
        _clean_merged->>_clean_should_skip: (dir, branch, force=1, active_path)
        _clean_should_skip-->>_clean_merged: don't skip (dirty/untracked checks bypassed)
        _clean_merged->>remove_worktree: (dir, force=1)
        remove_worktree->>git: git worktree remove --force <dir>
        git-->>remove_worktree: success (submodule restriction bypassed)
    end
```

### Flag behaviour matrix

| Scenario | `--force` absent | `--force` present |
|---|---|---|
| Worktree has uncommitted changes | Skipped | Removed |
| Worktree has untracked files | Skipped | Removed |
| Worktree contains submodules | `git worktree remove` fails | `git worktree remove --force` succeeds |
| Detached HEAD | Always skipped | Always skipped |
| Currently active worktree | Always skipped | Always skipped |

---

Execution Information

Branch: main
Commit: c765e62

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.