Merge pull request #246 from ajoberstar/groovy

Breaking changes for Groovy 2.5, JGit 5, and JSch agent removal

build.gradle

@@ -1,25 +1,24 @@
 plugins {
   id 'org.ajoberstar.defaults' version '0.12.0'
   id 'org.jbake.site' version '1.0.0'
-  id 'java-gradle-plugin'
-  id 'groovy'
 }
 
-group = 'org.ajoberstar'
-description = 'The Groovy way to use Git.'
+apply from: 'gradle/locking.gradle'
+apply from: 'gradle/bintray.gradle'
 
-sourceCompatibility = 8
+allprojects {
+  group = 'org.ajoberstar.grgit'
+  description = 'The Groovy way to use Git.'
 
-// compat tests use grgit to set up and verify the tests
-sourceSets {
-  compatTest {
-    compileClasspath += main.output
-    runtimeClasspath += main.output
+  plugins.withId('java') {
+    sourceCompatibility = 8
+
+    repositories {
+      mavenCentral()
+    }
   }
 }
 
-configurations.compatTestCompile.extendsFrom configurations.compile
-
 jbake {
   srcDirName = 'docs'
 }
@@ -31,115 +30,3 @@ gitPublish {
 }
 
 gitPublishCopy.dependsOn bake
-
-repositories {
-  mavenCentral()
-}
-
-// workaround for java-gradle-plugin adding gradleApi() to the compile classpath
-configurations.compile.withDependencies { deps ->
-  deps.remove(dependencies.gradleApi())
-}
-
-// workaround for gradle-defaults excluding groovy from all configurations
-configurations.all {
-  excludeRules = []
-}
-configurations.compatTestCompile {
-  exclude group: 'org.codehaus.groovy'
-}
-
-dependencyLocking {
-  lockAllConfigurations()
-}
-
-dependencies {
-  // groovy
-  testCompile 'org.codehaus.groovy:groovy-all:[2.4.0, 3.0.0)'
-
-  // gradle
-  compileOnly gradleApi()
-
-  // jgit
-  def jgitVersion = '4.11.0.201803080745-r'
-  compile "org.eclipse.jgit:org.eclipse.jgit:$jgitVersion"
-  compile "org.eclipse.jgit:org.eclipse.jgit.ui:$jgitVersion"
-
-  // agentproxy
-  def agentProxyVersion = '[0.0.9,)'
-  compile "com.jcraft:jsch.agentproxy.core:$agentProxyVersion"
-  compile "com.jcraft:jsch.agentproxy.jsch:$agentProxyVersion"
-  compile "com.jcraft:jsch.agentproxy.pageant:$agentProxyVersion"
-  compile "com.jcraft:jsch.agentproxy.sshagent:$agentProxyVersion"
-  compile "com.jcraft:jsch.agentproxy.usocket-jna:$agentProxyVersion"
-  compile "com.jcraft:jsch.agentproxy.usocket-nc:$agentProxyVersion"
-  // agentproxy pulls this in, but we need to force a newer version
-  compile 'com.jcraft:jsch:[0.1.54,)'
-
-  // logging
-  testCompile "org.slf4j:slf4j-api:[1.7.25,1.8.0-alpha)" // wait for final 1.8.0 to come out before letting it in
-  testRuntime "org.slf4j:slf4j-simple:[1.7.25,1.8.0-alpha)"
-
-  // testing
-  testCompile "junit:junit:latest.release"
-  compatTestCompile "junit:junit:latest.release"
-  testCompile "org.spockframework:spock-core:1.1-groovy-2.4"
-  compatTestCompile "org.spockframework:spock-core:1.1-groovy-2.4"
-}
-
-test {
-  useJUnit {
-    excludeCategories 'org.ajoberstar.grgit.fixtures.PlatformSpecific'
-  }
-}
-
-['Windows', 'Linux'].each { platform ->
-  tasks.create("test${platform}", Test) {
-    useJUnit {
-      includeCategories "org.ajoberstar.grgit.fixtures.${platform}Specific"
-    }
-    systemProperty 'org.slf4j.simpleLogger.defaultLogLevel', 'debug'
-  }
-}
-
-stutter {
-  sparse = true
-  includeActiveRc = true
-  java(8) {
-    compatibleRange '3.0'
-  }
-  java(9) {
-    compatibleRange '4.2.1'
-  }
-}
-
-publishing {
-  repositories {
-    maven {
-      name = 'bintray'
-      url = 'https://api.bintray.com/maven/ajoberstar/maven/grgit/;publish=1'
-      credentials {
-        username = System.env['BINTRAY_USER']
-        password = System.env['BINTRAY_KEY']
-      }
-    }
-  }
-}
-
-pluginBundle {
-    website = 'https://github.com/ajoberstar/grgit'
-    vcsUrl = 'https://github.com/ajoberstar/grgit.git'
-    description = 'The Groovy way to use Git'
-    plugins {
-        publishPlugin {
-            id = 'org.ajoberstar.grgit'
-            displayName = 'The Groovy way to use Git'
-            tags = ['git', 'groovy']
-        }
-    }
-    mavenCoordinates {
-        groupId = project.group
-        artifactId = project.name
-        version = project.version
-    }
-}

docs/content/grgit-authentication.adoc

@@ -0,0 +1,83 @@
+= grgit-authentication
+:jbake-title: grgit-authentication
+:jbake-type: page
+:jbake-status: published
+
+== Description
+
+[IMPORTANT]
+====
+JSCH authentication (and its agent proxy) are not supported in Grgit 3.x.
+
+If you're using Grgit 2.x, see the link:grgit-authentication-2.adoc[documentation] for that version.
+====
+
+Grgit communicates with remote repositories in one of three ways:
+
+. HTTP(S) protocol with basic auth credentials (i.e. username/password).
++
+TIP: Where possible, use of HTTPS urls is preferred over the SSH options. It has far simpler behavior than the SSH options.
+. SSH protocol using `ssh` or `plink` directly. This approach should work as long as you can push/pull on your machine.
++
+TIP: You should be using an SSH agent to have your key loaded before Grgit runs.
+
+== HTTP BasicAuth Credentials
+
+These are presented in precedence order (direct parameter in code, system properties, environment variables).
+
+=== Parameter to Grgit operations
+
+Some Grgit operations, such as link:grgit-clone.html[grgit-clone] allow you to provide credentials programmatically.
+
+[source, groovy]
+----
+import org.ajoberstar.grgit.Grgit
+import org.ajoberstar.grgit.Credentials
+
+def grgit = Grgit.clone(dir: '...', url: '...', credentials: new Credentials(username, password))
+----
+
+=== System Properties
+
+org.ajoberstar.grgit.auth.username:: Username to provide when basic authentication credentials are needed. Username can be specified without a password (e.g. using a GitHub auth token as the user and providing no password).
+org.ajoberstar.grgit.auth.password:: Password to provide when basic authentication credentials are needed.
+
+=== Environment Variables
+
+GRGIT_USER:: Username to provide when basic authentication credentials are needed. Username can be specified without a password (e.g. using a GitHub auth token as the user and providing no password).
+GRGIT_PASS:: Password to provide when basic authentication credentials are needed.
+
+== SSH
+
+If the `GIT_SSH` environment variable is set, that command will be used. If not, Grgit will scan your `PATH` for an `ssh` (preferred) or `plink` command.
+
+Any keys your `ssh` or `plink` can natively pick up will be used. This should include keys in default locations (e.g. `~/`) and any compatible SSH agent or OS keychain.
+
+[CAUTION]
+====
+Grgit cannot provide credentials to the system `ssh` or `plink` commands. If your key is password protected and not loaded in an agent, authentication _will_ fail **or** hang indefinitely.
+====
+
+== Examples
+
+This is a non-exhaustive list of examples of how to configure authentication in common scenarios.
+
+=== Using a GitHub auth token with HTTPS URLs
+
+Set the environment variable `GRGIT_USER` to your authentication token from GitHub.
+
+=== Using a Username and Password with HTTPS URLs
+
+Set the system properties:
+
+----
+groovy -Dorg.ajoberstar.grgit.auth.username=someone -Dorg.ajoberstar.grgit.auth.password=mysecretpassword myscript.groovy
+----
+
+=== Using ssh-agent
+
+Make sure your ssh-agent is started and your key is loaded. Then just run your application or script.
+
+=== Using Pageant
+
+Make sure your Pageant is started and your key is loaded. Then just run your application or script.

docs/content/grgit-branch.ad → docs/content/grgit-branch.adoc

@@ -38,10 +38,10 @@ grgit.branch.remove(names: [<name>, ...], force: <boolean>)
 == Description
 
 
-`grgit.branch.current()`:: Returns the current link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
-`grgit.branch.list()`:: Returns a list of branches (link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch]). The branches returned can be filtered using `mode` and `contains`.
-`grgit.branch.add(name: <name>, startPoint: <startPoint>, mode: <mode>)`:: Creates a new branch named `<name>` pointing at `<startPoint>`, possibly tracking a remote depending on `<mode>`. Returns the created link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
-`grgit.branch.change(name: <name>, startPoint: <startPoint>, mode: <mode>)`:: Modify an existing branch named `<name>` pointing at `<startPoint>`, possibly tracking a remote depending on `<mode>`. Returns the modified link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
+`grgit.branch.current()`:: Returns the current link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
+`grgit.branch.list()`:: Returns a list of branches (link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Branch.html[Branch]). The branches returned can be filtered using `mode` and `contains`.
+`grgit.branch.add(name: <name>, startPoint: <startPoint>, mode: <mode>)`:: Creates a new branch named `<name>` pointing at `<startPoint>`, possibly tracking a remote depending on `<mode>`. Returns the created link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
+`grgit.branch.change(name: <name>, startPoint: <startPoint>, mode: <mode>)`:: Modify an existing branch named `<name>` pointing at `<startPoint>`, possibly tracking a remote depending on `<mode>`. Returns the modified link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
 `grgit.branch.remove(names: [<name>, ...], force: <boolean>)`:: Removes one or more branches. Returns a `List<String>` of branch names removed.
 
 == Options

docs/content/grgit-clone.ad → docs/content/grgit-clone.adoc

@@ -36,7 +36,7 @@ After the clone, a plain link:grgit-fetch.html[grgit-fetch] without arguments wi
 
 This default configuration is achieved by creating references to the remote branch heads under `refs/remotes/origin` and by initializing `remote.origin.url` and `remote.origin.fetch` configuration variables.
 
-Returns a link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] instance.
+Returns a link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] instance.
 
 == Options
 
@@ -46,7 +46,7 @@ remote:: (`String`, default `origin`) Instead of using the remote name `origin`
 bare:: (`boolean`, default `false`) Create a bare repository.
 checkout:: (`boolean`, default `true`) Set to `false` to skip checking out a `HEAD`.
 refToCheckout:: (`String`, default `null`) Instead of pointing the newly created `HEAD` to the branch pointed to by the cloned repository’s `HEAD`, point to `<name>` branch instead. In a non-bare repository, this is the branch that will be checked out. This can also take tags and detaches the `HEAD` at that commit in the resulting repository.
-credentials:: (`Credentials`, default `null`) An instance of link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Credentials.html[Credentials] containing username/password to be used in operations that require authentication. See link:grgit-authentication.html[grgit-authentication] for preferred ways to configure this.
+credentials:: (`Credentials`, default `null`) An instance of link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Credentials.html[Credentials] containing username/password to be used in operations that require authentication. See link:grgit-authentication.html[grgit-authentication] for preferred ways to configure this.
 
 == Examples
 

docs/content/grgit-commit.ad → docs/content/grgit-commit.adoc

@@ -41,7 +41,7 @@ The content to be added can be specified in several ways:
 
 If you make a commit and then find a mistake immediately after that, you can recover from it with link:grgit-reset.html[grgit-reset].
 
-Returns a link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Commit.html[Commit] representing the new `HEAD`.
+Returns a link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Commit.html[Commit] representing the new `HEAD`.
 
 == Options
 
@@ -50,8 +50,8 @@ paths:: (`Set<String>`, default `[]`) When files are given on the command line,
 all:: (`boolean`, default `false`) Tell the command to automatically stage files that have been modified and deleted, but new files you have not told Git about are not affected.
 amend:: (`boolean`, default `false`) Replace the tip of the current branch by creating a new commit. The recorded tree is prepared as usual, and the message from the original commit is used as the starting point, instead of an empty message, when no other message is specified from the command line. The new commit has the same parents and author as the current one.
 reflogComment:: (`String`, default `null`) Use a different comment in the reflog for this commit.
-committer:: (`Person`, default `null`) Override the committer recorded in the commit. This must be a link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Person.html[Person].
-author:: (`Person`, default `null`) Override the author recorded in the commit. This must be a link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Person.html[Person].
+committer:: (`Person`, default `null`) Override the committer recorded in the commit. This must be a link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Person.html[Person].
+author:: (`Person`, default `null`) Override the author recorded in the commit. This must be a link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Person.html[Person].
 
 == Examples
 

docs/content/grgit-describe.ad → docs/content/grgit-describe.adoc

@@ -16,14 +16,15 @@ grgit.describe()
 
 [source, groovy]
 ----
-grgit.describe(commit: <commit>, longDescr: <boolean>, match: [<string>])
+grgit.describe(commit: <commit>, longDescr: <boolean>, tags: <boolean>, match: [<string>])
 ----
 
 [source, groovy]
 ----
 grgit.describe {
   commit = <commit>
   longDescr = <boolean>
+  tags = <boolean>
   match = [<string>]
 }
 ----
@@ -38,6 +39,7 @@ Describe only shows annotated tags. For more information about creating annotate
 
 commit:: (`Object`, default `null`) Commit-ish object names to describe. Defaults to HEAD if omitted. For a more complete list of ways to spell commit names, see link:grgit-resolve.html[grgit-resolve] (specifically the `toCommit` method).
 longDescr:: (`boolean`, default `false`) Always output the long format (the tag, the number of commits and the abbreviated commit name) even when it matches a tag. This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 that points at object deadbee…​.).
+tags:: (`boolean`, default `false`) Instead of using only the annotated tags, use any tag found in `refs/tags` namespace. This option enables matching a lightweight (non-annotated) tag.
 match:: (`List<String>`, default `[]`) Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix. This can be used to avoid leaking private tags from the repository. If multiple patterns are given they will be accumulated, and tags matching any of the patterns will be considered.
 
 == Examples

docs/content/grgit-gradle.ad → docs/content/grgit-gradle.adoc

@@ -15,7 +15,7 @@ plugins {
 
 ## What does the plugin do?
 
-The `org.ajoberstar.grgit` plugin adds a `grgit` property to your build, which is an instance of link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] opened to the repository visible from your project's root dir. This will check the project directory and its parents for a `.git` directory. If no repository is found, the `grgit` property is `null`.
+The `org.ajoberstar.grgit` plugin adds a `grgit` property to your build, which is an instance of link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] opened to the repository visible from your project's root dir. This will check the project directory and its parents for a `.git` directory. If no repository is found, the `grgit` property is `null`.
 
 ```groovy
 version = "1.0.0-${grgit.head().abbreviatedId}"

docs/content/grgit-head.ad → docs/content/grgit-head.adoc

@@ -16,7 +16,7 @@ grgit.head()
 
 == Description
 
-Returns the link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Commit.html[Commit] that the current `HEAD` points to.
+Returns the link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Commit.html[Commit] that the current `HEAD` points to.
 
 == Options
 

docs/content/grgit-init.ad → docs/content/grgit-init.adoc

@@ -26,7 +26,7 @@ grgit.init {
 
 This command creates an empty Git repository - basically a `.git` directory with subdirectories for `objects`, `refs/heads`, `refs/tags`, and template files. An initial `HEAD` file that references the HEAD of the master branch is also created.
 
-Returns a link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] instance.
+Returns a link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] instance.
 
 == Options
 

docs/content/grgit-log.ad → docs/content/grgit-log.adoc

@@ -57,7 +57,7 @@ grgit.log {
 }
 ----
 
-Returns a `List<Commit>` (link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Commit.html[Commit]) with the commits matching the criteria given.
+Returns a `List<Commit>` (link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Commit.html[Commit]) with the commits matching the criteria given.
 
 == Options
 

docs/content/grgit-lsremote.ad → docs/content/grgit-lsremote.adoc

@@ -30,7 +30,7 @@ grgit.lsremote {
 
 == Description
 
-Returns a `Map<Ref, String>` (link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Ref.html[Ref]) containing references available in the remote, and the object ID they currently point to.
+Returns a `Map<Ref, String>` (link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Ref.html[Ref]) containing references available in the remote, and the object ID they currently point to.
 
 == Options
 

docs/content/grgit-open.ad → docs/content/grgit-open.adoc

@@ -32,13 +32,13 @@ grgit.open {
 
 This command opens an existing Git repository. If both `dir` and `currentDir` are `null`, acts as if the `currentDir` is the JVM's working directory.
 
-Returns a link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] instance.
+Returns a link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Grgit.html[Grgit] instance.
 
 == Options
 
 dir:: (`Object`, default `null`) The directory the repository is in. Can be a `File`, `Path`, or `String`.
 currentDir:: (`Object`, default `null`) The directory to start searching for the repository from. Can be a `File`, `Path`, or `String`.
-creds:: (`Credentials`, default `null`) An instance of link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Credentials.html[Credentials] containing username/password to be used in operations that require authentication. See link:grgit-authentication.html[grgit-authentication] for preferred ways to configure this.
+creds:: (`Credentials`, default `null`) An instance of link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Credentials.html[Credentials] containing username/password to be used in operations that require authentication. See link:grgit-authentication.html[grgit-authentication] for preferred ways to configure this.
 
 == Examples
 

docs/content/grgit-remote.ad → docs/content/grgit-remote.adoc

@@ -37,8 +37,8 @@ grgit.remote.add {
 
 Manage the set of repositories ("remotes") whose branches you track.
 
-`list()` returns a `List<Remote>` (link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Remote.html[Remote]) of all remotes configured for the repo.
-`add()` returns the newly configured link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Remote.html[Remote]
+`list()` returns a `List<Remote>` (link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Remote.html[Remote]) of all remotes configured for the repo.
+`add()` returns the newly configured link:http://ajoberstar.org/grgit/docs/grgit-core/groovydoc/org/ajoberstar/grgit/Remote.html[Remote]
 
 == Options