// Copyright 2018 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[directory_layout]]
= The Directories and Files Gradle Uses

Gradle uses two main directories to perform and manage its work: the <<#dir:gradle_user_home>> and the <<#dir:project_root>>. The following two sections describe what is stored in each of them and how transient files and directories are cleaned up.


[[dir:gradle_user_home]]
== Gradle user home directory

The Gradle user home directory (`$USER_HOME/.gradle` by default) is used to store global configuration properties and initialization scripts as well as caches and log files. It is roughly structured as follows:

[listing]
----
├── caches // <1>
│   ├── 4.8 // <2>
│   ├── 4.9 // <2>
│   ├── ⋮
│   ├── jars-3 // <3>
│   └── modules-2 // <3>
├── daemon // <4>
│   ├── ⋮
│   ├── 4.8
│   └── 4.9
├── init.d // <5>
│   └── my-setup.gradle
├── wrapper
│   └── dists // <6>
│       ├── ⋮
│       ├── gradle-4.8-bin
│       ├── gradle-4.9-all
│       └── gradle-4.9-bin
└── gradle.properties // <7>
----
<1> Global cache directory (for everything that's not project-specific)
<2> Version-specific caches (e.g. to support incremental builds)
<3> Shared caches (e.g. for artifacts of dependencies)
<4> Registry and logs of the <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>>
<5> Global <<init_scripts.adoc#init_scripts, initialization scripts>>
<6> Distributions downloaded by the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>
<7> Global <<build_environment.adoc#sec:gradle_configuration_properties,Gradle configuration properties>>

[[dir:gradle_user_home:cache_cleanup]]
=== Cleanup of caches and distributions

From version 4.10 onwards, Gradle automatically cleans its user home directory. The cleanup runs in the background when the Gradle daemon is stopped or shuts down. If using `--no-daemon`, it runs in the foreground after the build session with a visual progress indicator.

The following cleanup strategies are applied periodically (at most every 24 hours):

- Version-specific caches in `caches/<gradle-version>/` are checked for whether they are still in use. If not, directories for release versions are deleted after 30 days of inactivity, snapshot versions after 7 days of inactivity.
- Shared caches in `caches/` (e.g. `jars-*`) are checked for whether they are still in use. If there's no Gradle version that still uses them, they are deleted.
- Files in shared caches used by the current Gradle version in `caches/` (e.g. `jars-3` or `modules-2`) are checked for when they were last accessed. Depending on whether the file can be recreated locally or would have to be downloaded from a remote repository again, it will be deleted after 7 or 30 days of not being accessed, respectively.
- Gradle distributions in `wrapper/dists/` are checked for whether they are still in use, i.e. whether there's a corresponding version-specific cache directory. Unused distributions are deleted.


[[dir:project_root]]
== Project root directory

The project root directory contains all source files that are part of your project. In addition, it contains files and directories that are generated by Gradle such as `.gradle` and `build`. While the former are usually checked in to source control, the latter are transient files used by Gradle to support features like incremental builds. Overall, the anatomy of a typical project root directory looks roughly as follows:

[listing,subs=+macros]
----
├── .gradle // <1>
│   ├── 4.8 // <2>
│   ├── 4.9 // <2>
│   └── ⋮
├── build // <3>
├── gradle
│   └── wrapper  // <4>
├── build.gradle pass:quotes[_or_] build.gradle.kts // <5>
├── gradle.properties // <6>
├── gradlew // <7>
├── gradlew.bat // <7>
└── settings.gradle pass:quotes[_or_] settings.gradle.kts // <8>
----
<1> Project-specific cache directory generated by Gradle
<2> Version-specific caches (e.g. to support incremental builds)
<3> The build directory of this project into which Gradle generates all build artifacts.
<4> Contains the JAR file and configuration of the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>
<5> The project's Gradle build script
<6> Project-specific <<build_environment.adoc#sec:gradle_configuration_properties,Gradle configuration properties>>
<7> Scripts for executing builds using the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>
<8> The project's <<build_lifecycle.adoc#sec:settings_file, settings file>>

[[dir:project_root:cache_cleanup]]
=== Project cache cleanup

From version 4.10 onwards, Gradle automatically cleans the project-specific cache directory. After building the project, version-specific cache directories in `.gradle/<gradle-version>/` are checked periodically (at most every 24 hours) for whether they are still in use. They are deleted if they haven't been used for 7 days.
