Skip to content

kingsword09/gvc

BranchesTags

Repository files navigation

GVC (Gradle Version Catalog Manager)

Crates.io License Rust

A fast, standalone CLI for managing Gradle version catalogs (libs.versions.toml): check, list, explain, update, add, audit, and diagnose dependencies or plugins with confidence.

English | 简体中文

Features

  • 🚀 Direct Maven repository queries - No Gradle runtime needed, pure Rust performance
  • 📦 Multi-repository support - Maven Central, Google Maven, custom repositories with smart filtering
  • 🎯 Intelligent version detection - Semantic versioning with stability filtering (alpha, beta, RC, dev)
  • 📋 Eight commands:
    • check - View available updates without applying
    • outdated - Show outdated entries in a package-manager style table
    • update - Apply dependency updates
    • list - Display all dependencies in Maven coordinate format
    • why - Explain a catalog entry by alias or coordinate
    • audit - Find catalog quality issues such as duplicate coordinates or missing version refs
    • add - Insert dependencies or plugins directly into the catalog with version aliasing
    • doctor - Diagnose Kotlin/Android catalog consistency
  • 🔒 Version reference support - Handles [versions] table with automatic resolution
  • 🎨 Beautiful CLI output - Progress bars, colored output, clear summaries
  • ⚡ Smart request optimization - Repository filtering based on group patterns to minimize HTTP requests

Prerequisites

  • Rust stable (for building from source)
  • A Gradle project using version catalogs (gradle/libs.versions.toml)
  • Git (optional, for branch/commit features)
  • Internet connection (to query Maven repositories)

Installation

From crates.io (Recommended)

cargo install gvc

From GitHub Releases

Download pre-built binaries from the releases page:

# Linux/macOS
curl -LO https://github.com/kingsword09/gvc/releases/download/v0.2.1/gvc-linux-x86_64
curl -LO https://github.com/kingsword09/gvc/releases/download/v0.2.1/gvc-linux-x86_64.sha256
shasum -a 256 -c gvc-linux-x86_64.sha256
chmod +x gvc-linux-x86_64
sudo mv gvc-linux-x86_64 /usr/local/bin/gvc

From source

git clone https://github.com/kingsword09/gvc.git
cd gvc
cargo install --path .

Or build manually:

cargo build --release
# Binary will be in target/release/gvc

Agent skill (optional)

This repository includes a gvc agent skill that can be installed with the Vercel skills CLI:

npx skills add kingsword09/gvc --skill gvc -g -y

From a local checkout:

npx skills add . --skill gvc -g -y

The skill teaches agents how to use gvc; install the CLI binary separately with cargo install gvc or cargo install --path ..

Quick Start

gvc check              # validate project and list available upgrades
gvc outdated           # show outdated catalog entries in a table
gvc why androidx-core  # explain a catalog entry by alias or coordinate
gvc audit              # inspect catalog quality without network access
gvc update --no-git    # apply upgrades without creating a Git branch
gvc check --format json --fail-on-updates  # agent/CI-friendly update gate
gvc doctor --format json --fail-on-issues  # Kotlin/Android catalog diagnostics
  • Use --path /path/to/project if the catalog lives elsewhere; global flags may be placed before or after the command.
  • Use --catalog gradle/custom.versions.toml to target a specific catalog file inside the project.
  • Pass --verbose (or export GVC_VERBOSE=1) to inspect HTTP traffic, caching, and other diagnostics.

Usage

Command Reference

Command Purpose Key Flags
gvc check Dry-run scan that validates the project and prints available dependency/plugin upgrades. --include-unstable to add alpha/beta/RC versions; --path to target another project.
gvc outdated Prints outdated version aliases, libraries, and plugins in a package-manager style table. --include-unstable to include pre-releases; --fail-on-updates exits with code 2 for automation.
gvc update Applies or previews catalog updates, honoring stability filters and optional Git integration. --dry-run to preview; --apply to be explicit; --target "*glob*" for targeted upgrades; --no-git to skip branch/commit; --no-stable-only to include pre-releases.
gvc list Displays the resolved version catalog as Maven coordinates for quick auditing. --path to point at another project.
gvc why <query> Explains a catalog entry's coordinate, version source, duplicate aliases, and recommendations. Query by alias, library coordinate (group:artifact), or plugin id; --format json for automation.
gvc audit Checks catalog maintainability without network access. --fail-on-issues exits with code 2 when warnings/errors are found; --format json for automation.
gvc doctor Checks Kotlin, KSP, Android Gradle Plugin, and Compose catalog consistency without network access. --fail-on-issues exits with code 2 when warnings/errors are found; --format json for automation.
gvc add Inserts a new entry into [libraries] (default) or [plugins]. -P/--plugin targets plugins; --no-stable-only allows pre-releases when resolving :latest; --alias / --version-alias override generated keys.

Global automation flags:

  • --format text|json - Emits either human-readable output or a stable JSON object.
  • --quiet - Suppresses progress output in text mode.
  • --no-color - Disables ANSI color.
  • --catalog <file> - Uses an explicit version catalog file under --path.

Exit codes:

  • 0 - Command completed successfully.
  • 1 - Validation, parsing, network, Git, or write error.
  • 2 - gvc check/outdated --fail-on-updates found updates, or gvc audit/doctor --fail-on-issues found diagnostics.

Check for Updates

View available dependency updates without modifying any files:

gvc check
# or
gvc --path /path/to/project check

By default, only stable versions are shown. To include pre-release versions:

gvc check --include-unstable

For CI or agents that should fail when upgrades exist:

gvc check --format json --fail-on-updates

Show Outdated Entries

Use outdated when you want a compact package-manager style view of what can move:

gvc outdated
gvc outdated --include-unstable
gvc outdated --format json --fail-on-updates

outdated uses the same resolver as check, so it respects the Gradle repositories configured for the project and the same stable-version filtering rules.

Audit Catalog Quality

Run an offline maintainability audit for the version catalog:

gvc audit
gvc audit --format json
gvc audit --fail-on-issues

The audit currently checks:

  • version.ref values that point to missing [versions] aliases.
  • Multiple aliases pointing to the same library or plugin coordinate.
  • Inline versions that could be moved into [versions].
  • [versions] aliases not referenced by catalog libraries or plugins.
  • Multiple [versions] aliases with the same value.

List Dependencies

Display all dependencies in Maven coordinate format (useful for verification):

gvc list
gvc list --format json

Output example:

📦 Dependencies:

Libraries:
  androidx.core:core-ktx:1.12.0
  com.squareup.okhttp3:okhttp:4.12.0
  org.jetbrains.compose.runtime:runtime:1.9.0

Plugins:
  org.jetbrains.kotlin.jvm:1.9.0
  com.android.application:8.1.0

Summary:
  4 libraries
  2 plugins

Explain a Catalog Entry

Use why to inspect how an alias or coordinate is declared and resolved:

gvc why androidx-core
gvc why androidx.core:core-ktx
gvc why com.android.application --format json

The report shows the matched entry, coordinate, inline version or version.ref, resolved version, duplicate aliases for the same coordinate, and any low-risk recommendations.

Diagnose Kotlin/Android Catalogs

Run catalog-only diagnostics for Kotlin-heavy Gradle projects:

gvc doctor
gvc doctor --format json
gvc doctor --fail-on-issues

The doctor currently checks:

  • Kotlin Gradle plugin entries use one aligned version.
  • KSP versions use the expected <kotlin-version>-<ksp-version> prefix.
  • Kotlin 2.x Compose projects declare org.jetbrains.kotlin.plugin.compose.
  • The Kotlin Compose compiler plugin matches the Kotlin Gradle plugin version.
  • com.android.* plugins share one Android Gradle Plugin version.

doctor is intentionally offline and only inspects the version catalog, so it is safe for CI and agent workflows.

Update Dependencies

Apply dependency updates (stable versions only by default):

gvc update

Options

  • --stable-only - Only update to stable versions (enabled by default)
  • --no-stable-only - Allow updates to unstable versions (alpha, beta, RC)
  • --dry-run - Preview updates without writing to the catalog
  • --apply - Explicitly apply updates (default behavior)
  • --target <glob> - Limit updates to dependencies whose alias matches the glob (e.g. *okhttp*)
  • -i, --interactive - Review each proposed change before applying it
  • --filter <glob> - Backward-compatible alias for --target
  • --no-git - Skip Git operations (no branch/commit)
  • --path, -p - Specify project directory
  • --format json - Emit the applied update report as JSON

Interactive mode will pause on each candidate upgrade, showing the old/new version and letting you accept, skip, apply all remaining changes, or cancel the run.

Dry-run mode is read-only and does not require a clean Git working tree:

gvc update --dry-run
gvc update --dry-run --target kotlin --format json

Targeted Updates

When --target is provided in apply mode, GVC lists every matching library/version alias/plugin so you can pick a single target. Combine it with -i/--interactive to choose the exact version (stable or pre-release) you want to install.

# Review and pick a version for dependencies with "okhttp" in their alias
gvc update --target "*okhttp*" --interactive
  • Skip the version prompt by omitting --interactive when the target pattern matches exactly one entry; GVC selects the newest version that satisfies the stability rules. If multiple entries match, refine the target or add --interactive.
  • Include pre-releases with --no-stable-only when you want to evaluate beta/RC builds.

Examples:

# Update to stable versions only (default behavior)
gvc update

# Include unstable versions (alpha, beta, RC)
gvc update --no-stable-only

# Review each update before writing changes
gvc update --interactive

# Target a single dependency by alias pattern
gvc update --target "*okhttp*"

# Update without Git integration
gvc update --no-git

# Update a specific project
gvc update --path /path/to/project

Selective Updates

When you pass --target, GVC narrows the scope to aliases that match your glob expression (case-insensitive). The CLI will:

  1. List every matching version alias, library, or plugin.
  2. Prompt you to pick the exact entry to change.
  3. Fetch available versions from the configured repositories.
  4. In interactive mode (-i), let you choose from recent stable and pre-release versions (use m to show more, s to skip, q to cancel).
  5. Without interactive mode, automatically pick the first newer version when exactly one entry matches. If multiple entries match, GVC exits with a message asking for a narrower target or --interactive.

This makes it easy to bump a single dependency—even to a specific pre-release—without touching the rest of the catalog.

Add Dependencies or Plugins

Create new catalog entries directly from Maven or plugin coordinates:

# Libraries: group:artifact:version (default target)
gvc add androidx.lifecycle:lifecycle-runtime-ktx:2.6.2

# Plugins: plugin.id:version
gvc add -P org.jetbrains.kotlin.jvm:1.9.24

# Resolve the newest available version automatically
gvc add com.squareup.okhttp3:okhttp:latest
gvc add -P org.jetbrains.kotlin.android:latest --no-stable-only  # allow pre-releases when needed
  • GVC auto-generates catalog aliases and version keys (use --alias / --version-alias to override).
  • -P is the plugin short flag; global -p/--path is reserved for the project path.
  • Library entries are written as { module = "group:artifact", version = { ref = "<alias>" } }.
  • Plugin entries use { id = "plugin.id", version = { ref = "<alias>" } }.
  • Existing version aliases are not updated implicitly. Pass --update-version-alias only when you intentionally want the new entry to move an existing version key.
  • Coordinates are verified upstream before writing; libraries query your configured repositories, plugins query the Gradle Plugin Portal. Use --no-stable-only to include pre-release versions when resolving :latest.
  • The --path flag works exactly as with other commands.

How It Works

GVC directly queries Maven repositories without requiring Gradle:

  1. Project Validation - Checks for gradle/libs.versions.toml and gradlew
  2. Repository Configuration - Reads Gradle build files to detect configured Maven repositories
  3. TOML Parsing - Uses toml_edit to parse version catalog while preserving formatting
  4. Version Resolution:
    • Parses dependencies in all supported TOML formats
    • Resolves version references from [versions] table
    • Queries Maven repositories for latest versions via HTTP
    • Applies smart filtering based on repository group patterns
  5. Version Comparison:
    • Semantic versioning support (1.0.0, 2.1.3)
    • Filters unstable versions (alpha, beta, RC, dev, snapshot, preview, etc.)
    • Prevents version downgrades
  6. Update Application - Updates TOML file while maintaining original formatting

Supported TOML Formats

GVC supports all Gradle version catalog formats:

# Simple string format
[libraries]
okhttp = "com.squareup.okhttp3:okhttp:4.11.0"

# Table format with module
okhttp = { module = "com.squareup.okhttp3:okhttp", version = "4.11.0" }

# Table format with group and name
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version = "4.11.0" }

# Version references (automatically resolved)
[versions]
okhttp = "4.11.0"

[libraries]
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }

Smart Repository Filtering

GVC automatically filters repository requests based on dependency group:

  • Google Maven - Only queries for google.*, android.*, androidx.* packages
  • Maven Central - Queries for all other packages
  • Custom Repositories - Respects mavenContent.includeGroupByRegex patterns

This significantly reduces unnecessary HTTP requests and speeds up checks.

Architecture Overview

  • Workflows in src/workflow.rs orchestrate CLI commands, progress output, and Git handoff.
  • Agents encapsulate core responsibilities:
    • ProjectScannerAgent validates Gradle structure and locates libs.versions.toml.
    • DependencyUpdater reads, evaluates, and mutates the catalog with repository-aware version lookups.
    • VersionControlAgent guards Git cleanliness and creates update branches plus commits when enabled.
  • See AGENTS.md for a deeper dive into responsibilities, extension tips, and developer checklists.

Project Requirements

Your Gradle project must have:

  1. Version catalog file: gradle/libs.versions.toml
  2. Gradle wrapper: gradlew or gradlew.bat (for repository detection)

No Gradle plugins required! GVC directly queries Maven repositories and updates your TOML file.

Repository Detection

GVC automatically reads repository configuration from your Gradle build files:

  • settings.gradle.kts / settings.gradle
  • build.gradle.kts / build.gradle

Detected repositories:

  • mavenCentral()
  • google()
  • gradlePluginPortal()
  • Custom maven { url = "..." } declarations
  • Repository content filters (mavenContent.includeGroupByRegex)

Examples

Check for Updates

$ gvc check

Checking for available updates (stable versions)...

1. Validating project structure...
✓ Project structure is valid

2. Reading Gradle repository configuration...
   Found 3 repositories:
   • Maven Central (https://repo1.maven.org/maven2)
   • Google Maven (https://dl.google.com/dl/android/maven2)
   • Gradle Plugin Portal (https://plugins.gradle.org/m2)

3. Checking for available updates...

Checking version variables...
[========================================] 10/10

Checking library updates...
[========================================] 25/25

✓ Check completed

📦 Available Updates:
Found 5 update(s)
   (showing stable versions only)

Version updates:
  • okio-version 3.16.0 → 3.16.2
  • kotlin-version 2.2.20 → 2.2.21
  • ktor-version 3.3.0 → 3.3.1

Library updates:
  • some-direct-lib 0.9.0 → 0.10.0 (stable)

To apply these updates, run:
  gvc update --stable-only

List All Dependencies

$ gvc list

Listing dependencies in version catalog...

1. Validating project structure...
✓ Project structure is valid

2. Reading version catalog...
✓ Catalog loaded

📦 Dependencies:

Libraries:
  androidx.core:core-ktx:1.17.0
  com.squareup.okhttp3:okhttp:4.12.0
  io.ktor:ktor-server-core:3.3.0
  org.jetbrains.compose.runtime:runtime:1.9.0

Plugins:
  org.jetbrains.kotlin.jvm:2.2.20
  com.android.application:8.13.0

Summary:
  4 libraries
  2 plugins

Troubleshooting

"Gradle wrapper not found"

Ensure your project has gradlew (Linux/Mac) or gradlew.bat (Windows) in the root directory.

"gradle/libs.versions.toml not found"

Make sure your project uses Gradle version catalogs and the file exists at gradle/libs.versions.toml.

"Working directory has uncommitted changes"

Commit or stash your changes before running the update command, or use --no-git to skip Git operations.

Development

Project Structure

gvc/
├── src/
│   ├── main.rs              # Entry point
│   ├── cli.rs               # CLI argument parsing
│   ├── workflow.rs          # Command orchestration
│   ├── error.rs             # Error types
│   ├── agents/
│   │   ├── dependency_updater.rs  # Core update logic
│   │   ├── project_scanner.rs     # Project validation
│   │   └── version_control.rs     # Git operations
│   ├── gradle/
│   │   └── config_parser.rs       # Gradle configuration parsing
│   └── maven/
│       ├── repository.rs          # Maven HTTP client
│       ├── version.rs             # Version comparison
│       └── mod.rs                 # Maven coordinate parsing
├── Cargo.toml
└── README.md

Building

# Development
cargo build

# Release (optimized)
cargo build --release

Testing

cargo test

Running in development

# Check updates
cargo run -- check

# List dependencies
cargo run -- list

# Update dependencies
cargo run -- update --no-git

See AGENTS.md for an in-depth guide to the agent modules that power these workflows.

License

Apache-2.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

  1. Clone the repository:

    git clone https://github.com/kingsword09/gvc.git
cd gvc

  2. Build and test:

    cargo build
cargo test
cargo fmt
cargo clippy --all-targets --all-features

  3. Run locally:

    cargo run -- check
cargo run -- update --no-git

See CONTRIBUTING.md for more details.

Changelog

See CHANGELOG.md for release history.

Roadmap

  • Async HTTP requests for concurrent version queries
  • Local caching of Maven metadata
  • Interactive TUI mode for selective updates
  • Support for Gradle plugin updates (Gradle Plugin Portal integration) ✅
  • Configuration file support (.gvcrc)
  • Better error messages with suggestions

About

CLI manager for Gradle version catalogs—check, update, list, and add dependencies with automatic version aliases.

docs.rs/gvc

Topics

rust gradle maven build-automation software-supply-chain cli-tool dev-tools gradle-version-catalog dependencies-management libs-versions-toml

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 4

v0.2.1 Latest
Jun 5, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages