%2B)&replace=%24%3Cversion%3E&label=homebrew){kind=icon}
%24&replace=%241&flags=m&label=debian){kind=icon}
This is the command-line version of the tool. It is available as a single executable file for Linux, macOS, Windows, and as a JAR file alongside its launch script.
You can install Caupain via Homebrew by running the following command:
brew install deezer/repo/caupainFor Debian-based distributions, you'll first need to add the repository to your system:
sudo mkdir -p /usr/local/share/keyrings
sudo curl -sfLo /usr/local/share/keyrings/deezer.gpg https://research.deezer.com/debian-repo/gpg.key
echo "deb [signed-by=/usr/share/local/keyrings/deezer.gpg] https://research.deezer.com/debian-repo/ stable main" | sudo tee -a /etc/apt/sources.list.d/deezer.list
sudo apt updateYou can then install Caupain with the following command:
sudo apt install caupainYou can install Caupain via Chocolatey by running the following command:
choco install caupainYou can also download the latest release from the releases page
or build it yourself by cloning the repository and running ./gradlew :cli:buildCurrentArchBinary in the root directory.
Usage: caupain [<options>]
Options:
-i, --version-catalog=<path> Version catalog path. Use multiple times to use
multiple version catalogs (default:
gradle/libs.versions.toml)
--gradle-wrapper-properties=<path>
Gradle wrapper properties path (default:
gradle/wrapper/gradle-wrapper.properties)
-e, --excluded=<text> Excluded keys
-c, --config=<path> Configuration file (default: caupain.toml)
--policy-plugin-dir=<path> Custom policies plugin dir
-p, --policy=<text> Update policy (default: stability-level).
Multiple policies can be specified by using a
comma-separated list, and will be combined (a
version must satisfy all policies to be
accepted).
--list-policies List available policies
--gradle-stability-level=(stable|rc|milestone|release-nightly|nightly)
Gradle stability level (default: stable)
-t, --output-type=(console|html|markdown|json)
Output type (default: console)
-o, --output=<file> Report output path (or - if you want to ouput
to standard output). If a file is specified,
only used if a single output type is specified
(default:
build/reports/dependencies-update.(html|md|json))
--output-dir=<path> Report output dir. Only used if multiple output
types are specified, and output is not set to
standard output (default: build/reports)
--output-base-name=<text> Report output base name, without extension.
Only used if multiple output types are
specified, and output is not set to standard
output (default: dependencies-update)
--show-version-references Show versions references update summary in the
report
--in-place Replace versions in version catalog in place
--search-release-notes Search for release notes for updated versions
on GitHub
--github-token=<text> GitHub token for searching release notes. Taken
from CAUPAIN_GITHUB_TOKEN environment variable
if not set
--cache-dir=<path> Cache directory. This is not used if --no-cache
is set (default: user cache dir)
--no-cache Disable HTTP cache
--clean-cache Clean the cache before running
-q, --quiet Suppress all output
-v, --verbose Verbose output
-d, --debug Debug output
--debug-http-calls Enable debugging for HTTP calls
--verify-existence Verify that .pom file exists before accepting
version updates (warning: may slow down checks)
--do-not-check-self-updates Do not check for Caupain updates on GitHub
--version Show the version and exit
-h, --help Show this message and exit
For a base usage, just launch the caupain command in the root of your project, and it will find your
version catalog and generate a report in console.
Most of the options correspond to options in the configuration file, see the configuration file section for more information.
You can configure the tool either via a configuration file in TOML format or via command line options. If present, configuration in the file will override command line options.
# Configures the Maven repositories where the dependencies are hosted.
# If none are specified, the default repositories "google" and "mavenCentral" are used.
# Repositories are queried in the order they are specified.
repositories = [
"mavenCentral", # Default repositories "google", "mavenCentral" and "gradlePluginPortal" are provided as shortcuts
{ url = "http://www.your.repo/maven" }, # You can also specify a custom repository
{ url = "http://www.your.secure.repo/maven", user = "my-user", password = "my-password" }, # You can also specify password credentials
{ url = "http://www.your.secure.repo/maven", authHeaderName = "my-header-name", authHeaderValue = "my-header-value" } # Or header credentials
]
# Configures the Maven repositories where the plugins are hosted.
# If none are specified, the default repositories "gradlePluginPortal", "google" and "mavenCentral" are used.
# Repositories are queried in the order they are specified.
# Syntax is the same as for the "repositories" key.
pluginRepositories = [ "google" ]
# Version catalog path. Default is "gradle/libs.versions.toml".
versionCatalogPath = "another/path/to/libs.versions.toml"
# You can also define multiple version catalogs. Warning: defining this will override the previous single path
versionCatalogPaths = [ "libs.versions.toml", "another/path/to/libs.versions.toml" ]
# Policy name to use. See the documentation section about policies for more information
policy = "stability-level"
# Policy names to use. See the documentation section about policies for more information
policies = [ "stability-level" ]
# Policy plugin directory. This is the directory where the custom policies are located.
# Only applies to JVM, see the documentation section about policies for more information
policyPluginDir = "path/to/policy/plugin/dir"
# Filter for specific dependencies. You can use this to restrict the updates that will be suggested.
filters = [
# You can use a prefix version filter. This will only accept updates with the 1. prefix, like
# 1.0.0, 1.5.2, but not 2.0.0.
{ group = "com.google.guava", name = "guava", versionFilter = "1.+" },
# or a range version filter. This will only accept updates with a version greater than 1.2 and
# less than or equal to 1.5.
{ group = "com.google.guava", name = "guava", versionFilter = "(1.2, 1.5]" },
# If the name is not specified, the group is interpreted as a glob and the filter will be
# applied to all dependencies matching the glob
{ group = "com.google.**", versionFilter = "1.+" },
# You can also use this for plugins
{ id = "filtered.plugin.id", versionFilter = "1.+" },
]
# Cache directory. This is the directory where the HTTP cache is stored. Defaults to the user cache
# directory.
cacheDir = "path/to/cache/dir"
# Output type. Can be "console", "html", "markdown" or "json". Default is "console".
outputType = "html"
# Output path, for HTML, Markdown and JSON output types. Default is build/reports/dependencies-update.(html|md|json)
outputPath = "path/to/output/file.html"
# Whether to show a block in the report that summarizes the updates from the version block in
# the version catalog. This allows to quickly see what to update if you use the versions block heavily.
# Default is false.
showVersionsReferences = true
# Path to the Gradle wrapper properties file. This is used to check for an update in the Gradle wrapper.
# Default is "gradle/wrapper/gradle-wrapper.properties".
gradleWrapperPropertiesPath = "/path/to/properties/file"
# By default, Caupain only checks updates for static versions in the version catalog (versions like 1.0.0 or
# 1.0.0-SNAPSHOT).
# The rationale behind this is that dynamic versions or rich versions indicate that the version range is
# already specified, and that an update isn't needed. If this value is passed to false, Caupain will try
# to find the latest version for all dependencies, even if they are dynamic or rich versions.
# This is where the result may not be exactly what you want, because Caupain will not use Gradle to
# try to resolve the exact dependency that is used.
# Default is true.
onlyCheckStaticVersions = false
# The stability level to use for Gradle version checks. Default is stable. Possible values are: stable,
# rc, milestone, releaseNightly, nightly.
gradleStabilityLevel = "stable"
# Whether to show a section in the report about the ignored available updates. Default is false.
checkIgnored = true
# GitHub token, used to search for release notes on GitHub.
githubToken = "your-token"
# Whether to search for release notes on GitHub and display the link to them in the results.
# If a GitHub token is provided, this will be true by default.
searchReleaseNotes = true
# Whether to verify that .pom files exist in the repository before accepting a version as valid.
# When enabled, only versions with available POM metadata will be considered for updates.
# This helps ensure that suggested versions are actually downloadable.
# Note: This may slow down the checking process as it adds extra network requests.
# Default is false.
verifyExistence = true
# Whether to skip the GitHub self-update check. Default is false.
doNotCheckSelfUpdates = trueBy default, Caupain will search for dependencies in all repositories, going through them in order until the dependency is found. If you want to specify what kind of dependencies are in each repository, you can set up component filtering by defining repositories using a TOML array of tables like so:
#... The rest of your configuration
# Repository block in array of tables needs to be at the very end of the configuration file to be
# parsed correctly
[[ repositories ]]
# If the repository is a predefined one, you can use the shortcut name with the key "default"
default = "mavenCentral"
# If only exclusions are defined, then all components except those excluded will be searched
# for in the repository. If only inclusions are defined, then only those components will be searched
# for in the repository. If both are defined, then only the components that are included and not excluded
# will be searched for in the repository.
includes = [
{ group = "com.example", name = "example-lib" }, # You can specify a group and name
{ group = "com.example" }, # You can also only specify a group...
{ group = "com.example2.**" } # ...or use globs
]
excludes = [
{ group = "com.other" }
]
[[ repositories ]]
# This can also be done for custom repositories
url = "http://www.example.com/repo"
# The credentials can be specified in the same way as for the repositories key
user = "my-user"
password = "my-password"
authHeaderName = "my-header-name"
authHeaderValue = "my-header-value"
includes = [
{ group = "com.example", name = "example-lib" },
{ group = "com.example2.**" }
]
excludes = [
{ group = "com.other" }
]You can select what updates you want to be suggested by using a combination of exclusions and inclusions. If inclusions are defined, only updates matching the inclusions will be suggested. If exclusions are defined, updates matching the exclusions will not be suggested. If both are defined, only updates matching the inclusions and not matching the exclusions will be suggested.
# You can exclude by key. The key matches the name used in the version catalog.
excludedKeys = [ "excluded1", "excluded2" ]
# You can also exclude by group and optionally by name. If name is not specified, all dependencies
# in the group are excluded. Furthermore, if name is not specified, then group is interpreted as a glob.
excludedLibraries = [
{ group = "com.google.guava" }, # Exclude all dependencies in the group
{ group = "com.google.guava", name = "guava" }, # Exclude only the guava dependency
{ group = "com.google.**" }, # Exclude all dependencies with group starting with com.google
{ group = "com.google.*.sub" }, # Exclude all dependencies like com.google.something.sub
]
# You can exclude plugins by their id
excludedPlugins = [
{ id = "excluded.plugin.id" }
]
# You can include by key. The key matches the name used in the version catalog.
includedKeys = [ "excluded1", "excluded2" ]
# You can also include by group and optionally by name. If name is not specified, all dependencies
# in the group are included. Furthermore, if name is not specified, then group is interpreted as a glob.
includedLibraries = [
{ group = "com.google.guava" }, # Include all dependencies in the group
{ group = "com.google.guava", name = "guava" }, # Include only the guava dependency
{ group = "com.google.**" }, # Include all dependencies with group starting with com.google
{ group = "com.google.*.sub" }, # Include all dependencies like com.google.something.sub
]
# You can include plugins by their id
includedPlugins = [
{ id = "included.plugin.id" }
]Alongside the exclusion configuration, you can also exclude dependencies directly in the TOML file by
adding a #ignoreUpdates comment, either on the same line as a version reference or dependency/plugin
definition or as a full-line comment in the line just before, like so:
[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
my-regular-plugin = { id = "com.example.plugin", version.ref = "my-regular-ref" }Using #noinspection NewerVersionAvailable is also possible to be compatible with the way IntelliJ
marks ignored updates.
Policies are used to filter available updates. You can either use predefined policies or create your own. If you specify multiple policies, they will be all checked in order to determine if a version is acceptable.
There are three predefined policies available at the moment:
stability-level: This policy will only select an update if its stability is greater than or equal to the stability of the current version. This means that if you're using a beta version, alpha versions won't be suggested for you, and so on. This is the default policy used if no other policy is specified.guava-android: This policy fixes a common issue in the Android world with using Guava libraries, which is the fact that Guava have both a-jreand an-androidversion with the same version number. Due to how Gradle computes updates, the-jreversion is selected as an update for the-androidversion, which is not what you want. This policy avoids this use case by only accepting updates that have the same suffix as the current version.always: This policy will accept all updates.
Custom policies are only usable if you launch the tool via the JVM launch script.
You'll also need to use the core dependency in order to create this policy. See the core module
for more information.
You can write your custom policy by extending the Policy
interface and implementing the select method. You can take an example from StabilityLevelPolicy
in the same file if needed. You'll then need to make a JAR file of your custom policy, with a META-INF/services/com.deezer.caupain.model.Policy
file containing the fully qualified name of your class, and place the JAR file in your policyPluginDir directory.
As sample can be found in the sample plugin module of the project.
If this is a bit too difficult to do, custom policy use is way easier when using the Gradle plugin version of the tool.
If needed, you can use the --in-place option to update the version catalog in place. This will
replace the versions in the version catalog with the latest versions found by Caupain. This is
useful if you want to quickly update your version catalog without having to manually change the
versions.
This will only work if there is only one version catalog provided, and if the onlyCheckStaticVersions
parameter is set to true (this is the default behavior).
There is no corresponding configuration option for this, because it should be used with care, and we want to make sure that it is not used by accident.
Shell completions can be found in the completions directory. You can source them in
your shell to enable completions for the caupain command.
You can build binaries locally by using ./gradlew :cli:assembleAll
If you need to see what's going on and the detailed queries sent and received from the Maven repositories,
you can enable HTTP call debugging by using the --debug-http-calls option along the --debug one.
This will print all HTTP calls to the output stream and allow you to see what's going on.