JarCastingGradleGitDependencies
Gradle plugin to add external git repositories as dependencies.
Setup
In settings.gradle file add the following lines:
- If using Gradle 6.x.x
plugins {
id 'com.alexvasilkov.git-dependencies' version '2.0.4'
}
- If using older Gradle version
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.alexvasilkov:gradle-git-dependencies:2.0.4'
}
}
apply plugin: 'com.alexvasilkov.git-dependencies'
Optionally you can provide settings next in settings.gradle:
git {
dir 'libs' // Directory in which to store git repositories, 'libs' by default
cleanup true // Whether to cleanup unused dirs inside 'libs' dir, true by default
defaultAuthGroup 'group name' // Default auth group to be used for all repos. See `Credentials` section below.
}
Usage
Note that the plugin only works with Groovy scripts, no Kotlin DSL support is available yet.
Now in project's build.gradle add the following:
git {
implementation 'https://example.com/repository.git', {
name 'DependencyName'
commit '12345678abcdefgh'
}
}
Where implementation is a configuration name, similar as used for regular gradle dependencies. Can be any valid configuration name.
Supported parameters
| Parameter | Description |
|---|---|
| name | Dependency name. Will be used as gradle project name and as repo directory name. If the name is not set then it will be taken from url. |
| commit | Git commit id of any length, tag name or branch name. For example e628b205, v1.2.3. Set to master by default. |
| tag | Same as commit, see above. |
| branch | Same as commit, see above. |
| dir | Directory for cloned repository. Used to override default directory as defined in settings.gradle. |
| projectPath | Path within repository which should be added as gradle project. By default repo's root directory is added as project. |
| username | Username to access repository. See Credentials section below. |
| password | Password to access repository. See Credentials section below. |
| authGroup | Group name used when looking for credentials. See Credentials section below. |
| keepUpdated | Whether to update this repository automatically or not. Default is true. |
Note that using master or any other branch name as git commit is not recommended, use explicit commit or tag instead.
You can also specify git repos in settings.gradle similar as it is done in build.gradle but use fetch instead of configuration name:
git {
fetch 'https://example.com/repository.git', {
dir "$rootDir/gradle/scripts"
tag 'v1.2.3'
}
}
Such repositories will be downloaded but not added as dependencies. This can be useful, for example, if you want to pre-fetch build scripts.
Examples
git {
implementation '[email protected]:alexvasilkov/GestureViews.git'
api 'https://github.com/alexvasilkov/GestureViews.git', {
name 'GestureViews'
tag 'v2.6.0'
projectPath '/library'
}
}
How it works
- You're providing git repository URL and other optional details in
build.gradlefile. - The plugin clones repository to
libs/[name]directory (both name and directory can be changed) at specified commit, tag or branch. - Cloned repo will be included as sub-project and defined as dependency of original project.
- Dependencies are resolved recursively, i.e. your git dependency can have other git dependencies.
- If several projects have dependencies with same name then all other details (url, commit, etc) should be completely the same, otherwise build process will fail.
- The plugin automatically updates repository if
commitdoesn't much local commit. If there're any uncommited changes in local repo then build process will fail until you manually resolve conflicts. - Removed dependencies will be automatically cleaned from
libsdirectory.
Credentials
If git repo is using SSH url (starts with git@) then the plugin will automatically try to use local SSH key. But you need to ensure your SSH key is correctly setup, see instructions for GitHub or Bitbucket
If git repo is using HTTPS url then there are two options how you can define credentials:
- Using
usernameandpasswordoptions directly inbuild.gradle. - Using
authGroupoption and providing credentials as specified below.
If authGroup is provided then the plugin will search for git.[authGroup].username and git.[authGroup].password params in:
- command line arguments (e.g.
[email protected]) - gradle.properties
- local.properties
- ~/.gradle/gradle.properties
- environment variables, in uppercase and with
_instead of., e.g.GIT_GITHUB_USERNAME
If defaultAuthGroup is provided in settings.gradle then it will be used for all repos unless authGroup is explicitly set.
Migration from v1.x.x
There were several breaking changes since version 1.x.x:
- Default directory is changed from
librariestolibs. - Instead of defining
def vcs() { ... }method you can use simplergit { ... } - Git dependencies declaration is reimplemented to mimic default gradle dependencies section.
- Credentials properties names are changed, e.g. was
GIT_AUTHGROUP_USERNAME, becomegit.authGroup.username. - Dropped SVN support.
License
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.