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 --organization kaizten --repository example

Preview cleanup without changing Docker resources:

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

Search somewhere other than ~:

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

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

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