[ About | Licence | Contacts ]
Written by Oleksandr Gavenko (AKA gavenkoa), compiled on 2024-04-01 from rev 052223c22317.


Getting help

$ gradle --help

Stopping server

$ gradle --stop

Altering user home

GRADLE_USER_HOME controls user home.

Build Environment. Gradle properties. GRADLE_USER_HOME directory.


Gradle uses modified Slf4j: org.gradle.api.logging.Logger.

Logging level can be set with org.gradle.api.logging.LogLevel:

logger.log(LogLevel.LIFECYCLE, "Unzipping {}...", zipFile);

Project and Task has logger object with levels:

logger.error "..."
logger.quiet "..."
logger.warning "..."
logger.lifecycle "..."
logger.info "..."
logger.debug "..."

println is printed on quiet level.

Make Gradle quiet:

$ gradle -q ...
$ gradle --quiet ...

Show only errors/warnings:

$ gradle -w ...
$ gradle --warn ...

Make Gradle verbose:

$ gradle -i ...
$ gradle --info ...

Make Gradle to print debug output:

$ gradle -d ...
$ gradle --debug ...

Debugging Gradle

Enable debugging and disable server mode:

gradle -Dorg.gradle.debug=true --no-daemon ...

Then attach by Java debugger to port 5005.


GRADLE_OPTS='-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' gradle  --no-daemon ...

To investigate interface & values of object:

println it.metaClass.metaMethods*.name.sort().unique()
println it.metaClass.methods*.name.sort().unique()
println it.properties.entrySet()*.toString().sort().toString().replaceAll(", ","\n")
println it.properties.toString()
println it.dump()
Attaching a debugger to your build.
How to dump all gradle values used for build.

Managing tasks

List tasks:

$ gradle tasks

Getting list of supported tasks in each subproject:

$ gradle tasks --all

Check execution path or debug task dependencies:

$ gradle -m compile
$ gradle --dry-run compile

Getting help on task:

$ gradle help --task build
$ gradle -q help --task build

Similar but to each task:

$ gradle model

Skip task during build with -x option:

$ gradle -x test build
$ gradle -x :core:build :client:build

Skipt task programmatically:

gradle.startParameter.excludedTaskNames.add "jar"

Working with subprojects

Getting list of subprojects:

$ gradle projects

Running build on specific subproject:

$ gradle :$SUB:clean
$ gradle -p $SUB clean

If subproject lies in hierarchy:

$ gradle :$SUB/$SUBSUB:clean
$ gradle -p $SUB/$SUBSUB clean

Skip building dependent modules, build just current module:

$ gradle -a build
$ gradle --no-rebuild build
$ gradle -a :client:build

Creating multilevel project:

$ mkdir $PRJROOT
$ mkdir lvl1 lvl1/lvl2
$ touch build.gradle lvl1/build.gradle lvl1/lvl2/build.gradle
$ { echo include "'lvl1'"; echo include "'lvl1/lvl2'"; } >settings.gradle
$ gradle projects

settings.gradle can include per line or a list of subprojects:

include 'sub1', 'sub2', 'sub2'
include 'lvl1'
include 'lvl1/lvl2'

https://docs.gradle.org/current/userguide/intro_multi_project_builds.html http://stackoverflow.com/questions/16976214/gradle-build-only-one-module

Debugging build

Enable better logging:

$ gradle -i ...
$ gradle --info ...
$ gradle -d ...
$ gradle --debug ...

Enable stacktraces:

$ gradle --stacktrace

Review deprecation:

$ gradle --warning-mode=all --stacktrace

Profiling build

$ gradle --profile

To use build scans accept EULA:

buildScan {
  termsOfServiceUrl = 'https://gradle.com/terms-of-service'
  termsOfServiceAgree = 'yes'

then run:

$ gradle --scan

Listing available toolchains

Toolchains are introduced in Gradle 6.7.

Requiring a toolchain for the build:

java {
    toolchain {

Altering toolchain for a specific task (derived from java plugin):

tasks.register<Test>("compatibilityTest") {
    javaLauncher.set(javaToolchains.launcherFor {

List of available toolchains:

gradle -q javaToolchains
Guide to Using Toolchains.
Introducing Java toolchains.

Running completely isolated build

To avoid using global cache and for really clean build use:

$ gradle --no-daemon -g _tmp
$ gradle --no-daemon --gradle-user-home ./.gradle.local

Build sources

$ gradle compileJava
$ gradle compileTestJava

Build with additional options and checks:

compileJava {
  options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"
compileTestJava {
  options.encoding = 'UTF-8'
  options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

To apply change recursively to subprojects:

subprojects {
    tasks.withType(JavaCompile) {
        options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

Run main class

$ gradle run

Run tests

To run test:

$ gradle test

To select specific test or pattern use --tests option, like:

$ gradle test --tests com.evil.UtitTest
$ gradle test --tests com.evil.UtitTest.login
$ gradle test --tests '*'BasicTest.login
$ gradle test --tests '*BasicTest.calc*'

To skip tests in build:

$ gradle -x test build

To continue testing after fixing test:

$ gradle test --continue

Alternative solution involves passing system property with build.gradle:

test.onlyIf { ! Boolean.getBoolean('skip.tests') }

To run tests with additional registered checks:

$ gradle check


--rerun-tasks option specifies that any task optimization is ignored. If you are not using build cache it reruns tests and all dependent tasks:

$ gradle test --rerun-tasks

See https://stackoverflow.com/questions/29427020/how-to-run-gradle-test-when-all-tests-are-up-to-date

By default System.out and Sysyem.err redirected so you wouldn't see anything about test on console.

Quick way to see test output is:

$ gradle test -i

Alternatively configure test task:

test {
  testLogging {
    events "passed", "skipped", "failed" //, "standardOut", "standardError"

    showExceptions true
    exceptionFormat "full"
    showCauses true
    showStackTraces true

    showStandardStreams = false

List project dependencies

List of project dependencies (it also downloads dependencies) for all configurations:

$ gradle dependencies
$ gradle dependencies -p $SUBPROJ
$ gradle :$SUBPROJ:dependencies

Limiting configuration:

gradle dependencies --configuration compileClasspath
gradle :$SUBPROJ:dependencies --configuration testCompileClasspath

Finding the reason for dependency inclusion into a configuration:

mygradle dependencyInsight --dependency com.netflix.ribbon --configuration runtimeClasspath
Viewing and debugging dependencies.

List of project plugin dependencies:

$ gradle buildEnvironment
$ gradle buildEnvironment -p $SUBPROJ
$ gradle :$SUBPROJ:buildEnvironment

Paths to dependencies can be printed via task:

task printDepPaths {
  doLast { configurations.runtime.each { println it } }

All dependencies can be copied to single directory via task:

task copyRuntimeLibs(type: Copy) {
  into "lib"
  from configurations.runtime
  // from configurations.testRuntime - configurations.runtime

List of configurations:

configurations.each { println it.name }

There is a hierarchy of configurations, not all are resolvable or consumable:

configurations.each {
  logger.lifecycle(String.format("%s, resolvable: %s, consumable: %s", it, it.canBeResolved, it.canBeConsumed))

For each configuration build<ConfigurationName> and upload<ConfigurationName> are defined.

Configuring external dependencies

Adding large well known artifact repositories:

repositories {

mavelLocal() for local ~/.m2 or whenever Maven settings.xml is pointing.

Adding custom repositories:

repositories {
  maven { url "http://repo.example.com/maven2" }
  ivy { url "http://repo.example.com/ivy" }
  maven {
    url "http://repo.example.com/maven2"
    username "ro-user"
    password "pas$$word"

Excluding transitive dependencies:

compile 'org.springframework:spring-web:4.3.10.RELEASE' {
    exclude group: 'com.google.code.gson', module: 'gson'

implementation project(':core'), {
    exclude group: 'org.quartz-scheduler'

configurations.all {
    exclude group: 'com.google.code.gson', module: 'gson'

configurations.runtime {
    exclude group: 'com.google.code.gson', module: 'gson'

configurations {
    implementation {
        exclude group: 'javax.jms', module: 'jms'

Forcing a specific version of a transitive dependency:

configurations.all {
    resolutionStrategy.force 'com.google.code.gson:gson:2.8.1'

Declaring dependency on module in multi-module build:

compile project(':core')

List project properties

$ gradle properties
$ gradle :$SUBPROJ:properties
$ gradle properties -p $SUBPROJ

Well known properties

rootDir, projectDir, buildDir are of java.io.File type.

tasks refers to task set.

project, subprojects, rootProject refer to various Project instances.

Bootstrap project structure

This creates simple project with Gradle boilerplate files:

$ gradle init --type java-library

To convert Maven project (with pom.xml file) to Gradle project use:

$ gradle init --type pom
Official docs on init plugin.

Gradle wrapper

With Gradle v2.4 and above:

$ cd $PROJ
$ gradle wrapper --gradle-version 3.5

It will add gradle/wrapper/gradle-wrapper.jar to project root and next call to ./gradlew download Gradle distribution from distributionUrl parameter from gradle/wrapper/gradle-wrapper.properties file. Dictribution will be cached in ~/.gradle/wrapper/dists.gradle/wrapper/dists directory so next calls won't require download.

Alternatively define task:

task wrapper(type: Wrapper) {
    gradleVersion = '2.0'

Update Gradle wrapper version with:

$ gradle --version
Gradle 4.0.1
$ gradle wrapper --gradle-version 4.9

To increase security add distributionSha256Sum parameter to gradle-wrapper.properties file. Distribution SHA-256 sum can be obtained via shasum utility.

To depend on a distribution with bundled docs & sources use --distribution-type all (bin is by default):

./gradlew wrapper --gradle-version 7.6 --distribution-type all
Official docs.

Migrating to newer Gradle

Try to eliminate all deprecation warnings:

./gradlew testClasses --warning-mode all

Update Gradle distro to newer version:

./gradlew wrapper --gradle-version 6.7

Try to eliminate another portion of deprecation warnings and run build/tests:

./gradlew test --warning-mode all

Managing Gradle cache

Work in offline mode with --offline option.

Invalidate cache (force re-downloading dependencies) with --refresh-dependencies option.

Alternatively remove ~/.m2/repository/ and ~/.gradle/caches directories.

Gradle cached modules declared as changing:

dependencies {
  compile("com.evil:evil-api:1.0.1-SNAPSHOT") { changing=true }

Default timeout is 24 hours and can be reset/changed via:

configurations.all {
    resolutionStrategy.cacheChangingModulesFor 0, 'seconds'

Download sources and javadoc of dependencies

To download sources and javadoc of dependencies to local ~/.gradle cache add idea plugin to your build.gradle:

apply plugin: 'idea'
idea.module.downloadJavadoc = true
idea.module.downloadSources = true

and invoke plugin:

$ gradle idea

To wipe out Idea projects file after plug-in run:

$ gradle cleanIdea

Dependencies between tasks

Direct dependency:

task A {
  dependsOn B, C
A.dependsOn D, E

Cleanup actions:

task A {
  dependsOn startServer
  finalizedBy stopServer

To enforce order without enforcing dependency:

task A {
  mustRunAfter B

Declare dependencies programmatically:

dependsOn project.tasks.matching { it.name.endsWith "Test" }

Apply task on condition:

task upload {
    onlyIf { System.getProperty("debug") != null }
    doLast { println "In debug mode." }

Accessing task graph

Process task graph when it is already populated:

gradle.taskGraph.whenReady { graph ->
  if (graph.hasTask(":release")) { ... }

gradle.taskGraph is safe to access inside doFirst / doLast:

task someTask {
  doLast {
    if (gradle.taskGraph.hasTask(":someTask")) {  }

List all tasks that will be executed in current build:

println gradle.taskGraph.allTasks

Applying pluings

apply from: "plugins/my.gradle"

Publishing artifacts

Publishing a project as module.
Customizing publishing.
Gradle Artifactory Plugin.
Project that holds Artifactory integration for Gradle (build-info-extractor-gradle).