Gradle Usage plugin

The plugin adds a new task that scans a directory tree for Gradle projects and produces a report listing the projects and the version of Gradle used.

Supported Gradle and Java versions

The plugin requires Gradle 7.0 or later and Java 1.8 or later.

Building the plugin

To build the plugin and run the unit tests run

./gradlew -s check

To run the functional tests run

./gradlew -s functionalTest

Using the plugin

The plugin is published on the Gradle Plugin Portal:

• io.github.rodm.gradle-usage - Provides a task to scan a directory for Gradle projects.

Refer to the Gradle Plugin Portal for instructions on how to apply the plugin.

Tasks

• usage : Scans a directory and subdirectories for Gradle projects and outputs a report listing the Gradle projects and the version used by each Gradle project.
  Options

  • --dir : A directory to search for Gradle projects. The option can be specified multiple times.

  • --exclude-dir : A directory to exclude from the search. The option can be specified multiple times.

  • --follow-links : Configure the search to follow symbolic links.

  • --use-gradle-connector : Use the version returned by the Gradle Connector. The default is to use the version returned from the Gradle Wrapper properties file.

Extension Properties

The following properties are defined in the usage configuration block.

• path : A directory to search for Gradle projects.

• exclude : A directory to exclude from the search.

• followLinks : An option flag to follow symbolic links, default is false.

• useGradleConnector : An option flag to use the version returned by the Gradle Connector, default is to use the version from the Gradle Wrapper properties file.

• outputDir : The output directory to write the report, default is 'build/reports/usage'.

Example

build.gradle.kts

    usage {
        path ("/Users/rod/Projects")
        exclude ("/Users/rod/Projects/ExcludedProject")
        followLinks = true
        useGradleConnector = true
        outputDir = "$buildDir/reports/usage"
    }

Report

Run the command providing a directory to search

./gradlew usage --dir ~/Projects

The report output is written to build/reports/usage/usage.txt.

Found 6 Gradle projects
  5.5.1  /Users/rod/Projects/asciidoctor-gradle-plugin
  7.0.2  /Users/rod/Projects/teamcity-jmx-plugin
    6.5  /Users/rod/Projects/jbake-gradle-plugin
  7.0.2  /Users/rod/Projects/gradle-usage-plugin
    6.0  /Users/rod/Projects/gradle-teamcity-plugin
    6.8  /Users/rod/Projects/teamcity-gradle-init-scripts
Summary
  7.0.2 used by 2 projects
    6.8 used by 1 projects
    6.0 used by 1 projects
    6.5 used by 1 projects
  5.5.1 used by 1 projects

Run the command providing a directory to search but excluding a subdirectory.

./gradlew usage --dir ~/Projects --exclude-dir ~/Projects/asciidoctor-gradle-plugin

The report output will be as shown above but without the asciidocker-gradle-plugin project and the version of Gradle it uses.

The report may also return projects with a version of UNKNOWN or FAILED. The value UNKNOWN will be returned when a Gradle project doesn’t contain a gradle-wrapper.properties file. The value FAILED will be returned if the Gradle Connector throws an exception or if the version cannot be parsed from the gradle-wrapper.properties file.

License

This plugin is available under the Apache License, Version 2.0.