| name | polylith-diff |
| description | List Polylith bricks whose **implementation** changed since a git tag using `poly diff`. Use for release notes, selective deploys ("which projects need rebuilding?"), and PR scope review. For TEST-code diffs, use `polylith-testing` instead. |
Diff Skill
Quick command
uv run poly diff
uv run poly diff --bricks --short
Agent rule of thumb: when the goal is to do something with the result (run pytest, drive a deploy script, render a list), reach for --bricks --short first. The default output is for human readers.
Command prefix: If you do not know the package manager, list lock files with ls uv.lock poetry.lock pdm.lock 2>/dev/null (a pyproject.toml is always present, so it tells you nothing on its own). Use uv run poly (uv), poetry poly (poetry), pdm run poly (pdm), hatch run poly (hatch), or poly (activated venv). Examples below use uv run.
poly diff vs poly test diff:
poly diff → brick implementation changes since a tag (drives releases/deploys).poly test diff → test-code changes since a tag (drives selective test runs). Load polylith-testing.
Tag selection
- Default: latest git tag matching
[tool.polylith.tag.patterns].stable from workspace.toml (e.g. stable-*).
--since <ref> — pin a specific tag, branch, or commit-ish. The CLI tries to resolve <ref> as a configured pattern key first, then falls through to using it literally with git diff <ref>.
Command reference
| Option | Default | Description |
|---|
--since | latest matching tag | Reference tag (or branch/commit) to diff against. |
--short | false | Compact output. Combined with --bricks, emits a comma-separated list of brick names — pipe-friendly. |
--bricks | false | Print the list of bricks that changed (human-readable on its own; CSV when paired with --short). |
--deps | false | With --bricks, also print bricks that depend on the changed bricks (transitive impact). |
Examples
uv run poly diff
uv run poly diff --since stable-4 --bricks --deps
uv run poly diff --since main --bricks --short
Running tests for changed bricks
The established Polylith pattern is to feed --bricks --short straight into pytest -k: brick names become an or-expression that pytest matches against test IDs, so the agent doesn't need to resolve namespace / theme / base-vs-component.
changes="$(uv run poly diff --bricks --short)"
[ -n "$changes" ] && uv run pytest -k "${changes//,/ or }"
Example: --bricks --short outputs log,message → pytest runs as pytest -k "log or message", collecting every test whose ID contains log or message (matches test/components/<ns>/log/... and test/bases/<ns>/log/... alike).
⚠ pytest -k does substring matching, so a brick named log will also match tests whose name contains log (e.g. an unrelated logger brick or a test_login function). For short/generic brick names, fall back to passing explicit test directories.
Notes for the agent
- Operates on git's view of the working tree — uncommitted changes since the tag count as changed.
- If no matching tag exists and
--since isn't passed, the command prints No matching tags or commits found in repository. and exits 0. Guard scripts so they don't run pytest -k "" (which would collect nothing or, worse, every test depending on the version).
- Map changed bricks → projects with
poly info (load polylith-workspace-inspection) to drive selective deploys.
