Gradle: Directories & Logging

By default the Gradle User Home is ~/.gradle (C:\Users\<USERNAME>\.gradle on Windows). It is changed with the environment variable GRADLE_USER_HOME, the system property gradle.user.home, or the command-line option -g / --gradle-user-home. It must not be confused with GRADLE_HOME, the optional directory where a Gradle distribution was unpacked (see Installation); the user home is the one that grows. The official layout is:

A real one, created by building tidepool once with the wrapper and a fresh GRADLE_USER_HOME, then adding an init.d directory for the cleanup examples below. The ls commands and what they printed:

Three entries are not in the official overview: native (native libraries that Gradle extracts for operating-system integration), notifications (the release features text shown after an upgrade) and .tmp. In the last listing the name of the sub-directory is a hash of the distribution URL, printed here as <hash> because the scratch wrapper points at a local file; with the official URL it is a fixed value for that URL, which is why two projects that use the same URL share one unpacked distribution. The size is worth knowing: the wrapper directory with a single -bin distribution of 9.8.1 took 165 MB, and the caches directory grows with every dependency, plugin and transform.

Three of these directories carry a CACHEDIR.TAG file (caches, wrapper/dists and daemon in the run above; the official page lists jdks too). It is a marker defined by the Cache Directory Tagging Specification: backup and archive tools that honour it skip the directory. Gradle writes the tags since 8.1; markingStrategy in an init script can turn them off (below). This is the reason why a backup of the home directory does not need an exclude rule for .gradle/caches.

Source: Gradle: Understanding the Directory Layout, Gradle User Home directory and Build Environment, environment variables

Gradle keeps three kinds of caches, and the official page separates them by where they live. The listing is from the run above (a Kotlin DSL project and a Groovy DSL project had both been built).

The number at the end of a shared directory is the on-disk format version. When Gradle changes a format, the new version gets a new directory (transforms-3 next to transforms-4) and the old one is left until it is cleaned up, so after an upgrade the home grows before it shrinks. In the example ls caches/modules-2 shows files-2.1, metadata-2.107 and modules-2.lock: the files and the resolution metadata have their own format numbers.

The caches are not an API. You can delete the whole caches directory when no Gradle process is using it, and Gradle will download again what it needs; the reason not to do it routinely is that the dependencies come back from the network (see Repositories & Publishing Across Tools). For a clean rebuild use --refresh-dependencies, --rerun-tasks or clean instead (see Command-Line Interface).

Source: Gradle: Understanding the Directory Layout, Caches, Version-specific caches, Shared caches and Project-local caches

The project root holds the sources and everything Gradle generates for the project. The official overview and what the scratch project (with an added buildSrc directory, and built with the configuration cache) really contained:

A .gitignore that matches this table needs only two lines for Gradle (the build directory of each subproject is matched by the pattern):

The project cache is also cleaned: since Gradle 4.10 the version-specific directories in .gradle/<version> are checked at most every 24 hours after a build, and deleted when they have not been used for seven days.

Source: Gradle: Understanding the Directory Layout, Project Root directory and Project cache cleanup

The caches would grow without limit, so Gradle cleans the Gradle User Home itself. By default the cleanup runs in the background when the daemon is stopped or shuts down, and in the foreground after the build session if the build uses --no-daemon. It runs periodically, at most once every 24 hours, and applies these rules (from the official page):

The retention periods have been configurable since Gradle 8.0 (before that they were fixed: 30 or 7 days depending on the cache). Gradle 9.8.1 has six categories, each with its own default; the first four exist since 8.0, buildCache since 8.8 and daemonLogs since 9.4.0 (the Since entries of the CacheConfigurations Javadoc):

The settings can only be made in an init script in init.d of the Gradle User Home, so they are tied to the home they apply to and a project cannot override a shared home. The script below uses longer retentions for the downloads and the wrapper distributions and a shorter one for the build cache. The Kotlin DSL file and the Groovy DSL file were each placed in init.d of the scratch Gradle User Home with a second file that prints one line, to prove that the directory is applied; the build succeeded with both and printed the line, so the accessors exist and accept the values:

The effect of the periods themselves (an unused distribution disappearing after 45 days) was not observed: it needs time to pass and a cache that is genuinely unused, so it is not run here. Besides the periods, cleanup takes three values: Cleanup.DEFAULT (periodic, in the background), Cleanup.DISABLED (never; for an ephemeral home, or when the cleanup should happen at a point you choose) and Cleanup.ALWAYS (at the end of every build session, in the foreground, which can be expensive). With Cleanup.ALWAYS and --info or --debug no line announcing a cleanup of these caches was found in the output or in the daemon log in this run. The local build cache is different: with --build-cache and --info it logs its own "removing files not accessed" and "cleanup deleted" lines, as shown in Gradle Build Cache.

Two version rules matter on a machine that builds with several Gradle versions. The version-specific caches are cleaned by the version that owns them, but the shared ones are cleaned by everyone, and Gradle before 8.0 has fixed periods: a longer retention configured for 8.x can be undone by an older version in the same home. The DSL elements do not exist before 8.0, so a script in init.d that is shared with older versions must guard them (the official page applies a second script from a sub-directory only when GradleVersion.current() is at least 8.0, because every script directly in init.d is applied):

(Not run here: only 9.8.1 was available.) The gradle8 script must then name only what 8.0 has: releasedWrappers, snapshotWrappers, downloadedResources, createdResources and cleanup. The two scripts above also set buildCache and daemonLogs, so they work only from 9.4.0 on; those two settings go into scripts of their own behind >= 8.8 and >= 9.4 guards. The cache marking is configured the same way: markingStrategy = MarkingStrategy.NONE inside caches { } stops writing CACHEDIR.TAG files, and the default marks caches, wrapper/dists, daemon and jdks. On CI the common choices are to keep the home between jobs and let the default cleanup run, or to throw an ephemeral home away and disable the cleanup.

Source: Gradle: Understanding the Directory Layout, Gradle User Home cleanup, Configuring cleanup of caches and distributions, Multiple versions of Gradle sharing a Gradle User Home, Configuring cache marking, Gradle API: CacheConfigurations, Gradle 8.0 release notes and Gradle 8.1 release notes

Gradle has six log levels. A message is shown when its level is at or above the level you select; the default selection is LIFECYCLE.

To see what each level shows, a task writes one message at every level (and one with println). Both DSLs were run; the Groovy DSL run printed the same messages at the default level.

The task is compatible with the configuration cache (it only calls the task’s own logger), and every run below used --configuration-cache, which is why the output contains the "Reusing configuration cache" lines. The default level:

-q hides everything below QUIET, but not QUIET itself, so the println and the quiet message remain (the help text of the option says "errors only", which is not what it does), and -w adds the warning:

-i adds the INFO message and the information messages of Gradle itself. The full output is long and includes the machine’s paths; the lines from the task onwards, which show the reasons for running the task and the new message (the command and filter used: ./gradlew logDemo -i --configuration-cache piped to sed -n '/^> Task :logDemo/,/^BUILD/p'):

That is the most valuable use of -i: it explains why a task ran or was not cached. The {} placeholder of logger.info("{} items of {}", 3, "tidepool") is the SLF4J form and avoids building the string when the level is off. The -d output has hundreds of lines (379 in this run). To see how Gradle classifies each message, the lines of the demo (command: ./gradlew logDemo -d --configuration-cache, filtered with grep for the logger names org.gradle.api.Task and system.out; the timestamp at the start of each line was removed):

So println is a QUIET message of the logger system.out, and every logger in a task has the name org.gradle.api.Task. The default level can also be set in a property (gradle.properties in the project, or the Gradle User Home) instead of an option; with org.gradle.logging.level=warn in the project, a plain ./gradlew logDemo printed:

The command line wins over the property. The related options --console (plain, rich, verbose, auto), --warning-mode (all, fail, summary, none) and --non-interactive (9.6) control the form of the output rather than the level and are in Command-Line Interface. For the equivalent in the other tools: Maven has -q, the default INFO and -X for debug, and Ant has -q, the default, -v and -d (see Maven: Running Maven from the Command Line and Ant: Running Ant).

Source: Gradle: Logging, Gradle Log levels, Choosing and setting a log level and Command-Line Interface, logging options

When a build fails Gradle prints the problem, the location and the tips, and no stack trace. A task that fails on purpose shows it:

The Groovy DSL project reported the same failure, with a "* Where:" block that names build.gradle and line 16, because Groovy scripts are located by line. The stack trace options:

With -s the failure above grows by an * Exception is: section: 151 lines for this build (the build run is a plain ./gradlew fail -s --configuration-cache). The beginning, the part that points to your code, and the end:

Read it from the Caused by: line: the first line of your own code (build.gradle.kts:16) is the line of the throw. -S printed 156 lines for the same failure (... 28 more instead of ... 25 more), and org.gradle.logging.stacktrace=full in gradle.properties produced the same 156 lines without the option. In a build with a deeper failure (a compile error, a plugin bug) the difference is larger, because the truncated form drops internal frames. The usual sequence when something fails is the one the message itself suggests: --stacktrace, then --info or --debug, then --scan (see Performance Profiling & Build Scans).

Source: Gradle: Logging, Stacktrace options

The DEBUG level can write sensitive data into the build log, and the official page lists what to expect: environment variables, credentials of private repositories, build cache and Develocity credentials, and Plugin Portal publishing credentials. Do not use --debug on public CI services, whose logs anybody can read, and be careful on private ones; masking by the CI provider only covers exact matches of pre-configured secrets. In the scratch run, DEMO_TOKEN=not-a-real-secret ./gradlew logDemo -d listed the names of 62 environment variables of the shell in one line ("Configuring env variables: [PATH, …​") and the value of the placeholder did not appear in the output; the log still showed that the variable existed. The conclusion is the official one: treat a DEBUG log as sensitive, and read credentials with providers.environmentVariable / providers.gradleProperty instead of putting them where they are printed (see Build Environment & Properties).

Source: Gradle: Logging, Logging Sensitive Information

Gradle redirects the standard output of a build to the QUIET level and standard error to ERROR, so a println works but is shown even with -q. The logger property of a script or task is a Logger, which extends the SLF4J logger and adds quiet and lifecycle. The levels and the placeholder form were in the logDemo task above; logger.trace is accepted and never logged. Choose the level by who should see the message: LIFECYCLE for progress the user should see, INFO for information needed to diagnose why a task ran, DEBUG for noise.

Classes of build logic outside the scripts need a logger of their own. Since Gradle 9.8 the best practices catalogue says to obtain it with Logging.getLogger(MyClass.class) in every non-task class (plugins, build services, extensions), rather than going through project.logger, which is not compatible with the configuration cache when read at execution time and is not reachable from a build service at all; inside a task, the inherited getLogger() is right. The example is a class in buildSrc, with a script that calls it:

(The buildSrc tasks that compile the class were left out of the listing; buildSrc is built first.) With --info the first message, "Resolving station 8443970", appears too. Both DSLs behaved the same. The class is a plain SLF4J user as well: the first version of this example used LoggerFactory.getLogger("tidepool-build") from org.slf4j and printed the same messages, since the API of Gradle exposes SLF4J.

Gradle in Action (Muschko, Manning 2014, Gradle 1.7) shows the ~/.gradle directory and the .gradle and build directories of a project, and the logging chapter’s levels and -q, -i, -d options still apply unchanged. What changed: the cache layout (modules-2, the build output cleanup, the configuration cache and, since 8.0, configurable retentions and cleanup by Gradle itself), the way to set the JVM options (org.gradle.jvmargs, see The Gradle Daemon), the stack-trace options (-s for the truncated one is the recommended form), and the preference for Logging.getLogger in build logic over the script’s logger. The buildSrc directory is still supported, but the book predates the guidance towards included builds for build logic.