Configuration.

Start with the defaults#

Full build-context checks are enabled, stable versions are preferred, all update tiers are allowed, and included builds and buildSrc are analyzed. Check tasks never edit sources. The interactive task starts every source at Current.

// build.gradle.kts — a conservative starting point
depLens {
    dependencies { allowedUpdates.set("minor") }
    plugins { allowedUpdates.set("minor") }
    gradle { allowedUpdates.set("minor") }
    failIfChecksIncomplete.set(true)
}

// build.gradle — the same configuration
depLens {
    dependencies { allowedUpdates = 'minor' }
    plugins { allowedUpdates = 'minor' }
    gradle { allowedUpdates = 'minor' }
    failIfChecksIncomplete = true
}

Groovy examples assign values directly. Kotlin examples use Gradle properties' .set(...) methods. Omitted fields retain their defaults or inherited policy.

Build scope and check mode#

The current build and its subprojects remain included. Intentionally excluded builds do not make a report incomplete. Gradle may still configure or compile excluded build logic to load the consumer; these switches control DepLens analysis. Root values provide defaults for nested analysis; scopes with their own DepLens configuration may override supported defaults. --fast overrides build-context checking across the selected invocation.

depLens {
    checkIncludedBuilds.set(true)
    checkBuildSrc.set(false)
    checkBuildContext.set(true)
    consoleMode.set("standard")
}

depLens {
    checkIncludedBuilds = true
    checkBuildSrc = false
    checkBuildContext = true
    consoleMode = 'standard'
}

Fast discovery still resolves the current inventory and uses repositories, selectors, ordering, update tiers, prerelease and ignore policies. It skips candidate Java/variant and peer/BOM/constraint compatibility checks and the older-compatible candidate fallback. Recommendations are qualified as “build context not checked”; latestAllowedByBuild remains null. Wrapper checks are unchanged. A completed fast check can be complete for its selected mode without proving graph compatibility.

Analysis and output filters#

Each filter has includes and excludes: lists of Java regex strings matched against the whole configuration name. Both default to []. Empty includes accept all names; any matching exclusion wins. Invalid regexes fail configuration.

runtimeClasspath is a resolvable context; runtimeOnly is a declaration bucket. Do not use those names interchangeably. Dependencies and constraints inherited by a selected context still participate, even when their declaring names do not match the analysis filter. A component reached by another selected context remains analyzed. Deliberately excluded contexts do not make analysis incomplete.

depLens {
    checkResolvableConfigurationFilter {
        includes.set(listOf("compileClasspath", "runtimeClasspath", "test.*Classpath"))
        excludes.set(listOf("testRuntimeClasspath"))
    }
    outputDeclaredConfigurationFilter {
        excludes.set(listOf("jacocoAnt", "kotlinCompilerPluginClasspath.+"))
    }
}

depLens {
    checkResolvableConfigurationFilter {
        includes = ['compileClasspath', 'runtimeClasspath', 'test.*Classpath']
        excludes = ['testRuntimeClasspath']
    }
    outputDeclaredConfigurationFilter {
        excludes = ['jacocoAnt', 'kotlinCompilerPluginClasspath.+']
    }
}

Root analysis lists are inherited by subprojects and separate builds. An explicitly configured list replaces the inherited list; an explicit empty list resets it. The requesting task's output filter also applies to merged entries. Entries with multiple origins stay visible if one origin passes; entries with no origins stay visible. All origins of retained entries remain in JSON.

Output filtering never bypasses pins, failed checks or policy conflicts on shared sources. Hidden peers, constraints and BOMs still affect recommendations. JSON hiddenEntries and hiddenFailedEntries record hidden results. Neither filter changes plugin, wrapper, buildscript or settings-classpath checks.

Dependency and plugin policies#

Configure these properties independently in dependencies { ... } and plugins { ... }. Dependency defaults also cover BOMs/platforms and constraints. Plugin keys are plugin IDs, not implementation-module coordinates.

depLens {
    dependencies {
        includePreReleases.set(false)
        allowedUpdates.set("minor")
        failIfUpdatesFound.set(true)
        pinCurrentVersions.set(listOf("org.example:legacy"))
        ignoredVersions.set(mapOf("org.example:library" to listOf("2.5.0")))
    }
    plugins {
        includePreReleases.set(false)
        allowedUpdates.set("patch")
        failIfUpdatesFound.set(false)
        pinCurrentVersions.set(listOf("org.example.tool"))
        ignoredVersions.set(mapOf("org.example.other" to listOf("3.0.0")))
    }
}

depLens {
    dependencies {
        includePreReleases = false
        allowedUpdates = 'minor'
        failIfUpdatesFound = true
        pinCurrentVersions = ['org.example:legacy']
        ignoredVersions = ['org.example:library': ['2.5.0']]
    }
    plugins {
        includePreReleases = false
        allowedUpdates = 'patch'
        failIfUpdatesFound = false
        pinCurrentVersions = ['org.example.tool']
        ignoredVersions = ['org.example.other': ['3.0.0']]
    }
}

Normal ordering uses Gradle's version comparator. Automatic prerelease detection recognizes alpha, beta, rc, cr, m, milestone, preview, snapshot, dev, ea and nightly, case-insensitively. Calendar-date versions can have unknown compatibility; minor and patch policies exclude unknown tiers unless a matching custom version pattern classifies them. Update tiers describe version numbering, not binary compatibility.

Gradle wrapper policy#

Configure the wrapper independently in gradle { ... }.

depLens {
    gradle {
        includePreReleases.set(false)
        allowedUpdates.set("minor")
        failIfUpdatesFound.set(false)
        pinCurrentVersion.set(false)
        versionsUrl.set("https://services.gradle.org/versions/all")
    }
}

depLens {
    gradle {
        includePreReleases = false
        allowedUpdates = 'minor'
        failIfUpdatesFound = false
        pinCurrentVersion = false
        versionsUrl = 'https://services.gradle.org/versions/all'
    }
}

Offline mode skips remote wrapper feeds and marks them unchecked; a local feed can be used instead. Builds without a wrapper do not become incomplete just because they have no wrapper target.

When an interactive wrapper edit has an existing distributionSha256Sum, DepLens fetches the exact selected distribution's .sha256 sidecar and prepares the URL and checksum changes before any selected source is written. The distribution type (bin/all) and custom mirror are preserved. Sidecars support HTTPS or local file: URLs; HTTPS redirects must remain HTTPS. Invalid or unavailable checksums prevent the whole selection from being applied. Offline mode allows local sidecars only. Wrappers without a checksum do not gain one. Wrapper scripts and JARs are not regenerated by these source edits. There is no separate checksum-update option.

Scoped rules and precedence#

Rules override individual fields, not whole policies. Higher precedence wins:

Exact dependency / platform / plugin / Gradle > group > project > global > section defaults.

At equal specificity, the later matching rule wins for fields it explicitly sets. Unset fields inherit. Lists replace broader lists; they are not appended. Empty lists clear inherited exclusions. A specific pinned = false can unpin a broader pin. Root rules are inherited by subprojects and separate builds; their rules may override fields at the same or greater specificity.

depLens {
    rules {
        global { includePreReleases.set(false) }
        project(":app") { allowedUpdates.set("minor") }
        group("org.example") { allowedUpdates.set("patch") }
        dependency("org.example:library") {
            allowedUpdates.set("minor")
            ignoredVersions.set(listOf("2.5.0"))
        }
        platform("org.example:stack-bom") { allowedUpdates.set("minor") }
        plugin("org.example.tool") { pinned.set(true) }
        gradle { allowedUpdates.set("minor") }
    }
}

depLens {
    rules {
        global { includePreReleases = false }
        project(':app') { allowedUpdates = 'minor' }
        group('org.example') { allowedUpdates = 'patch' }
        dependency('org.example:library') {
            allowedUpdates = 'minor'
            ignoredVersions = ['2.5.0']
        }
        platform('org.example:stack-bom') { allowedUpdates = 'minor' }
        plugin('org.example.tool') { pinned = true }
        gradle { allowedUpdates = 'minor' }
    }
}

Here org.example:library permits minor updates even in :app: its exact rule wins over the group rule. The global prerelease setting still applies because the exact rule does not change that field. Inventory collection does not apply update policies; checks and interactive discovery do.

Version exclusions#

Exact exclusions and regex exclusions are combined with OR. Regexes use find(): anchor with ^ and $ to match a whole version, and use (?i) for case-insensitive matching. Patterns inspect original versions before normalization. They remain active when prereleases are enabled and do not redefine prerelease detection.

depLens {
    rules {
        global { ignoredVersionPatterns.set(listOf("(?i)-redhat(?:[.-]|$)")) }
        dependency("org.example:library") { includePreReleases.set(true) }
        plugin("org.example.tool") { ignoredVersionPatterns.set(emptyList()) }
    }
}

depLens {
    rules {
        global { ignoredVersionPatterns = [/(?i)-redhat(?:[.-]|$)/] }
        dependency('org.example:library') { includePreReleases = true }
        plugin('org.example.tool') { ignoredVersionPatterns = [] }
    }
}

The plugin rule clears inherited pattern exclusions without clearing exact-version exclusions. Invalid patterns fail configuration. Ignoring a version does not make that installed baseline unresolvable; it only removes update candidates. Lower eligible candidates remain available. Entries with excluded candidates retain IGNORED evidence in reports.

Version and prerelease patterns#

Only exact dependency(...) and plugin(...) rules support these patterns. They are not valid on global, project, group, platform or wrapper rules or section defaults. Use strings: Groovy slashy strings are supported; a ~ Pattern object is not.

versionPattern matches the entire current and candidate version. Both must provide numeric named major, minor, patch captures. Malformed regexes or missing required groups fail configuration. A version mismatch, absent optional capture or nonnumeric capture yields unknown classification with no automatic fallback. major permits unknown tiers; minor and patch exclude them. Matching major/minor captures make a newer candidate patch-tier even when only an uncaptured fourth segment changes. Ordering still uses Gradle's comparator unless normalization is configured.

preReleasePattern uses find() and replaces automatic detection completely. A match means prerelease; no match means stable for DepLens. Include every relevant marker: a pattern that only matches eap treats rc as stable. (?!) disables prerelease detection for that component. Detected prereleases still require includePreReleases = true to become eligible.

depLens {
    rules {
        dependency("org.json:json") {
            versionPattern.set("""^(?<major>[0-9]{4})(?<minor>[0-9]{2})(?<patch>[0-9]{2})$""")
            allowedUpdates.set("minor")
        }
        plugin("org.sonarqube") {
            preReleasePattern.set("""(?i)(?:alpha|beta|rc|eap)[0-9]*$""")
        }
    }
}

depLens {
    rules {
        dependency('org.json:json') {
            versionPattern = /^(?<major>[0-9]{4})(?<minor>[0-9]{2})(?<patch>[0-9]{2})$/
            allowedUpdates = 'minor'
        }
        plugin('org.sonarqube') {
            preReleasePattern = /(?i)(?:alpha|beta|rc|eap)[0-9]*$/
        }
    }
}

The JSON example deliberately maps year/month/day to major/minor/patch: new day = patch, new month = minor, new year = major. This is a user-defined numbering policy, not a compatibility guarantee. --info and JSON retain the effective patterns and unknown-classification diagnostics.

Version normalization#

Set versionNormalizationPattern and versionNormalizationReplacement together in an exact dependency or plugin rule. Invalid scopes, regexes or replacement references fail configuration. The pair is inherited together.

Java replaceAll creates comparison keys. Nonmatching versions retain their original keys; empty keys fail the query. Keys affect ordering, newer-version comparison, automatic tiers, recommendation limits and interactive choices. Equal normalized keys compare as equivalent. Original versions remain in repository requests, reports and source edits. Custom versionPattern, prerelease checks and exclusions still inspect the original versions. Strict selectors and forced versions retain Gradle's selection behavior.

depLens {
    rules {
        dependency("org.apache.directory.server:apacheds-core-api") {
            versionNormalizationPattern.set("""[.]AM(?=[0-9]+$)""")
            versionNormalizationReplacement.set("-M")
            preReleasePattern.set("""(?i)[.-](?:AM|M)[0-9]+$""")
            includePreReleases.set(true)
        }
    }
}

depLens {
    rules {
        dependency('org.apache.directory.server:apacheds-core-api') {
            versionNormalizationPattern = /[.]AM(?=[0-9]+$)/
            versionNormalizationReplacement = '-M'
            preReleasePattern = /(?i)[.-](?:AM|M)[0-9]+$/
            includePreReleases = true
        }
    }
}

This orders 2.0.0-M24 < 2.0.0.AM25 < 2.0.0.AM26 using keys 2.0.0-M24, 2.0.0-M25, 2.0.0-M26. Milestones require the explicit prerelease opt-in shown. Candidate graph checks try original versions in normalized order and preserve consumer restrictions. See the full reference for diagnostics and query-reuse details.

CI failure behavior#

failIfChecksIncomplete and section-level failIfUpdatesFound are independent. The former checks completion; the latter checks update availability. Enable both when CI should reject either an incomplete result or available dependency updates:

depLens {
    failIfChecksIncomplete.set(true)
    dependencies { failIfUpdatesFound.set(true) }
    plugins { failIfUpdatesFound.set(true) }
    gradle { failIfUpdatesFound.set(true) }
}

depLens {
    failIfChecksIncomplete = true
    dependencies { failIfUpdatesFound = true }
    plugins { failIfUpdatesFound = true }
    gradle { failIfUpdatesFound = true }
}

Reports and summaries are written before failing. Incomplete checks take precedence when both conditions apply. Failure policies evaluate the full analyzed scope; output filters cannot hide a failure. Available-only versions count for failIfUpdatesFound, even if the build does not recommend them.

Repository failures, incomplete inventories and unchecked selected targets can trigger incomplete-check failure. NO_MATCHING_CANDIDATES is a successful policy result. Pinned entries, local components, wrapperless builds and deliberately unselected component types do not count as unchecked update targets. A completed fast check is complete for its chosen mode. Inventory-only and interactive tasks do not enforce either failure policy. Gradle task failure is used; there is no separate custom exit-code scheme.

Command line and environment#

Task options follow the task name. Gradle global options apply to the invocation.

./gradlew depLensCheck --fast --console-mode standard
./gradlew depLensCheckDependencies --offline --info
./gradlew depLensCheck --configuration-cache
./gradlew depLensCheck -Pdeplens.inventory.checkBuildSrc=false
./gradlew depLensInteractiveUpdate

Configuration Cache and Isolated Projects support does not change the source-edit safeguards. Complex captured resolution rules may require cache degradation or --no-configuration-cache on older Gradle; see the full compatibility reference.

Repositories and source editing#

Repositories, credentials, repository order and content filters belong to Gradle's repositories, pluginManagement.repositories and buildscript repositories. DepLens uses the originating context. It does not have separate repository, transport-concurrency or delay settings. Gradle parallel project scheduling and worker limits control project concurrency. JSON reports accompany text output under build/reports/deplens/.

BOM-managed dependencies update through their owning BOM. Shared version values must have common candidates across all checked consumers. Pins or incomplete checks protect the shared source. Dynamic selectors remain unchanged during bulk selection; arrow selection may explicitly convert one to a fixed version.

The interactive task edits literal catalogs, properties, variables, dependency and plugin declarations, settings and wrapper URLs. Computed, generated or ambiguous sources stay read-only. Snapshot and overlap checks run before writes. Applying updates runs no build, tests or rollback; write failures can leave partial changes. Graph compatibility does not guarantee compilation or artifact availability.