Changed Projects Task Plugin

A Gradle plugin to run a user defined task on changed projects (modules) and their dependent projects (modules) based on git changes. This is based on either the HEAD commit, a specific commit id or even a commit range.

Installation

Recommended way is to apply the plugin to the root build.gradle in the plugins block

plugins {
    id 'io.github.crimix.changed-projects-task' version 'VERSION'
}

and then configure the plugin using the following block still in the root build.gradle

changedProjectsTask {
    taskToRun = "test" //One of the main use cases of the plugin
    alwaysRunProject = [
            ":some-other-project"
    ]
    affectsAllRegex = [
            ~'build.gradle$' //Changes to the root build.gradle affects all projects
    ]
    ignoredRegex = [
            ~'^.*([.]css|[.]html)$' //Ignore changes to front-end files
    ]
}

Configuration

As seen above, there are a few different configuration options available

Usage

To use the added runTaskForChangedProjects from this plugin you need to run it with a few parameters. The minimum required is -PchangedProjectsTask.run or -PchangedProjectsTask.runCommandLine which enables the plugin to run (See the differance below).
Depending on usage, it might also be a good idea to run it with --continue such that all dependent tasks are run, instead of fail-fast behaviour. Then there are four other optional parameters -PchangedProjectsTask.taskToRun, -PchangedProjectsTask.commit, -PchangedProjectsTask.prevCommit and -PchangedProjectsTask.compareMode.

• -PchangedProjectsTask.run informs the plugin to do its work, analysing changes files and which module it belongs to. It will then create a dependsOn relation between its own task and all modules taskToRun. To stop the tasks from running it guards it using an onlyIf, this onlyIf is only put on the taskToRun and not other dependices of that task.

• -PchangedProjectsTask.runCommandLine informs the plugin to do its work, analysing changes files and which module it belongs to. Instead of using dependsOn, this one will invoke the taskToRun on the default commandline of the system. This means it would be just like if you manually called the task for the specific module changed. To supply commandline arguments (including -D and -P arguments), use -PchangedProjectsTask.commandLineArgs

• -PchangedProjectsTask.taskToRun lets you configure the task to run on demand. If it is provided it takes priority over the task configured in the above-mentioned table.

• -PchangedProjectsTask.commit is to configure which ref to use in the git diff.

  • If this is specified with -PchangedProjectsTask.prevCommit it creates a range to use in diff.
    By calling the following git diff --name-only prevCommit~ commit.
  • If it is specified with -PchangedProjectsTask.prevCommit, it uses the following command instead
    git diff --name-only commit~ commit

• -PchangedProjectsTask.prevCommit is to configure which previous ref to use in the git diff.
  This cannot be used without also using -PchangedProjectsTask.commit

• -PchangedProjectsTask.compareMode is used to change which mode it uses to compare. The following modes are available

  • commit (Default, the -PchangedProjectsTask.commit and -PchangedProjectsTask.prevCommit options are the commit ids and makes use of ~)
  • branch (-PchangedProjectsTask.commit and -PchangedProjectsTask.prevCommit are now branch names and will be used like the following git diff --name-only prev curr, where curr is -PchangedProjectsTask.commit)
  • branchTwoDotted (-PchangedProjectsTask.commit and -PchangedProjectsTask.prevCommit are branch names and will be used like the following git diff --name-only prev..curr)
  • branchThreeDotted (-PchangedProjectsTask.commit and -PchangedProjectsTask.prevCommit are branch names and will be used like the following git diff --name-only prev..curr)

If either -PchangedProjectsTask.commit and -PchangedProjectsTask.prevCommit is not specified when running the runTaskForChangedProjects command, then that option simply defaults to HEAD if it is allowed to by the logic, otherwise an error is thrown.

The following table illustrates the allowed and available options and how the resulting diff command looks

Example for evaluating the plugin

This is a basic example you can use to evaluate the plugin on your project, apply the following to your own root build.gradle.

plugins {
    id 'io.github.crimix.changed-projects-task' version 'VERSION'
}

allprojects {
    task print {
        doLast {
            println ">> " + project.path
        }
    }
}

changedProjectsTask {
    taskToRun = "print"
}

Then run the following Gradle command line
runTaskForChangedProjects -PchangedProjectsTask.run

This example will print the path of all the projects that is affected by some change and write Task x:print SKIPPED for those not affected.
You can use this to test how the plugin works and also set up the configuration of the plugin using real-world changes in your project.
This way to can skip running time-consuming task like test when you are just configuring the plugin.

Local Development

To develop and test locally with your own projects there are a few changes needed to be made.

1. First add the following to settings.gradle file in the root project

   pluginManagement {
   repositories {
     mavenLocal()
     gradlePluginPortal()
   }
   }
   buildscript {
   configurations.all {
     resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
   }
   }

2. Change the version inside of build.gradle in ChangedProjectsTaskPlugin to be x.y-SNAPSHOT
3. Change the plugin version used in your project to be x.y-SNAPSHOT
4. Do a refresh / sync of Gradle

Local debugging

To debug the plugin on your project, first checkout the repo and set breakpoints. Then you start the project task as the following in your project ./gradlew runTaskForChangedProjects -PchangedProjectsTask.run -Dorg.gradle.debug=true --no-daemon

Then the Gradle task will wait for you to connect a debugger, this can be done using the GradleRemoteDebug run configuration from this repo.

FAQ

Dependent task execution stops on first failed

Normally Gradle uses a fail-fast approach except for the test task. This means that if a dependent task fails the build stops. Depending on the use case it can be preferable, but if this plugin is used to skip unit tests, the wanted behavior will probably to execute all test tasks.

The way to get the wanted behaviour is to run the task as the following

--continue runTaskForChangedProjects -PchangedProjectsTask.run

This caused Gradle to execute all tasks even if the fail and still report the build as failed when it is done. This way it is possible to run all dependent tasks and get all unit test results to present to the user.

Task '.run' not found in root project

If you encounter any issue running the commands with the -PchangedProjectsTask.run parameter, it might be because you are using PowerShell on Windows which needs double quotes around such parameters.

Why did I make this

I have for at least a month been looking for a plugin or way to do this in Gradle. I have found a few interesting articles and plugins/code snippets, but none that worked out-of-the-box or suited my needs.

Thus, I began to write it using plain Groovy and Gradle, but when I was nearly done I stopped and thought for a moment, because all the embedded filtering and logic could be removed and put into a configuration instead, such that others could use it. Leading to this plugin being created