Resolution and Conflicts

It is one-directional: old is replaced by new. It never pins or introduces the new module's version — the replacement is only chosen if it is already in the graph, and its version is resolved by Gradle's normal rules.

Substitution unconditionally swaps one selector for another module/project. Module replacement only states that two coordinates are the same logical library, so the old one is evicted during conflict resolution if both appear. Use replacement for renamed libraries, substitution for forced swaps.

Use configuration.incoming.artifactView{...}.artifacts.artifactFiles (a lazy FileCollection) as the task's @InputFiles. Resolution then happens at execution time, not configuration time, keeping builds fast and configuration-cache compatible.

Walk the graph via incoming.resolutionResult.allComponents, find the ResolvedComponentResult for the module, and read its selectionReason — its descriptors explain the cause (conflict resolution, constraint, forced, etc.).

The eachDependency closure runs at resolve time, but you register it at configuration time. Capturing live project state inside it can read stale values or break the configuration cache. Resolve inputs into a Provider/local val up front instead.

eachDependency is an imperative per-module callback — great for conditional or computed rewrites, but harder to read and reason about at scale. For broad version policy, prefer declarative constraints or a platform; reserve eachDependency for cases needing logic.

Use the variant-aware substitution DSL: substitute(module(...)).using(project(...)).withClassifier(...) or attach capabilities/attributes via variant { ... }, so the substitute resolves to the correct artifact instead of failing on a missing variant.

Set componentFilter { id -> id is ProjectComponentIdentifier } to keep only local project artifacts, or ModuleComponentIdentifier for external ones. Useful for fat-jar/relocation logic that should treat your own code differently from third-party libs.

failOnVersionConflict() makes Gradle fail whenever two versions of a module are requested, instead of silently picking the highest. force resolves such conflicts and avoids the failure; you enable it to surface every version disagreement and pin them deliberately.

When publishing, declare a capability on a variant via the Java library's registerFeature or by adding capabilities to outgoing configurations. If you give two alternative implementations the same capability, consumers can pick only one — Gradle enforces mutual exclusivity at resolution.

Decide which configurations to lock (often all resolvable ones), generate per-project lockfiles, commit them, and enforce regeneration in CI. Use STRICT mode to forbid unlocked resolution, and define a standard --update-locks workflow for upgrades.