Clean to Execute

clean-to-execute removes Docker Compose resources for a local clone of a GitHub repository.

The repository is found recursively by inspecting Git remotes under the user's home directory. Directory names alone are not trusted. Docker Compose files must be at the repository root.

Requirements

• Python 3.10 or newer
• Git
• Docker with the Compose plugin
• Access to a running Docker daemon

Installation

From this directory:

python3 -m pip install .

Usage

Execute cleanup:

clean-to-execute --repository example

Preview cleanup without changing Docker resources:

clean-to-execute --repository example --dry-run

Search somewhere other than ~:

clean-to-execute \
  --repository example \
  --root /workspaces

The GitHub organization defaults to kaizten. Use --organization to select a different organization.

Cleanup is destructive by default. Use --dry-run when only a preview is required.

Before cleanup, each published host port is annotated with the PID and name of its current host listener when that information is available. PID discovery is best-effort and uses the Linux ss command. An unbound port is shown as not listening; missing tools or insufficient permissions are shown as PID unavailable and do not prevent cleanup.

Cleanup scope

The command recognizes compose.yaml, compose.yml, docker-compose.yaml, and docker-compose.yml at the repository root. Docker Compose renders the effective configuration, including its normal override and environment interpolation behavior. All Compose profiles are activated for inspection and shutdown, so services and ports behind profiles are included without requiring the caller to name each profile.

By default, the command:

1. Stops and removes the entire Compose project, including orphan containers, so all of its published ports are released.
2. Deletes the project's non-external named and anonymous volumes.
3. Deletes all other dangling Docker volumes, while preserving external volumes declared by this Compose project.
4. Force-removes local images referenced by the Compose configuration whose namespace matches the GitHub organization.

The namespace comparison works across registries. For example, all of these belong to the GitHub organization kaizten:

• kaizten/api
• docker.io/kaizten/api
• ghcr.io/kaizten/api
• registry.example.com/kaizten/api

Containers outside the selected Compose project are never stopped or removed. An external container may still prevent Docker from deleting an image; that is reported as a cleanup failure.

If multiple local clones match the same GitHub remote, the command lists them and exits instead of choosing one implicitly.

Development

python3 -m unittest discover -s tests -v
./build-package.sh