{"id":13610624,"url":"https://github.com/littlerobots/version-catalog-update-plugin","last_synced_at":"2026-01-14T02:45:04.941Z","repository":{"id":37824287,"uuid":"422557181","full_name":"littlerobots/version-catalog-update-plugin","owner":"littlerobots","description":"Gradle plugin for updating a project version catalog","archived":false,"fork":false,"pushed_at":"2025-09-27T10:42:00.000Z","size":536,"stargazers_count":618,"open_issues_count":6,"forks_count":23,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-27T12:08:31.913Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/littlerobots.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"hvisser"}},"created_at":"2021-10-29T11:56:35.000Z","updated_at":"2025-09-27T10:42:03.000Z","dependencies_parsed_at":"2025-09-03T15:15:59.527Z","dependency_job_id":"260abcf4-72c0-4ab2-a358-d7d71060fee3","html_url":"https://github.com/littlerobots/version-catalog-update-plugin","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/littlerobots/version-catalog-update-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlerobots%2Fversion-catalog-update-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlerobots%2Fversion-catalog-update-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlerobots%2Fversion-catalog-update-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlerobots%2Fversion-catalog-update-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/littlerobots","download_url":"https://codeload.github.com/littlerobots/version-catalog-update-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlerobots%2Fversion-catalog-update-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:01:46.401Z","updated_at":"2026-01-14T02:45:04.929Z","avatar_url":"https://github.com/littlerobots.png","language":"Kotlin","funding_links":["https://github.com/sponsors/hvisser"],"categories":["Kotlin","Gradle插件"],"sub_categories":["文件同步"],"readme":"# Version catalog update plugin\n[![gradlePluginPortal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/nl/littlerobots/version-catalog-update/nl.littlerobots.version-catalog-update.gradle.plugin/maven-metadata.xml.svg?label=gradlePluginPortal)](https://plugins.gradle.org/plugin/nl.littlerobots.version-catalog-update)\n[![Maven Central](https://img.shields.io/maven-central/v/nl.littlerobots.vcu/plugin)](https://search.maven.org/search?q=g:nl.littlerobots.vcu%20a:plugin)\n\nThis plugin helps to keep the versions in a Gradle [version catalog toml file](https://docs.gradle.org/current/userguide/platforms.html) up to date.\n\n# Getting started\nThis plugin requires Gradle 7.2 or up. [Version catalogs](https://docs.gradle.org/current/userguide/platforms.html) are a Gradle incubating feature for versions lower than 7.4, check out the documentation on how to enable this feature for those versions.\n\nThe version catalog plugin is hosted on the [Gradle Plugin portal](https://plugins.gradle.org/plugin/nl.littlerobots.version-catalog-update) and Maven Central. [Snapshots](#snapshot-versions) are only published to Maven Central. To use Maven Central, be sure to include\nit in your plugin repositories, for example in `settings.gradle`:\n\n```\npluginManagement {\n    repositories {\n      mavenCentral()\n    }\n}\n```\nIn your `build.gradle[.kts]`:\n\n\u003cdetails open\u003e\n\u003csummary\u003ebuild.gradle\u003c/summary\u003e\n\n```groovy\nplugins {\n  id \"nl.littlerobots.version-catalog-update\" version \"\u003clatest version\u003e\"\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ebuild.gradle.kts\u003c/summary\u003e\n\n```kotlin\nplugins {\n  id(\"nl.littlerobots.version-catalog-update\") version \"\u003clatest version\u003e\"\n}\n```\n\n\u003c/details\u003e\n\nWhen using the plugins block, the classpath dependency is `nl.littlerobots.vcu:plugin:\u003cversion\u003e`\n\n## Defining repositories\nThe plugin needs to be able to resolve the dependencies of your project. This means that you'll have to configure repositories for the root project and not just for your subproject(s). If dependencies cannot be resolved, the plugin will tell you. The easiest way to do declare repositories for your project is to [declare your dependencies in settings.gradle](https://docs.gradle.org/current/userguide/centralizing_repositories.html). Also note that plugins will be resolved using the repositories declared in [pluginManagement configuration](pluginManagement).\n\n## Upgrading\nEarlier versions of this plugin used the  [versions plugin](https://github.com/ben-manes/gradle-versions-plugin) to resolve\ndependencies. This plugin is no longer required and version selection is configured using the `versionSelector` option.\n\n# Selecting dependency versions\nBy default, a stable version will be selected, based on the version name, unless the current version is already considered unstable and a newer version exists. A version is considered stable if it isn't a snapshot or alpha version.\nSee the [VersionSelectors](https://github.com/littlerobots/version-catalog-update-plugin/blob/main/plugin/src/main/kotlin/nl/littlerobots/vcu/plugin/resolver/VersionSelectors.kt#L20) class for the exact definition.\n\nThe selection can be customized by configuring a version selector:\n\n\u003cdetails open\u003e\n\u003csummary\u003ebuild.gradle\u003c/summary\u003e\n\n```groovy\nversionCatalogUpdate {\n    versionSelector {\n        // here 'it' is a ModuleVersionCandidate that can be used to determine if the version\n        // is allowed, returning true if it is.\n        !(it.candidate.version.contains('SNAPSHOT') || it.candidate.version.contains('ALPHA'))\n    }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ebuild.gradle.kts\u003c/summary\u003e\n\n```kotlin\nimport nl.littlerobots.vcu.plugin.versionSelector\n\nversionCatalogUpdate {\n    versionSelector {\n        // here 'it' is a ModuleVersionCandidate that can be used to determine if the version\n        // is allowed, returning true if it is.\n        !(it.candidate.version.contains(\"SNAPSHOT\") || it.candidate.version.contains(\"ALPHA\"))\n    }\n}\n```\n\u003c/details\u003e\n\nOr use one of the predefined selectors:\n\n```kotlin\nimport nl.littlerobots.vcu.plugin.resolver.VersionSelectors\n\n// LATEST to accept any latest version, STABLE to select only stable versions or\n// PREFER_STABLE (default setting) to accept unstable versions only if the catalog already uses an unstable version\nversionSelector(VersionSelectors.STABLE)\n```\n\n## Updating the `libs.versions.toml` file\nTo update the catalog file at any time run `./gradlew versionCatalogUpdate`. This takes care of the following:\n\n* New available versions will be updated in the catalog, retaining existing version groups if they exist\n* Keys used in `versions`, `libraries`, `bundles` and `plugins` will be sorted by name [configurable](#configuration)\n* `bundles` will be updated so that they only contain valid keys. Keys in a bundle will be sorted.\n\nVersions that are not used and not marked to be kept will be removed when the catalog is updated. This is [configurable](#configuration).\n\n### Interactive mode\nUpdating all dependencies at once is without testing is generally not recommended. When using a version control system, changes to the version catalog can be rolled back\nby comparing a diff, but for large updates this may be inconvenient. In these cases, interactive mode might help.\n\nWhen running `./gradlew versionCatalogUpdate --interactive` the `libs.versions.toml` file will not be directly be updated, in stead\na `libs.versions.updates.toml` file will be created containing the entries that would be updated and any pinned entries\nthat can be updated. This file uses the short form dependency notation without any `version.ref`s. Pinned entries are commented\nby default, all other entries are uncommented. To skip updating an entry in the TOML file it can be commented out or removed completely.\nIt's also possible to edit the entry if that's desired.\n\nTo apply the changes to the `libs.versions.toml` file, run `./gradlew versionCatalogApplyUpdates`. This will also\nupdate `version.ref`s and `versions` in the same way as `versionCatalogUpdate` would.\n\nNote that any comments and any other TOML tables than `[libraries]` and `[plugins]` will be ignored when applying the changes.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample libs.versions.updates.toml\u003c/summary\u003e\n\n```\n# Version catalog updates generated at 2022-08-19T16:00:29.757349\n#\n# Contents of this file will be applied to libs.versions.toml when running versionCatalogApplyUpdates.\n#\n# Comments will not be applied to the version catalog when updating.\n# To prevent a version upgrade, comment out the entry or remove it.\n#\n[libraries]\n# @pinned version 4.9.3 (antlr) --\u003e 4.10.1\n#antlr = \"org.antlr:antlr4:4.10.1\"\n# From version 2.5.4 (asciidoctorj) --\u003e 2.5.5\nasciidoctorj = \"org.asciidoctor:asciidoctorj:2.5.5\"\n# From version 2.1.2 (asciidoctorjPdf) --\u003e 2.1.6\nasciidoctorjPdf = \"org.asciidoctor:asciidoctorj-pdf:2.1.6\"\n\n[plugins]\n# Updated from version 1.20.0\ndetekt = \"io.gitlab.arturbosch.detekt:1.21.0\"\n# Updated from version 1.7.0\ndokka = \"org.jetbrains.dokka:1.7.10\"\n```\n\n\u003c/details\u003e\n\n### Formatting only\nRunning the `versionCatalogUpdate` task will also format the catalog. For formatting libraries and plugins, the plugin will use\nthe \"short\" syntax if possible (`com.group:module:version` for libraries). If a `version.ref` is applied, it will be kept.\nBy default, entries in the version catalog will be sorted alphabetically. Note that during formatting some whitespace might\nbe lost due to parsing the toml file and rewriting it.\n\nTo format the existing `libs.versions.toml` file without updating library versions, you can run `./gradlew versionCatalogFormat`.\nThis comes in handy when you added an entry to the version catalog, but aren't ready yet to update any dependencies.\n\n## Informational output\nIn some cases the plugin will output some additional messages when checking for updates.\n\n### Dependencies with invalid versions\nThe versions plugin will report dependencies with invalid versions, which are dependencies that don't match the declared version for some reason. This can happen when you specify a version that does not exist, but some other dependency is pulling in an existing version of the same dependency.\nIn that case, your build will not fail, but the version used isn't the version that was specified in the catalog file. The plugin will show a warning and update the catalog to the correct version in that case.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample warning\u003c/summary\u003e\n\n```\nThere are libraries with invalid versions that could be updated:\n - androidx.activity:activity-compose (androidx-activity-activity-compose) -\u003e 1.9.2\n```\n\u003c/details\u003e\n\n### Rich versions\nA version may be specified as a rich version in the toml file. In that case the plugin cannot determine if the dependency should be updated and will leave it alone.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample output\u003c/summary\u003e\n\n```\nThere are libraries using a version condition that could be updated:\n - androidx.appcompat:appcompat (androidx-appCompat ref:appCompat) -\u003e 1.4.1\n```\n\u003c/details\u003e\n\n### Pinned versions (see below)\nWhen an entry in the catalog is affected by a pin that you have configured, the plugin will leave that entry alone, but tell you that there's a possible update.\n\n\u003cdetails\u003e\n\u003csummary\u003eexample output\u003c/summary\u003e\n\n```\nThere are updates available for pinned entries in the version catalog:\n - androidx.appcompat:appcompat (androidx-appcompat) 1.4.0 -\u003e 1.4.1\n```\n\u003c/details\u003e\n\n\n## Configuration\nThe plugin can be configured using the `versionCatalogUpdate` block in the build file:\n\n\u003cdetails open\u003e\n\u003csummary\u003ebuild.gradle\u003c/summary\u003e\n\n```groovy\nversionCatalogUpdate {\n    // sort the catalog by key (default is true)\n    sortByKey = true\n    // Referenced that are pinned are not automatically updated.\n    // They are also not automatically kept however (use keep for that).\n    pin {\n        // pins all libraries and plugins using the given versions\n        versions = [\"my-version-name\", \"other-version\"]\n        // pins specific libraries that are in the version catalog\n        libraries = [libs.my.library.reference, libs.my.other.library.reference]\n        // pins specific plugins that are in the version catalog\n        plugins = [libs.plugins.my.plugin, libs.plugins.my.other.plugin]\n        // pins all libraries (not plugins) for the given groups\n        groups = [\"com.somegroup\", \"com.someothergroup\"]\n    }\n    keep {\n        // keep has the same options as pin to keep specific entries\n        // note that for versions it will ONLY keep the specified version, not all\n        // entries that reference it.\n        versions = [\"my-version-name\", \"other-version\"]\n        // keep versions without any library or plugin reference\n        keepUnusedVersions = true\n    }\n\n    // Return true in the version selector function to accept the updated version\n    // For more details refer to the chapter earlier in this README\n    versionSelector {\n        ///\n    }\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003ebuild.gradle.kts\u003c/summary\u003e\n\n```kotlin\nversionCatalogUpdate {\n    // sort the catalog by key (default is true)\n    sortByKey.set(true)\n    // Referenced that are pinned are not automatically updated.\n    // They are also not automatically kept however (use keep for that).\n    pin {\n        // pins all libraries and plugins using the given versions\n        versions.add(\"my-version-name\")\n        versions.add(\"other-version\")\n        // pins specific libraries that are in the version catalog\n        libraries.add(libs.my.library.reference)\n        libraries.add(libs.my.other.library.reference)\n        // pins specific plugins that are in the version catalog\n        plugins.add(libs.plugins.my.plugin)\n        plugins.add(libs.plugins.my.other.plugin)\n        // pins all libraries (not plugins) for the given groups\n        groups.add(\"com.somegroup\")\n        groups.add(\"com.someothergroup\")\n    }\n    keep {\n        // keep has the same options as pin to keep specific entries\n        versions.add(\"my-version-name\")\n        versions.add(\"other-version\")\n        // keep versions without any library or plugin reference\n        keepUnusedVersions.set(true)\n    }\n\n    // Return true in the version selector function to accept the updated version\n    // For more details refer to the chapter earlier in this README\n    versionSelector {\n        ///\n    }\n}\n```\n\n\u003c/details\u003e\n\n### Keeping and pinning entries with a TOML comment\nTo keep an entry in the TOML file, or pin it to a specific version you can also use annotations in TOML comments.\nThis functions in the same way as specifying the `keep` and `pin` configuration in the build file.\nFor a `@keep` or `@pin` annotation to be recognised, the comment must start with a single `#`.\n\n```toml\n[versions]\n# @keep this version, for example because it is not used in a dependency declaration\nminSdk = \"21\"\n# Pinning the version will keep every library using this version on 1.6.10\n# @pin\nkotlin = \"1.6.10\"\n\n[libraries]\n# @pin this library to version 1.0\nmy-library = \"com.example.library:1.0\"\n```\n\n## Managing additional version catalogs\nThe default tasks operate on the default version catalog file, `libs.versions.toml` in the `gradle` directory\nof a project. Additional version catalogs can be configured within the `versionCatalogUpdate` extension:\n\n\u003cdetails open\u003e\n\u003csummary\u003ebuild.gradle\u003c/summary\u003e\n\n```groovy\nversionCatalogUpdate {\n    // These options will be set as default for all version catalogs\n    sortByKey = true\n    // Referenced that are pinned are not automatically updated.\n    // They are also not automatically kept however (use keep for that).\n    pin {\n        ...\n    }\n    keep {\n        ...\n    }\n    versionCatalogs {\n        myOtherCatalog {\n            catalogFile = file(\"catalogs/mycatalog.versions.toml\")\n            // not sorted\n            sortByKey = false\n        }\n        special {\n            catalogFile = file(\"catalogs/special.versions.toml\")\n            // overrides the options set above\n            keep {\n                keepUnusedVersions = true\n            }\n            versionSelector(VersionSelectors.LATEST)\n        }\n    }\n}\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003ebuild.gradle.kts\u003c/summary\u003e\n\n```kotlin\nversionCatalogUpdate {\n    // These options will be set as default for all version catalogs\n    sortByKey.set(true)\n    // Referenced that are pinned are not automatically updated.\n    // They are also not automatically kept however (use keep for that).\n    pin {\n        ...\n    }\n    keep {\n        ...\n    }\n    versionCatalogs {\n        create(\"myOtherCatalog\") {\n            catalogFile.set(file(\"catalogs/mycatalog.versions.toml\"))\n            // not sorted\n            sortByKey.set(false)\n        }\n        create(\"special\") {\n            catalogFile.set(file(\"catalogs/special.versions.toml\"))\n            // overrides the options set above\n            keep {\n                keepUnusedVersions.set(true)\n            }\n            versionSelector(VersionSelectors.LATEST)\n        }\n    }\n}\n```\n\u003c/details\u003e\n\nBy configuring additional version catalogs, new tasks in the form of `versionCatalogUpdate\u003cName\u003e` will get added.\nFor example, when declaring a `myOtherCatalog` catalog, the tasks `versionCatalogUpdateMyOtherCatalog`, `versionCatalogFormatMyotherCatalog`\nand `versionCatalogAppyUpdatesMyOtherCatalog` are configured. These work the same as the default tasks\nand have the same available options. Each version catalog definition can specify configuration for\n`sortByKey` and the `pin` and `keep` blocks. If not defined, the default options will be applied for those options.\n\n### Changing the default version catalog\nBy the default the plugin uses `gradle/libs.versions.toml` as the primary version catalog file.\nTo change the default, configure it in the `versionCatalogUpdate` block:\n\n\u003cdetails open\u003e\n\u003csummary\u003ebuild.gradle\u003c/summary\u003e\n\n```groovy\nversionCatalogUpdate {\n    catalogFile = file(\"path/to/the/catalog.toml\")\n}\n```\n\u003c/details\u003e\n\u003cdetails open\u003e\n\u003csummary\u003ebuild.gradle.kts\u003c/summary\u003e\n\n```kotlin\nversionCatalogUpdate {\n    catalogFile.set(file(\"path/to/the/catalog.toml\"))\n}\n```\n\u003c/details\u003e\n\n## Snapshot versions\nFor snapshots versions add the Sonatype snapshot repository `https://oss.sonatype.org/content/repositories/snapshots/`.\n\n## Known issues and limitations\n* The TOML file will be updated and formatted by this plugin; this is by design. If this is undesirable then the  [versions plugin](https://github.com/ben-manes/gradle-versions-plugin) is probably what you are looking for.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlerobots%2Fversion-catalog-update-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flittlerobots%2Fversion-catalog-update-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlerobots%2Fversion-catalog-update-plugin/lists"}