Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Orchestrator

Repo hygiene

On this page
  1. Safety rule
  2. Ownership
  3. Reconcile round
  4. Leftovers
  5. Remote branches
  6. Disk guard
  7. Temp files and maintenance
  8. Logging
  9. Uninstall

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 prefix gitoodo).
  • 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.

StateAction
lease held or worker running (here or on a satellite)keep
merged (content in the base, also after squash), cleanremove worktree and local branch
issue closed, nothing unsavedremove 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 unknownkeep
unsaved workreport as leftover
folder deleted by handworktree 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 prune in every checkout; in Gitoodo's own clones (below clone_root) also git remote prune origin (with the account's token) and git 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.

Docs version: dev