Gradle plugin for publishing to Git repositories
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci Add Java 11 to Circle CI Oct 6, 2018
.github Usage documentation Dec 17, 2016
.stutter Upgrade to grgit 3 Oct 6, 2018
gradle Upgrade to grgit 3 Oct 6, 2018
src Test for copying to multiple subdirs Oct 6, 2018
.gitignore Migrate to Circle CI and update defaults Apr 8, 2018
LICENSE
README.md Migrate to Circle CI and update defaults Apr 8, 2018
build.gradle Remove duplicate bintray config Oct 6, 2018
gradle.properties.enc Migrate to Circle CI and update defaults Apr 8, 2018
gradlew
gradlew.bat fix travis stuff Nov 5, 2016
settings.gradle Use newer gradle features Jun 2, 2018

README.md

gradle-git-publish

Download CircleCI

Why do you care?

Git is immensely popular and being able to publish to it as part of a build process can be very valuable, for example to publish a blog or project documentation to GitHub Pages.

What is it?

gradle-git-publish is a Gradle plugin, org.ajoberstar.git-publish, which publishes files to a remote Git repository's branch.

See Grgit for details on the Git library used underneath, including configuration for authentication.

Usage

See the Release Notes for updates on changes and compatibility with Java and Gradle versions.

Applying the Plugin

Plugins DSL

plugins {
    id 'org.ajoberstar.git-publish' version '<version>'
}

Classic

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.ajoberstar:gradle-git-publish:<version>'
    }
}

apply plugin: 'org.ajoberstar.git-publish'

Configuration

NOTE: In general, there are no default values here. The main exception is that the repoUri will be automatically set if you use the org.ajoberstar.grgit plugin to your project's origin repo URI.

gitPublish {
    // where to publish to (repo must exist)
    repoUri = 'git@github.com/ajoberstar/test-repo.git'
    // (or 'https://github.com/ajoberstar/test-repo.git', depending on authentication)

    // branch will be created if it doesn't exist
    branch = 'gh-pages'

    // generally, you don't need to touch this
    repoDir = file("$buildDir/somewhereelse") // defaults to $buildDir/gitPublish

    // what to publish, this is a standard CopySpec
    contents {
        from 'src/pages'
        from(javadoc) {
            into 'api'
        }
    }

    // what to keep in the existing branch (include=keep)
    preserve {
        include '1.0.0/**'
        exclude '1.0.0/temp.txt'
    }

    // message used when committing changes
    commitMessage = 'Publishing a new page' // defaults to 'Generated by gradle-git-publish'
}

Tasks and Execution

Generally, you'll just run gitPublishPush, but there is a series of four tasks that happen in order.

  • gitPublishReset - Clones/updates the working repo to the latest commit on the repoUri branch head. All files not included by the preserve filters will be deleted and staged.
  • gitPublishCopy - Copies any files defined in the contents CopySpec into the working repo.
  • gitPublishCommit - Commits all changes to the working repo.
  • gitPublishPush - If changes were committed, pushed them to the repoUri.

Avoiding Extra Copy

If you are generating a large site, you may want to directly generate it into the working repo to save an extra copy step. You can do this with task dependencies and referring to the repoDir.

jbakeTask {
    outputDir gitPublish.repoDir
    dependsOn gitPublishReset
}

gitPublishCommit.dependsOn jbakeTask

Migrating from org.ajoberstar.github-pages

The following table should help translate settings you used in org.ajoberstar.github-pages to this plugin's format. Additionally reference the Configuration section above for more information on the current feature set.

org.ajoberstar.github-pages org.ajoberstar.git-publish Comment
repoUri repoUri Used to allow any Object (which would be lazily unpacked to a String). Now requires a String.
targetBranch branch The old plugin defaulted to gh-pages, the new one has no default. This must be a String.
workingPath repoDir Used to allow any Object and called file() on it for you. Now expects a File.
pages contents Just a name change.
deleteExistingFiles preserve If previously true (the default), do nothing. If previously false, preserve { include '**/*' }
commitMessage commitMessage Just copy from the old value.
credentials env variable or system prop GRGIT_USER environment variable or org.ajoberstar.grgit.auth.username system property.

Questions, Bugs, and Features

Please use the repo's issues for all questions, bug reports, and feature requests.

Contributing

Contributions are very welcome and are accepted through pull requests.

Smaller changes can come directly as a PR, but larger or more complex ones should be discussed in an issue first to flesh out the approach.

If you're interested in implementing a feature on the issues backlog, add a comment to make sure it's not already in progress and for any needed discussion.

Acknowledgements

Thanks to all of the contributors.

I also want to acknowledge Peter Ledbrook for the initial idea and code for the plugin.