For developers · Orchestrator
Repo hygiene
On this page
Gitoodo cleans up its own worktrees, branches and temp files: after merges, after crashes and
resets, after an uninstall, and above all in the user's own checkouts, which serve as clones since
#755. Code: crates/core/src/hygiene/ (decisions, the only removing code), the dispatcher's
crates/cli/src/dispatcher_hygiene.rs and the satellite's crates/cli/src/satellite_hygiene.rs.
Safety rule#
In a user checkout Gitoodo only ever runs git worktree remove on worktrees below the worktree root
that are its own, git worktree prune, git branch -D <prefix>/<number>… and a fetch of the base.
User branches, stashes, the index and working-tree changes of the checkout are never touched
(crates/core/tests/hygiene.rs checks this). Anything that holds work that would be lost
(uncommitted files, commits on no remote branch and not in the base by content) is never removed
silently; it is reported as a leftover.
Ownership#
- Every worktree Gitoodo creates (dispatcher and satellite) gets the marker file
gitoodo-owner(JSON: issue key, branch, time, host) in its git folder (<checkout>/.git/worktrees/<name>/), so the working tree stays clean. - Its branch is
<branch_prefix>/<number>-<title>(default prefixgitoodo). - Older worktrees without a marker count as Gitoodo's when they lie below the worktree root on such a
branch. Agent sessions (
agent-session/*) never match.
Reconcile round#
At dispatcher start (after the leases of the earlier run are released) and every sweep interval
(5 min), the dispatcher scans the checkouts of the configured repos, every checkout a folder below
worktree_root points to, and the orphan folders there. Before deciding it fetches the base.
| State | Action |
|---|---|
| lease held or worker running (here or on a satellite) | keep |
| merged (content in the base, also after squash), clean | remove worktree and local branch |
| issue closed, nothing unsaved | remove worktree and local branch |
| issue open, clean and pushed (abandoned) | remove worktree, keep branch for a new start |
waiting for a human (needs-human, stalled) or unknown | keep |
| unsaved work | report as leftover |
| folder deleted by hand | worktree prune, branch as above |
| orphan folder (no worktree any more) | report as leftover |
The lease sweep and the cleanup after a merge also delete the local branch once its work is merged or its issue closed. A lease taken between scan and removal wins (checked again right before).
Satellites take part on the main host's word: hygiene_scan returns their items, the main host
decides with its leases and the forge, hygiene_apply carries the decisions out; a running
worker's worktree is refused there too. On its own, 30 s after start and every 5 minutes, a satellite sweeps
old temp files (also inside the shared sessions folder) and removes what is merged in content (the scope the main host sent last, kept in
satellite-hygiene.json).
Leftovers#
Reported items go to hygiene.json in the state folder (HygieneStatus): cleanup state, leftovers
with host, issue, branch, commits and uncommitted files, disk reading and errors. The status window
shows "Cleaned up" or "N leftovers", the board lists the leftovers too, each with:
- Discard: removes the worktree and branch with whatever they hold.
- Push as backup branch and remove: commits uncommitted files, pushes the branch as
<prefix>-backup/<rest>-<time>with the account's token, then removes it (main host only).
The app queues the decision in hygiene-requests.json; the dispatcher handles it within 5 s and
runs a round. dispatch.leftover_expiry_days (default 0 = off) discards leftovers automatically
after that many days. gitoodo diagnose lists the leftovers.
Remote branches#
Hourly, for every configured repo with the sweep rule on, remote <prefix>/* branches without an
open pull/merge request, without a lease and without a local branch are deleted once the issue is
known (open or closed) and the newer of last commit and first sighting is older than
dispatch.remote_branch_grace_hours (default 24, 0 = off). At most 10 per round, one per second,
through the forge adapters (Forgejo/Gitea, GitHub, GitLab; every deletion in the forge audit log and
the dispatcher log).
Disk guard#
Before a new local worker the free space of the volume holding worktree_root is checked against
the smaller of dispatch.min_free_disk_mb (default 10240) and dispatch.min_free_disk_percent
(default 5 %); 0 switches a limit off, an unknown reading never blocks. When it is low no new local
worker starts (satellites still take work; with none online the dispatch wait reason is
disk_low), DispatcherStatus.disk_low is set, a reconcile round runs and the app offers "Clean up now".
Temp files and maintenance#
- Temp artefacts live under one root,
<system temp>/gitoodo, as RAII folders removed when done. At dispatcher, satellite (30 s later) and app start, leftovers older than 24 h are removed, including the older names in the system temp folder. - Every 6 hours:
git worktree prunein every checkout; in Gitoodo's own clones (belowclone_root) alsogit remote prune origin(with the account's token) andgit gc --auto.
Logging#
Every removal, backup, remote deletion and maintenance pass is a cleanup step
(logging::run::Step, see logging) plus a dispatch.cleanup_* event.
Uninstall#
scripts/uninstall.sh --keep-repos (Windows: scripts/uninstall.ps1 -KeepRepos) keeps the working
copies but removes Gitoodo's worktrees and <prefix>/* branches from them (only what loses nothing;
the rest is listed). --dry-run (-DryRun) lists what would be removed.