Resource Cleanup & Garbage Collection
Relevant source files
The following files were used as context for generating this wiki page:
Resource Cleanup and Garbage Collection in Docktree is the process of identifying and removing stale or orphaned Docker resources—such as containers, networks, and volumes—and associated port allocations that are no longer linked to an active git worktree. This system ensures that local development environments remain performant by reclaiming system resources from worktrees that have been deleted, are missing their directory paths, or have remained idle for extended periods.
The cleanup logic is primarily invoked via the docktree clean command, which scans for resources managed by Docktree (identified by specific Docker labels) and compares them against the known global state of active worktree instances.
Cleanup Architecture & Discovery
The cleanup process follows a discovery-then-application pattern. It cross-references three sources of truth: the port registry, the global instance state, and the live Docker environment.
Stale Resource Identification
Resources are considered "stale" if they meet specific criteria defined by the system's identification logic. This includes resources belonging to worktrees whose filesystem path no longer exists, worktrees that haven't been active for more than 14 days, or "orphaned" Docker resources that have no corresponding entry in the Docktree state.
The following flowchart illustrates the logical flow for identifying stale candidates:
Key Data Structures
The system uses specific structures to track resources and report the impact of a cleanup operation.
| Structure | Description | Fields |
|---|---|---|
cleanCandidate | Internal representation of a project identified for removal. | Name, Reason, Ports, Resources, Instance |
CleanItem | A single item in the public cleanup result. | Instance, Reason, Ports, Containers, Networks, Volumes |
CleanResult | The final object rendered to the user or returned as JSON. | Instances[], Totals, DryRun, Removed |
ProjectResources | Collections of raw Docker resource IDs/Names. | Containers[], Networks[], Volumes[] |
Sources: internal/cli/clean.go:150-161, internal/docker/cleanup.go:15-19
Execution & Application
Once candidates are identified, the application phase handles the actual removal of resources. This phase is gated by a safety check unless the --yes or --dry-run flags are provided.
Removal Sequence
The removal process is performed in a specific order to prevent resource locking issues:
- Port Release: Allocated host ports are freed in the registry.
- State Removal: The global instance entry is deleted.
- Docker Resource Removal: Containers are removed forcefully (
rm -f), followed by networks and (optionally) volumes. - Filesystem Cleanup: The per-worktree state directory (e.g.,
.docktree/) is deleted.
The sequence diagram below details the interaction between the CLI and internal modules during an application:
Docker Integration
Docktree identifies its resources using Docker labels. This prevents the cleanup process from accidentally removing non-Docktree containers.
Managed Labels
The system filters resources based on the following labels:
docktree.managed=true: Used to identify containers under Docktree control.com.docker.compose.project: Used to group resources by project name.docktree.instance: Often contains the specific instance identifier.
Volume Cleanup
Volumes are treated as a special case. Because volumes often contain persistent developer data (like databases), they are only removed if the --volumes flag is explicitly passed to the clean command. The system supports both project-scoped volumes and shared volumes.
Sources: internal/docker/cleanup.go:21-41, internal/docker/cleanup.go:138-185, internal/cli/help_doc.go:121-131
Conclusion
Resource Cleanup and Garbage Collection serves as the maintenance backbone of the Docktree system. By automating the discovery of orphaned Docker resources and stale port allocations, it prevents the accumulation of "ghost" containers and port exhaustion—a common issue when managing dozens of git worktrees. The inclusion of safety features like dry-run modes and idle-time thresholds ensures that active development is not disrupted while keeping the host system clean.
Sources: internal/cli/clean.go:1-50, internal/cli/render.go:377-438