From f33f585b38878c3e02bc5727f6a46ee53566c452 Mon Sep 17 00:00:00 2001 From: Alex Vasilkov Date: Thu, 19 Apr 2018 18:46:29 +0700 Subject: [PATCH] Updated readme --- README.md | 106 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 61 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 59bbd92..c74e08c 100755 --- a/README.md +++ b/README.md @@ -3,30 +3,15 @@ GradleVcsDependencyPlugin [![Maven Central][mvn-img]][mvn-url] -Gradle plugin to add external git/svn repositories as dependencies. - -### How it works ### - -1. You can provide dependency name, git or svn repository info and version in `build.gradle` file. -1. Plugin clones repository to `libraries/[NAME]` directory (can be changed, see further) -at specified commit (git) / revision (svn). -1. Cloned repo will be included as sub-project and correct project dependency will be added to original project. -1. Dependencies are resolved recursively, so your vcs dependencies can have other vcs dependencies -1. If several projects have dependencies with same name then dependencies info and versions -should be completely the same. Otherwise plugin will fail build process. -1. Plugin automatically updates repository if version info was updated. -But if there are any uncommited changes in local repo, than plugin will fail build process -until you manually resolve conflicts. -1. Removed dependencies will be automatically cleaned from `libraries` directory -(can be changed, see further). +Gradle plugin to add external Git and SVN repositories as dependencies. ### How to use ### -In `settings.gradle` file add next lines: +In `settings.gradle` file add the following lines: buildscript { repositories { - mavenCentral() + jcenter() } dependencies { classpath 'com.alexvasilkov:gradle-vcs-dependency:1.0.1' @@ -35,45 +20,75 @@ In `settings.gradle` file add next lines: apply plugin: 'com.alexvasilkov.vcs-dependency' -Optionally you can also provide some settings next in `settings.gradle`: +Optionally you can provide settings next in `settings.gradle`: vcs { dir = 'libs' // Directory in which to store vcs repositories, 'libraries' by default cleanup = false // Whether to cleanup unused dirs inside 'libraries' dir, true by default } -In `build.gradle` add next method: +Now in `build.gradle` add the following method: def vcs() { - svn name: '[Svn dependency name. Required]', - url: '[Svn repository url. Required]', - path: '[Path within repo url, i.e. /trunk/library/. Optional]', - rev: [Revision number or 'HEAD'. Required] - - git name: '[Git dependency name. Required]', - url: '[Git repository url. Required]', - path: '[Path within repo which should be added as dependency, i.e. /library/. Optional]', - commit: '[Commit id of any length, tag name or 'master' to checkout HEAD. Required]' + git name: 'GitDependencyName', + url: 'https://example.com/repository.git', + commit: '12345678abcdefgh' + + svn name: 'SvnDependencyName', + url: 'https://example.com/repository', + rev: 123 } - -Note, that using 'master' as git commit or 'HEAD' as svn revision is not recommended, -use explicit commit / revision instead. -Other optional parameters: +Supported parameters: + +| Parameter | Description | +| --------- | ----------- | +| name | Dependency name, will be used as Gradle dependency name and as source code directory name. Required. | +| url | Git (or SVN) repository url. Required. | +| path | Path within repository which should be added as dependency. For example `/library/`, `/trunk/`. | +| commit | Git commit id of any length, tag name, branch name. For example `v1.2.3` or `master`. Required for Git. | +| rev | SVN revision number or 'HEAD'. Required for SVN. | +| dir | Repository directory, overrides global directory settings. | +| username | Username to access repository. | +| password | Password to access repository. | +| authGroup | Group name (prefix) used when looking for access credentials. See `Credentials` section for more details. Default is `VCS`. | +| noAuth | Whether authentication is required for this repository. Default value is `true` meaning that missing credentials will fail build process. | +| includeProject | Whether to include this repository as Gradle project or not. Can be set to `false` if you only want this repository to be fetched before building main project. Default is `true`. | +| keepUpdated | Whether to update this repository automatically or not. Default is `true`. | +| configName | Gradle dependency configuration name. For example `compile`, `implementation`, `api`. Default value is `implementation`. | + +Note, that using 'master' as git commit or 'HEAD' as svn revision is not recommended, use explicit commit / revision instead. + + +### Example ### def vcs() { - xxx dir: '[Repository directory, overrides global vcs directory settings. Optional.]', - username: '[Username to access repo. Optional.]', - password: '[Password. Optional.]', - authGroup: '[Group name to share same access credentials. Optional, default is VCS.]', - includeProject: [Whether to include this repo as Gradle project. Optional, true by default.], - addDependency: [Whether to add this project as dependency. - Only works if 'includeProject' is true. Optional, true by default.], - keepUpdated: [Whether to update this repo automatically or not. Optional, true by default.] + git name: 'GestureViews', + url: 'https://github.com/alexvasilkov/GestureViews.git', + commit: 'v2.5.1', + path: '/library', + noAuth: true } + +### How it works ### + +1. You're providing dependency name, Git or SVN repository URL and other details in `build.gradle` file. +1. Plugin clones repository to `libraries/[NAME]` project directory (can be changed, see further) +at specified commit (Git) or revision (SVN). +1. Cloned repo will be included as sub-project and necessary dependency will be added to original project. +1. Dependencies are resolved recursively, for example your Git dependency can have other Git or SVN dependencies. +1. If several projects have dependencies with same name then dependencies info and versions +should be completely the same. Otherwise plugin will fail build process. +1. Plugin automatically updates repository if version info was updated. But if there are any uncommited +changes in local repo then plugin will fail build process until you manually resolve conflicts. +1. Removed dependencies will be automatically cleaned from `libraries` directory (can be changed, see further). + + +### Credentials ### + If `username` property is not specified, plugin will look first for property named -`[name in upper case]_USERNAME` and than for property `[authGroup]_USERNAME` +`[name in upper case]_USERNAME` and then for property `[authGroup]_USERNAME` (`VCS_USERNAME` by default) in next places: 1. `vcs.properties` in the root directory of the project @@ -82,11 +97,12 @@ If `username` property is not specified, plugin will look first for property nam 1. Environment variables If `password` property is not specified, plugin will look first for property named -`[name in upper case]_PASSWORD` and than for property `[authGroup]_PASSWORD` +`[name in upper case]_PASSWORD` and then for property `[authGroup]_PASSWORD` (`VCS_PASSWORD` by default) in same places. -I.e. if dependency name is `ProjectName` than plugin will first look for `PROJECTNAME_USERNAME` -and `PROJECTNAME_PASSWORD` properties. +For example, if `name` property is set to `ProjectName` and `authGroup` property set to `Company` +then plugin will first look for properties called `PROJECTNAME_USERNAME` and `PROJECTNAME_PASSWORD`. +If no credentials found then plugin will check properties `COMPANY_USERNAME` and `COMPANY_PASSWORD`. #### License ####