[[dependency-locking]]
= Locking dependency versions

Use of dynamic dependency versions (e.g. `1.+` or `[1.0,2.0)`) makes builds non-deterministic.
This causes builds to break without any obvious change, and worse, can be caused by a transitive dependency that the build author has no control over.

To achieve https://reproducible-builds.org/[reproducible builds], it is necessary to _lock_ versions of dependencies and transitive dependencies such that a build with the same inputs will always resolve the same module versions.
This is called _dependency locking_.

It enables, amongst others, the following scenarios:

* Companies dealing with multi repositories no longer need to rely on `-SNAPSHOT` or changing dependencies,
which sometimes result in cascading failures when a dependency introduces a bug or incompatibility.
Now dependencies can be declared against major or minor version range, enabling to test with the latest versions on CI while leveraging locking for stable developer builds.
* Teams that want to always use the latest of their dependencies can use dynamic versions, locking their dependencies only for releases.
The release tag will contain the lock states, allowing that build to be fully reproducible when bug fixes need to be developed.

Combined with <<publishing_maven.adoc#publishing_maven:resolved_dependencies,publishing resolved versions>>, you can also replace the declared dynamic version part at publication time.
Consumers will instead see the versions that your release resolved.

Locking is enabled per <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,dependency configuration>>.
Once enabled, you must create an initial lock state.
It will cause Gradle to verify that resolution results do not change, resulting in the same selected dependencies even if newer versions are produced.
Modifications to your build that would impact the resolved set of dependencies will cause it to fail.
This makes sure that changes, either in published dependencies or build definitions, do not alter resolution without adapting the lock state.

[NOTE]
====
Dependency locking makes sense only with <<dynamic_versions.adoc#sub:declaring_dependency_with_dynamic_version,dynamic versions>>.
It will have no impact on <<dynamic_versions.adoc#sub:declaring_dependency_with_changing_version,changing versions>> (like `-SNAPSHOT`) whose coordinates remain the same, though the content may change.
Gradle will even emit a warning when persisting lock state and changing dependencies are present in the resolution result.
====

== Enabling locking on configurations

Locking of a configuration happens through the link:{groovyDslPath}/org.gradle.api.artifacts.ResolutionStrategy.html[ResolutionStrategy]:

.Locking a specific configuration
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleConfiguration/groovy",files="build.gradle[tags=locking-one]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-one]"]
====

Or the following, as a way to lock all configurations:

.Locking all configurations
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingAllConfigurations/groovy",files="build.gradle[tags=locking-all]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingAllConfigurations/kotlin",files="build.gradle.kts[tags=locking-all]"]
====

[NOTE]
====
Only configurations that can be resolved will have lock state attached to them.
Applying locking on non resolvable-configurations is simply a no-op.
====

[NOTE]
====
The above will lock all _project_ configurations, but not the _buildscript_ ones.
====

You can also disable locking on a specific configuration.
This can be useful if a plugin configured locking on all configurations but you happen to add one that should not be locked.

.Unlocking a specific configuration
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-unlockingSingleConfiguration/groovy",files="build.gradle[tags=locking-one]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-unlockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-one]"]
====

=== Locking buildscript classpath configuration

If you apply plugins to your build, you may want to leverage dependency locking there as well.
In order to lock the <<plugins.adoc#sec:applying_plugins_buildscript,`classpath` configuration>> used for script plugins, do the following:

.Locking buildscript classpath configuration
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingClasspathConfiguration/groovy",files="build.gradle[tags=locking-classpath]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingClasspathConfiguration/kotlin",files="build.gradle.kts[tags=locking-classpath]"]
====

Produced lockfiles will have a `buildscript-` prefix to their name to prevent any name collision with locking of regular project configurations.

=== Locking settings classpath configuration

By doing the same as above in your <<build_lifecycle.adoc#sec:settings_file,Gradle settings file>>, you can lock the settings `classpath` configuration or any custom configuration you resolve as part of the settings.
Produced lockfiles will have a `settings-` prefix to their name to prevent any name collision with either project configurations or project buildscript ones.

== Generating and updating dependency locks

In order to generate or update lock state, you specify the `--write-locks` command line argument in addition to the normal tasks that would trigger configurations to be resolved.
This will cause the creation of lock state for each resolved configuration in that build execution.
Note that if lock state existed previously, it is overwritten.

[[lock_all_configurations_in_one_build_execution]]
=== Lock all configurations in one build execution

When locking multiple configurations, you may want to lock them all at once, during a single build execution.

For this, you have two options:

* Run `gradle dependencies --write-locks`.
This will effectively lock all resolvable configurations that have locking enabled.
Note that in a multi project setup, `dependencies` only is executed on _one_ project, the root one in this case.
* Declare a custom task that will resolve all configurations

.Resolving all configurations
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingAllConfigurations/groovy",files="build.gradle[tags=resolve-all]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingAllConfigurations/kotlin",files="build.gradle.kts[tags=resolve-all]"]
====

That second option, with proper choosing of configurations, can be the only option in the native world, where not all configurations can be resolved on a single platform.

== Lock state location and format

Lock state will be preserved in a file located in the folder `gradle/dependency-locks` inside the project or subproject directory.
Each file is named by the configuration it locks and has the `lockfile` extension.
There are two exceptions to this rule: for configurations for the <<plugins.adoc#sec:applying_plugins_buildscript,buildscript itself>> and for the <<build_lifecycle.adoc#sec:settings_file,settings>>.
In that case the configuration name will be prefixed with `buildscript-` and `settings-` respectively.

The content of the file is a module notation per line, with a header giving some context.
Module notations are ordered alphabetically, to ease diffs.

.Lockfile content
[listing]
.gradle/dependency-locks/compileClasspath.lockfile
----
include::{snippetsPath}/dependencyManagement/dependencyLocking-lockingSingleConfiguration/groovy/gradle/dependency-locks/compileClasspath.lockfile[]
----

which matches the following dependency declaration:

.Dynamic dependency declaration
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleConfiguration/groovy",files="build.gradle[tags=locking-deps]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-deps]"]
====

== Running a build with lock state present

The moment a build needs to resolve a configuration that has locking enabled and it finds a matching lock state,
it will use it to verify that the given configuration still resolves the same versions.

A successful build indicates that the same dependencies are used as stored in the lock state, regardless if new versions matching the dynamic selector have been produced.

The complete validation is as follows:

* Existing entries in the lock state must be matched in the build
** A version mismatch or missing resolved module causes a build failure
* Resolution result must not contain extra dependencies compared to the lock state

[[fine_tuning_dependency_locking_behaviour_with_lock_mode]]
=== Fine tuning dependency locking behaviour with lock mode

While the default lock mode behaves as described above, two other modes are available:

Strict mode::
In this mode, in addition to the validations above, dependency locking will fail if a configuration marked as _locked_ does not have lock state associated with it.

Lenient mode::
In this mode, dependency locking will still pin dynamic versions but otherwise changes to the dependency resolution are no longer errors.

The lock mode can be controlled from the `dependencyLocking` block as shown below:

.Setting the lock mode
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockModeSelection/groovy",files="build.gradle[tags=lock-mode]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockModeSelection/kotlin",files="build.gradle.kts[tags=lock-mode]"]
====

[[selectively_updating_lock_state_entries]]
== Selectively updating lock state entries

In order to update only specific modules of a configuration, you can use the `--update-locks` command line flag.
It takes a comma (`,`) separated list of module notations.
In this mode, the existing lock state is still used as input to resolution, filtering out the modules targeted by the update.

----
❯ gradle classes --update-locks org.apache.commons:commons-lang3,org.slf4j:slf4j-api
----

Wildcards, indicated with `*`, can be used in the group or module name. They can be the only character or appear at the end of the group or module respectively.
The following wildcard notation examples are valid:

* `org.apache.commons:*`: will let all modules belonging to group `org.apache.commons` update
* `*:guava`: will let all modules named `guava`, whatever their group, update
* `org.springframework.spring*:spring*`: will let all modules having their group starting with `org.springframework.spring` and name starting with `spring` update

[NOTE]
====
The resolution may cause other module versions to update, as dictated by the Gradle resolution rules.
====

== Disabling dependency locking

. Make sure that the configuration for which you no longer want locking is not configured with locking.
. Remove the file matching the configurations where you no longer want locking.

If you only perform the second step above, then locking will effectively no longer be applied.
However, if that configuration happens to be resolved in the future at a time where lock state is persisted, it will once again be locked.

== Single lock file per project

Gradle supports an improved lock file format.
The goal is to have only a single lock file per project, which contains the lock state for all configurations of said project.
By default, the file is named `gradle.lockfile` and is located inside the project directory.
The lock state for the buildscript itself is found in a file named `buildscript-gradle.lockfile` inside the project directory.

[NOTE]
====
It is impossible to leverage the single lockfile format for the settings configurations locking, because feature previews are applied after Gradle settings are configured.
====

The main benefit is a substantial reduction in the number of lock files compared to the format requiring one lockfile per locked configuration.

This format requires a migration for existing locking users and is thus opt-in.

[NOTE]
====
The objective is to default to this single lock file per project in Gradle 7.0.
====

The format can be activated by enabling the matching <<feature_lifecycle#feature_preview, feature preview>>:

.Single lock file per project activation
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/groovy",files="settings.gradle[]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/kotlin",files="settings.gradle.kts[]"]
====

Then with the following dependency declaration and locked configurations:

.Explicit locking
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/groovy",files="build.gradle[tags=locking-explicit]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=locking-explicit]"]
====

The lockfile will have the following content:

[listing]
.gradle.lockfile
----
include::{snippetsPath}/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/groovy/gradle.lockfile[]
----

* Each line still represents a single dependency in the `group:artifact:version` notation
* It then lists all configurations that contain the given dependency
* The last line of the file lists all empty configurations, that is configurations known to have no dependencies

=== Migrating to the single lockfile per project format

Once you have activated the feature preview (see above), you can simply follow the documentation for <<#lock_all_configurations_in_one_build_execution, writing>> or <<#selectively_updating_lock_state_entries, updating>> dependency lock state.

Then after confirming the single lock file per project contains the lock state for a given configuration, the matching per configuration lock file can be removed from `gradle/dependency-locks`.

[[configuring_the_per_project_lock_file_name_and_location]]
=== Configuring the per project lock file name and location

When using the single lock file per project, you can configure its name and location.
The main reason for providing this is to enable having a file name that is determined by some project properties, effectively allowing a single project to store different lock state for different execution contexts.
One trivial example in the JVM ecosystem is the Scala version that is often found in artifact coordinates.

.Changing the lock file name
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/groovy",files="build.gradle[tags=locking-file-name]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=locking-file-name]"]
====

[[ignoring_dependencies]]
== Ignoring specific dependencies from the lock state

Dependency locking can be used in cases where reproducibility is not the main goal.
As a build author, you may want to have different frequency of dependency version updates, based on their origin for example.
In that case, it might be convenient to ignore some dependencies because you always want to use the latest version for those.
An example is the internal dependencies in an organization which should always use the latest version as opposed to third party dependencies which have a different upgrade cycle.

[WARNING]
====
This feature can break reproducibility and should be used with caution.
There are scenarios that are better served with leveraging  <<#fine_tuning_dependency_locking_behaviour_with_lock_mode,different lock modes>> or <<#configuring_the_per_project_lock_file_name_and_location,using different names for lock files>>.
====

You can configure ignored dependencies in the `dependencyLocking` project extension:

.Ignoring dependencies for the lock state
====
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/groovy",files="build.gradle[tags=ignore-dependencies]"]
include::sample[dir="snippets/dependencyManagement/dependencyLocking-lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=ignore-dependencies]"]
====

The notation is a `<group>:<name>` dependency notation, where `\*` can be used as a trailing wildcard.
See <<#selectively_updating_lock_state_entries,the description>> on updating lock files for more details.
Note that the value `*:*` is not accepted as it is equivalent to disabling locking.

Ignoring dependencies will have the following effects:

* An ignored dependency applies to all locked configurations. The setting is project scoped.
* Ignoring a dependency does not mean lock state ignores its transitive dependencies.
* There is no validation that an ignored dependency is present in any configuration resolution.
* If the dependency is present in lock state, loading it will filter out the dependency.
* If the dependency is present in the resolution result, it will be ignored when validating that resolution matches the lock state.
* Finally, if the dependency is present in the resolution result and the lock state is persisted, it will be absent from the written lock state.

[[locking_limitations]]
== Locking limitations

* Locking cannot yet be applied to source dependencies.

== Nebula locking plugin

This feature is inspired by the https://github.com/nebula-plugins/gradle-dependency-lock-plugin[Nebula Gradle dependency lock plugin].

