Configurable trash directory location (trash on a separate filesystem)

[g-simmons]

Summary

Allow the worktree trash directory to be configured, so it can live on a different filesystem than the repo.

Motivation

wt's trash dir is currently hardcoded to <git-common-dir>/wt/trash (the Repository::wt_trash_dir path). On a repo with many large worktrees (ours have full node_modules trees), trash accumulates fast — ours reached 78 GB / ~3.8M files. That can fill the repo's disk while plenty of space exists on a separate bulk volume.

There's no config key or env var to redirect it today (wt config exposes worktree-path but nothing for trash; the binary has no WORKTRUNK_*TRASH setting).

Request

A configurable trash location, e.g. one of:

• trash-path in config.toml (templated like worktree-path), or
• a WORKTRUNK_TRASH_DIR env var.

Ideally per-project overridable, same as worktree-path.

Current workaround

Symlink the trash dir to a bigger filesystem:

mv  <repo>/.git/wt/trash  /mnt/bigstorage/<repo>-wt-trash
ln -s /mnt/bigstorage/<repo>-wt-trash  <repo>/.git/wt/trash

This works and is transparent to wt (and to tools that compute the same path), but a native config option would be cleaner and survive .git/wt recreation.

Thanks for worktrunk!

[worktrunk-bot]

Thanks for the suggestion, and for the detailed motivation (78 GB / 3.8M files is a compelling case).

I searched the codebase and confirmed there's no existing way to redirect the trash directory: Repository::wt_trash_dir() hardcodes <git-common-dir>/wt/trash, and there's no trash-path config key or WORKTRUNK_*TRASH* env var. The closest related functionality is worktree-path, which is templated and per-project overridable — that's the shape your request points at.

One design nuance worth flagging for whoever picks this up: the trash dir exists specifically to enable an instant same-filesystem rename. stage_worktree_removal does std::fs::rename(worktree, staged) and, on failure (cross-filesystem, permissions, Windows locking), returns None so the caller falls back to a synchronous git worktree remove. So pointing trash at a different filesystem — whether via this feature or your symlink workaround — defeats the rename optimization: removals would copy-then-delete synchronously rather than rename-and-defer. That's a real tradeoff (the disk-space win comes at the cost of the fast-removal win), not a blocker, but it's the thing a native implementation would need to decide how to handle. A configurable path would also need the background sweep that prunes stale trash (documented in the FAQ) to follow the same override.

Your symlink workaround is the right stopgap in the meantime. I'll leave this for a maintainer to evaluate and prioritize.

[max-sixty]

currently the trash design is just a temporary place to move files so that the remove is fast. then the trash is immediately cleaned up in the background.

does this fit well with that?

is there a different problem, like the trash not getting cleaned?

[worktrunk-bot]

Your model is right, and it's worth being precise about it because it bears directly on whether a configurable path is the correct fix.

The trash dir is not a holding area that fills until a sweep — under normal operation it should hover near empty:

• Default wt remove: rename the worktree into .git/wt/trash/<name>-<ts>/ (instant on the same filesystem), then spawn a detached rm -rf on that staged dir immediately (handle_remove_output → build_remove_command_staged). The trash entry normally lives only as long as that one rm -rf. The detached process is process_group(0)'d, so closing the terminal/SSH session doesn't SIGHUP it.
• 24h sweep (sweep_stale_trash, TRASH_STALE_THRESHOLD_SECS = 24h) is only a backstop for entries the immediate rm didn't finish. It runs only as a side effect of wt remove (run_internal_sweep), at low priority (nice/ionice).
• Cross-filesystem / locked: no staging at all — falls back to git worktree remove, so trash isn't even touched.

So 78 GB / 3.8M files is a cleanup-not-completing symptom, not a steady-state size — which means a configurable path wouldn't address the root cause (and, as I noted above, pointing trash at another filesystem actively disables the instant rename, forcing synchronous copy-then-delete on every removal).

The plausible accumulation story for huge node_modules trees: a machine sleep/reboot/interrupt mid-rm leaves a partial tree, and the only thing that reclaims it is the next wt remove's single low-priority sweep — which over a multi-GB backlog can itself be interrupted before it catches up, and does nothing at all if removals pause. The janitor is gated entirely on wt remove running and completing.

One diagnostic that would settle it ( @g-simmons ): in .git/wt/trash/, are there entries whose trailing timestamp (a unix epoch) is older than 24h?

• Many old ones → the backstop genuinely isn't keeping up (a cleanup-robustness bug worth fixing on its own — e.g. a sweep not gated on wt remove, or one that retries until drained).
• Everything <24h → the directory is self-draining and the large size is transient churn during active removal.

Either way the more durable fix points at making cleanup robust rather than relocatable — but that's a maintainer call.