Caupain

Caupain is a tool designed to help keep Gradle version catalogs up to date. Unlike other dependency update tools, it focuses on being fast and simple by using the version catalog as the single source of truth and only handling Maven repositories.

Key characteristics:

• Fast: It does not plug into Gradle, avoiding the long runtimes associated with Gradle dependency resolution.
• Non-intrusive: It does not change your files automatically; it only reports available updates and where to find information.
• Maven-focused: It specifically targets Maven repositories within your version catalogs.

Policies filter available updates based on specific criteria. You can use predefined policies or define a custom logic block via tasks.withType<DependenciesUpdateTask>.

Predefined Policies:

• StabilityLevelPolicy: Only suggests updates with stability $\ge$ current version (e.g., won't suggest alpha if you use beta). This is the default.
• GuavaAndroidPolicy: Specifically for Guava, ensures updates match the suffix (e.g., -android vs -jre) to avoid incorrect version jumps.
• AlwaysPolicy: Accepts all updates.

Custom Policies: Use selectIf to define custom logic. Inside the block, you have access to dependency, currentVersion, and updatedVersion.

tasks.withType<DependenciesUpdateTask> {
    // Use a predefined policy
    selectIf(StabilityLevelPolicy)

    // Define a custom policy
    selectIf {
        updatedVersion.text == "1.0.0"
    }
}

By default, Caupain searches all repositories in order. You can optimize this by defining component filtering using an array of tables in your TOML configuration. This allows you to specify which includes or excludes apply to specific repositories.

Note: The [[ repositories ]] array of tables must be at the very end of the configuration file to be parsed correctly.

# Repository block in array of tables must be at the end
[[ repositories ]]
default = "mavenCentral"
includes = [
    { group = "com.example", name = "example-lib" },
    { group = "com.example2.**" }
]
excludes = [
    { group = "com.other" }
]

[[ repositories ]] 
url = "http://www.example.com/repo"
includes = [
    { group = "com.example", name = "example-lib" }
]

You can prevent specific dependencies or versions from being suggested for updates directly within your libs.versions.toml file using the #ignoreUpdates comment. This can be placed on the same line as the definition or as a full-line comment immediately preceding it. You can also use #noinspection NewerVersionAvailable for compatibility with IntelliJ IDEA.

[versions]
my-excluded-version-ref = "1.0.0" #ignoreUpdates
#ignoreUpdates
my-regular-ref = "1.0.0"

[libraries]
my-excluded-lib = { module = "com.example:example", version.ref = "my-excluded-version-ref" } #ignoreUpdates
my-regular-lib = { module = "com.example:example", version.ref = "my-regular-ref" }

[plugins]
my-excluded-plugin = { id = "com.example.plugin", version.ref = "my-excluded-version-ref" } #ignoreUpdates

To build the Caupain binaries on your local machine, use the Gradle wrapper from the project root.

./gradlew :cli:assembleAll

To automatically update your version catalog and the Gradle wrapper with the latest versions found by Caupain, use the replaceOutdatedDependencies task.

Requirements and Constraints:

• This task only works if there is exactly one version catalog provided in the project.
• The onlyCheckStaticVersions parameter must be set to true (which is the default behavior).
• This task also triggers the Gradle wrapper task to update your Gradle wrapper to the latest version.

Warning: Use this task with care as it performs automated writes to your configuration files.

./gradlew replaceOutdatedDependencies

Caupain can be integrated into your workflow in two ways:

1. Command Line Tool (CLI): Use it as a standalone binary. Refer to cli/README.md for installation and command usage.
2. Gradle Plugin: Integrate it directly into your Gradle builds. Refer to gradle-plugin/README.md for setup instructions.

Choose the method that best fits your CI/CD pipeline or local development environment.

Use the --in-place option to automatically update your version catalog with the latest versions found by Caupain. This replaces existing versions in the catalog and will also update the Gradle wrapper properties file if a Gradle version update is detected.

Requirements for in-place updates:

1. There must be exactly one version catalog provided.
2. The onlyCheckStaticVersions parameter must be set to true (which is the default behavior).

Note: This option is intended for careful use and cannot be configured via a permanent configuration setting to prevent accidental updates.

caupain --in-place