<commit_before>[[sec:declaring-repositories]]
= Declaring repositories

Gradle can resolve dependencies from one or many repositories based on Maven, Ivy or flat directory formats. Check out the <<repository_types.adoc#repository_types,full reference on all types of repositories>> for more information.

[[sec:declaring_public_repository]]
== Declaring a publicly-available repository

Organizations building software may want to leverage public binary repositories to download and consume open source dependencies. Popular public repositories include Maven Central, Bintray JCenter and the Google Android repository. Gradle provides built-in shortcut methods for the most widely-used repositories.

.Declaring a repository with the help of shortcut methods
image::dependency-management-shortcut-repositories.png[]

To declare JCenter as repository, add this code to your build script:

.Declaring JCenter repository as source for resolving dependencies
====
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/publicRepository/groovy",files="build.gradle[tags=public-repository]"]
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/publicRepository/kotlin",files="build.gradle.kts[tags=public-repository]"]
====

Under the covers Gradle resolves dependencies from the respective URL of the public repository defined by the shortcut method. All shortcut methods are available via the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.RepositoryHandler.html[RepositoryHandler] API. Alternatively, you can <<#sec:declaring_custom_repository,spell out the URL of the repository>> for more fine-grained control.

[[sec:declaring_custom_repository]]
== Declaring a custom repository by URL

Most enterprise projects set up a binary repository available only within an intranet. In-house repositories enable teams to publish internal binaries, setup user management and security measure and ensure uptime and availability. Specifying a custom URL is also helpful if you want to declare a less popular, but publicly-available repository.

Add the following code to declare an in-house repository for your build reachable through a custom URL.

.Declaring a custom repository by URL
====
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/customRepository/groovy",files="build.gradle[tags=custom-repository]"]
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/customRepository/kotlin",files="build.gradle.kts[tags=custom-repository]"]
====

Repositories with custom URLs can be specified as Maven or Ivy repositories by calling the corresponding methods available on the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.RepositoryHandler.html[RepositoryHandler] API. Gradle supports other protocols than `http` or `https` as part of the custom URL e.g. `file`, `sftp` or `s3`. For a full coverage see the <<repository_types.adoc#sub:supported_transport_protocols,reference manual on supported transport protocols>>.

You can also <<repository_types.adoc#sec:defining_custom_pattern_layout_for_an_ivy_repository,define your own repository layout>> by using `ivy { }` repositories as they are very flexible in terms of how modules are organised in a repository.

[[sec:declaring_multiple_repositories]]
== Declaring multiple repositories

You can define more than one repository for resolving dependencies. Declaring multiple repositories is helpful if some dependencies are only available in one repository but not the other. You can mix any type of repository described in the <<repository_types.adoc#repository_types,reference section>>.

This example demonstrates how to declare various shortcut and custom URL repositories for a project:

.Declaring multiple repositories
====
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/multipleRepositories/groovy",files="build.gradle[tags=multiple-repositories]"]
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/multipleRepositories/kotlin",files="build.gradle.kts[tags=multiple-repositories]"]
====

[NOTE]
====
The order of declaration determines how Gradle will check for dependencies at runtime. If Gradle finds a module descriptor in a particular repository, it will attempt to download all of the artifacts for that module from _the same repository_. You can learn more about the inner workings of <<introduction_dependency_management.adoc#sec:dependency_resolution,Gradle's resolution mechanism>>.
====

[[supported-repo-types]]
== Supported repository types

TODO

[[how-gradle-downloads-deps]]
== How Gradle downloads dependencies

Gradle takes your dependency declarations and repository definitions and attempts to download all of your dependencies by a process called _dependency resolution_. Below is a brief outline of how this process works.

* Given a required dependency, Gradle attempts to resolve the dependency by searching for the module the dependency points at. Each repository is inspected in order. Depending on the type of repository, Gradle looks for metadata files describing the module (`.module`, `.pom` or `ivy.xml` file) or directly for artifact files.

** If the dependency is declared as a dynamic version (like `1.+`, `[1.0,)`, `[1.0, 2.0)`), Gradle will resolve this to the highest available concrete version (like `1.2`) in the repository. For Maven repositories, this is done using the `maven-metadata.xml` file, while for Ivy repositories this is done by directory listing.

** If the module metadata is a POM file that has a parent POM declared, Gradle will recursively attempt to resolve each of the parent modules for the POM.

* Once each repository has been inspected for the module, Gradle will choose the 'best' one to use. This is done using the following criteria:

** For a dynamic version, a 'higher' concrete version is preferred over a 'lower' version.

** Modules declared by a module metadata file (`.module`, `.pom` or `ivy.xml` file) are preferred over modules that have an artifact file only.

** Modules from earlier repositories are preferred over modules in later repositories.

** When the dependency is declared by a concrete version and a module metadata file is found in a repository, there is no need to continue searching later repositories and the remainder of the process is short-circuited.

* All of the artifacts for the module are then requested from the _same repository_ that was chosen in the process above.

The dependency resolution process is highly customizable to meet enterprise requirements. For more information, see the chapter on <<customizing_dependency_resolution_behavior.adoc#customizing_dependency_resolution_behavior,customizing dependency resolution>>.

[[sub:http-retries]]
=== HTTP Retries

Gradle will make several attempts to connect to a given repository. If it fails, Gradle will retry, increasing the amount of time waiting between each retry. After a max number of failed attempts, the repository will be blacklisted for the whole build.


[[case-for-maven-local]]
== The case for mavenLocal()

TODO

[[plugin-vs-build-repos]]
== Plugin repositories vs. build repositories

TODO

[[dependency_cache]]
== The Dependency Cache

Gradle contains a highly sophisticated dependency caching mechanism, which seeks to minimise the number of remote requests made in dependency resolution, while striving to guarantee that the results of dependency resolution are correct and reproducible.

The Gradle dependency cache consists of two storage types located under `GRADLE_USER_HOME/caches`:

* A file-based store of downloaded artifacts, including binaries like jars as well as raw downloaded meta-data like POM files and Ivy files. The storage path for a downloaded artifact includes the SHA1 checksum, meaning that 2 artifacts with the same name but different content can easily be cached.
* A binary store of resolved module meta-data, including the results of resolving dynamic versions, module descriptors, and artifacts.

The Gradle cache does not allow the local cache to hide problems and create other mysterious and difficult to debug behavior.
Gradle enables reliable and reproducible enterprise builds with a focus on bandwidth and storage efficiency.

[[sub:cache_metadata]]
=== Separate metadata cache

Gradle keeps a record of various aspects of dependency resolution in binary format in the metadata cache.<commit_msg>Add section about correct use of `mavenLocal()`<commit_after>[[sec:declaring-repositories]]
= Declaring repositories

Gradle can resolve dependencies from one or many repositories based on Maven, Ivy or flat directory formats. Check out the <<repository_types.adoc#repository_types,full reference on all types of repositories>> for more information.

[[sec:declaring_public_repository]]
== Declaring a publicly-available repository

Organizations building software may want to leverage public binary repositories to download and consume open source dependencies. Popular public repositories include Maven Central, Bintray JCenter and the Google Android repository. Gradle provides built-in shortcut methods for the most widely-used repositories.

.Declaring a repository with the help of shortcut methods
image::dependency-management-shortcut-repositories.png[]

To declare JCenter as repository, add this code to your build script:

.Declaring JCenter repository as source for resolving dependencies
====
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/publicRepository/groovy",files="build.gradle[tags=public-repository]"]
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/publicRepository/kotlin",files="build.gradle.kts[tags=public-repository]"]
====

Under the covers Gradle resolves dependencies from the respective URL of the public repository defined by the shortcut method. All shortcut methods are available via the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.RepositoryHandler.html[RepositoryHandler] API. Alternatively, you can <<#sec:declaring_custom_repository,spell out the URL of the repository>> for more fine-grained control.

[[sec:declaring_custom_repository]]
== Declaring a custom repository by URL

Most enterprise projects set up a binary repository available only within an intranet. In-house repositories enable teams to publish internal binaries, setup user management and security measure and ensure uptime and availability. Specifying a custom URL is also helpful if you want to declare a less popular, but publicly-available repository.

Add the following code to declare an in-house repository for your build reachable through a custom URL.

.Declaring a custom repository by URL
====
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/customRepository/groovy",files="build.gradle[tags=custom-repository]"]
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/customRepository/kotlin",files="build.gradle.kts[tags=custom-repository]"]
====

Repositories with custom URLs can be specified as Maven or Ivy repositories by calling the corresponding methods available on the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.RepositoryHandler.html[RepositoryHandler] API. Gradle supports other protocols than `http` or `https` as part of the custom URL e.g. `file`, `sftp` or `s3`. For a full coverage see the <<repository_types.adoc#sub:supported_transport_protocols,reference manual on supported transport protocols>>.

You can also <<repository_types.adoc#sec:defining_custom_pattern_layout_for_an_ivy_repository,define your own repository layout>> by using `ivy { }` repositories as they are very flexible in terms of how modules are organised in a repository.

[[sec:declaring_multiple_repositories]]
== Declaring multiple repositories

You can define more than one repository for resolving dependencies. Declaring multiple repositories is helpful if some dependencies are only available in one repository but not the other. You can mix any type of repository described in the <<repository_types.adoc#repository_types,reference section>>.

This example demonstrates how to declare various shortcut and custom URL repositories for a project:

.Declaring multiple repositories
====
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/multipleRepositories/groovy",files="build.gradle[tags=multiple-repositories]"]
include::sample[dir="/userguide/dependencyManagement/declaringRepositories/multipleRepositories/kotlin",files="build.gradle.kts[tags=multiple-repositories]"]
====

[NOTE]
====
The order of declaration determines how Gradle will check for dependencies at runtime. If Gradle finds a module descriptor in a particular repository, it will attempt to download all of the artifacts for that module from _the same repository_. You can learn more about the inner workings of <<introduction_dependency_management.adoc#sec:dependency_resolution,Gradle's resolution mechanism>>.
====

[[supported-repo-types]]
== Supported repository types

TODO

[[how-gradle-downloads-deps]]
== How Gradle downloads dependencies

Gradle takes your dependency declarations and repository definitions and attempts to download all of your dependencies by a process called _dependency resolution_. Below is a brief outline of how this process works.

* Given a required dependency, Gradle attempts to resolve the dependency by searching for the module the dependency points at. Each repository is inspected in order. Depending on the type of repository, Gradle looks for metadata files describing the module (`.module`, `.pom` or `ivy.xml` file) or directly for artifact files.

** If the dependency is declared as a dynamic version (like `1.+`, `[1.0,)`, `[1.0, 2.0)`), Gradle will resolve this to the highest available concrete version (like `1.2`) in the repository. For Maven repositories, this is done using the `maven-metadata.xml` file, while for Ivy repositories this is done by directory listing.

** If the module metadata is a POM file that has a parent POM declared, Gradle will recursively attempt to resolve each of the parent modules for the POM.

* Once each repository has been inspected for the module, Gradle will choose the 'best' one to use. This is done using the following criteria:

** For a dynamic version, a 'higher' concrete version is preferred over a 'lower' version.

** Modules declared by a module metadata file (`.module`, `.pom` or `ivy.xml` file) are preferred over modules that have an artifact file only.

** Modules from earlier repositories are preferred over modules in later repositories.

** When the dependency is declared by a concrete version and a module metadata file is found in a repository, there is no need to continue searching later repositories and the remainder of the process is short-circuited.

* All of the artifacts for the module are then requested from the _same repository_ that was chosen in the process above.

The dependency resolution process is highly customizable to meet enterprise requirements. For more information, see the chapter on <<customizing_dependency_resolution_behavior.adoc#customizing_dependency_resolution_behavior,customizing dependency resolution>>.

[[sub:http-retries]]
=== HTTP Retries

Gradle will make several attempts to connect to a given repository. If it fails, Gradle will retry, increasing the amount of time waiting between each retry. After a max number of failed attempts, the repository will be blacklisted for the whole build.


[[case-for-maven-local]]
== The case for mavenLocal()

As a general advice, you should avoid adding `mavenLocal()` as a repository.
There are different issues with using `mavenLocal()` that you should be aware of:

* as it is a local repository, it can't be trusted, which means that
 ** origin of artifacts cannot be tracked, which is a security problem
 ** artifacts can be easily overwritten, which is a both a security and a reproducibility problem
* to mitigate the fact metadata artifacts can be changed, Gradle currently does not cache any metadata from local repositories
** as a consequence, your builds are slower
** given that order of repositories is important, adding `mavenLocal()` _first_ means that all your builds are going to be slower

There are a few cases where you might, legitimately, want to use `mavenLocal()`:

* for interoperability with Maven
** for example, project A is built with Maven, project B is built with Gradle, and you need to share the artifacts during development
** it is _always_ preferable to use a local repository server instead
** in case this is not possible, you should limit this to _local builds only_
* for interoperability with Gradle itself
** in a multi-repository world, you want to check that changes to project A work with project B
** it is preferable to use <<composite-builds#composite-builds.adoc, composite builds>> for this use case
** if for some reason composite builds are not applicable, you can add `mavenLocal()`

[[plugin-vs-build-repos]]
== Plugin repositories vs. build repositories

TODO

[[dependency_cache]]
== The Dependency Cache

Gradle contains a highly sophisticated dependency caching mechanism, which seeks to minimise the number of remote requests made in dependency resolution, while striving to guarantee that the results of dependency resolution are correct and reproducible.

The Gradle dependency cache consists of two storage types located under `GRADLE_USER_HOME/caches`:

* A file-based store of downloaded artifacts, including binaries like jars as well as raw downloaded meta-data like POM files and Ivy files. The storage path for a downloaded artifact includes the SHA1 checksum, meaning that 2 artifacts with the same name but different content can easily be cached.
* A binary store of resolved module meta-data, including the results of resolving dynamic versions, module descriptors, and artifacts.

The Gradle cache does not allow the local cache to hide problems and create other mysterious and difficult to debug behavior.
Gradle enables reliable and reproducible enterprise builds with a focus on bandwidth and storage efficiency.

[[sub:cache_metadata]]
=== Separate metadata cache

Gradle keeps a record of various aspects of dependency resolution in binary format in the metadata cache.
{'fraction_non_alphanumeric': 0.06238030095759234, 'fraction_numerical': 0.0013132694938440491, 'mean_word_length': 5.799107142857143, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3756702', 'n_tokens_mistral': 4510, 'n_tokens_neox': 4190, 'n_words': 2185}