Included Git repositories plugin for Gradle

Multi-repository development, while providing architectural advantages (reduced scope of libraries, faster development cycles, …​), are often painful for developers, especially when the number of modules being involved grows.

For example, to develop a single feature, a developer may have to work on more than one repository at a time: a core module, living in repository core, and a library module depending on core, living in a repository library.

The problem is that the development of a particular feature may require changes to both core and library. In that case, developers, in the Java ecosystem, typically rely on publishing snapshots in their local Maven repository: make a change in core, publish a snapshot, then make changes to library, publish a snapshot, and repeat the loop.

There are several problems with this approach:

• it requires switching between projects, publishing intermediate artifacts to the local filesystem

• makes it difficult to collaborate with others as they also need to checkout several projects

• it requires integrating mavenLocal() as a repository for your local builds, which is considered a bad practice (because it introduces non-reproducibility and makes the builds brittle)

• for CI, it requires publishing to a snapshot repository for downstream builds to pick up the changes, meaning that you will often have to merge work-in-progress just to be able to test changes

• it simply doesn’t work if the library that you want to work with is not a first level dependency

To improve the situation, Gradle users can use composite builds to avoid publishing to a local repository. This makes the development cycle much faster already, by avoiding the publishToMavenLocal dance. However, there are some limitations with composite builds:

• the included builds must be available locally, in a directory

• it makes it hard, or even impossible, to setup on CI servers, unless you create an "integrating" project which hardcodes checkouts

• it forces to change the configuration of the build to use composites

In addition, there’s a process problem with developing in a multi-repository environment: if the feature requires changes to multiple modules, in order to be able to integrate the changes, in particular on CI, you have to publish either snapshots or pre-releases. The problem is that this is not necessarily acceptable: for example you might want to develop a feature in a branch of each repository, and only merge once the full feature is ready.

Gradle also provides experimental support for source dependencies, but there are addressing a different problem. In particular, source dependencies are a replacement for regular dependencies: they require to change the dependency notation in builds with "source dependencies", including the branches. What we want to do, instead, is to keep our build files untouched, and substitute binary dependencies with sources.

This plugin provides a solution to this problem by allowing to include (in the sense of Gradle included builds) Git repositories, and specifying what branches/tags should be used.

If you’re looking for a synthetic view of pros and cons of each solution, please refer to this section in the docs.