JarCastingPartial Build Plugin
A maven plugin for partially building multi-module projects based on changes in the Git repository.
Partial Build Plugin allows to build (or test) only the sub-set of modules impacted by the changes between the base (current) branch and a reference branch. Additionally it writes the list of impacted projects into files and/or maven properties to be exploited later in the build workflow.
Partial Build Plugin can be integrated into different kinds of development workflows, whether feature branching, promiscuous branching or trunk-based development.
Disclosure : This plugin is forked and based on the project gitflow-incremental-builder by Vaclav Kosar.
Usage
Partial Build Plugin leverages Maven build extensions to modify the projects to be build. So be sure to add <extensions>true</extensions> in the plugin definition to enable the partial build.
<build>
<plugins>
<plugin>
<groupId>com.lesfurets</groupId>
<artifactId>partial-build-plugin</artifactId>
<version>VERSION</version>
<extensions>true</extensions>
<configuration>
<referenceBranch>refs/remotes/origin/master</referenceBranch>
...
</configuration>
</plugin>
</plugins>
</build>
If you are only interested to include the information on changed projects into your build lifecycle, you can use the goal called writeChanged without the build extension. This will write the list of changed projects into the output file.
Default phase : Validate
<build>
<plugins>
<plugin>
<groupId>com.lesfurets</groupId>
<artifactId>partial-build-plugin</artifactId>
<version>VERSION</version>
<executions>
<execution>
<id>changed</id>
<goals>
<goal>writeChanged</goal>
</goals>
<configuration>
<outputFile>${project.build.directory}/changed.projects</outputFile>
...
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
Configuration
In the configuration of the plugin
<build>
<plugins>
<plugin>
<groupId>com.lesfurets</groupId>
<artifactId>partial-build-plugin</artifactId>
<version>VERSION</version>
<extensions>true</extensions>
<configuration>
<referenceBranch>refs/remote/heads/master</referenceBranch>
<buildAll>true</buildAll>
<skipTestsForNotImpactedModules>true</skipTestsForNotImpactedModules>
<ignoreChanged>
com.lesfurets:some-project,
com.lesfurets:other-project
</ignoreChanged>
</configuration>
</plugin>
</plugins>
</build>
Through Maven properties
<properties>
<partial.referenceBranch>HEAD~2</partial.referenceBranch>
<partial.baseBranch>HEAD</partial.baseBranch>
<partial.uncommited>true</partial.uncommited>
<partial.untracked>false</partial.untracked>
<partial.buildAll>false</partial.buildAll>
<partial.outputFile>changed.projects</partial.outputFile>
<partial.writeChanged>false</partial.writeChanged>
</properties>
Through User properties
mvn clean install -Dpartial.uncommited=true -Dpartial.referenceBranch=HEAD
Through System properties
export partial.referenceBranch=origin/master
export partial.outputFile=changed.modules
mvn clean install
Configuration order
User properties override system properties overrides plugin configuration, overrides maven properties.
Configuration parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enabled | No | TRUE | Whether the partial plugin is enabled completely or not |
| repositorySshKey | No | empty | Ssh key used for fetching branches if configured |
| referenceBranch | No | refs/remotes/origin/develop | 'To' end of branch comparison. Branch name or refspec |
| baseBranch | No | HEAD | 'From' end of branch comparison. Checked out if different from HEAD |
| uncommited | No | TRUE | Whether to include uncommited changes in branch difference |
| untracked | No | FALSE | Whether to include untracked file changes in branch difference |
| skipTestsForNotImpactedModules | No | FALSE | Used with buildAll to true, skips tests for modules not impacted modules |
| buildAll | No | FALSE | Whether to build all modules or just the changed |
| compareToMergeBase | No | TRUE | Compare base branch to its merge base with reference branch |
| fetchBaseBranch | No | FALSE | Fetch base branch before execution |
| fetchReferenceBranch | No | FALSE | Fetch reference branch before execution |
| outputFile | No | ${project.basedir}/changed.properties | Path of the file to write the changed projects output |
| writeChanged | No | TRUE | Whether to write or not the changed projects output |
| ignoreChanged | No | empty | Comma separated pattern of project Id's to ignore from changed project calculation. Ex. com.acme:* ignores changes from all projects with group Id com.acme. These projects are included in the build if they are considered in the default maven build. |
| buildAnyways | No | empty | Comma separated pattern of project Id's to add to build, whether these projects are changed or not. Difference from ignoreChanged is that these projects are used to calculate impacted project calculation. |
| buildSnapshotDependencies | No | FALSE | Builds all dependencies that are in SNAPSHOT versions. This is necessary if you are using partial build on a reactor where multiple SNAPSHOT projects depend on each other. |
| ignoreAllReactorProjects | No | FALSE | Ignore reactor projects (pom packaging with modules). Reactor projects are included in the build whether they are changed or not. |
| impacted | No | TRUE | Disables whether the partial build includes also projects impacted by changed projects. |
| useNativeGit | No | FALSE | Use Native Git commands instead of JGit for detecting changed files. It should also cut down the build bootstrap by a couple of seconds |
Getting Started
Let's illustrate the working principle of the plugin with a simple use case. Here we have a simple multi-module project, versioned in Git :
- reactor
- child1
- child2
- grandchild1
- grandchild2
- child3
- child4
If we build this project on reactor root we would see the following.
mvn validate -Dpartial.enabled=false
[INFO] Scanning for projects...
[INFO] Partial build disabled...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] parent
[INFO] child1
[INFO] child2
[INFO] grandchild1
[INFO] grandchild2
[INFO] child3
[INFO] child4
[INFO]
[INFO] ---------------------
So far so good. Maven reactor aggregated all projects and constructed the standard build order. Let's make some changes in modules child3 and child4 and commit those.
touch child3/file
touch child4/file
git commit --all -m 'modify child3 and child4'
Now we activate the partial build and tell it to take into account only changes in the last commit.
mvn validate -Dpartial.enabled=true -Dpartial.referenceBranch=HEAD~1 -Dpartial.baseBranch=HEAD
[INFO] Scanning for projects...
[INFO] Starting Partial build...
[INFO] Git root is: /Users/ogunalp/dev/partial-test/.git
[INFO] Head of branch HEAD is commit of id: commit 94bcac65da63a8578fbec2b241edc7f122219c5d 1470907753 -----p
[INFO] Head of branch HEAD~1 is commit of id: commit eebfc84bed00343ab2c4dd203b1c26e7771d8f6b 1470907544 -----p
[INFO] Using merge base of id: commit eebfc84bed00343ab2c4dd203b1c26e7771d8f6b 1470907544 -tr-sp
[INFO] ------------------------------------------------------------------------
[INFO] Changed Projects:
[INFO]
[INFO] child4
[INFO] child3
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] child3
[INFO] child4
[INFO]
Here the plugin only included changed projects in the build session and omitted the others. It also listed changed projets in the file changed.projets :
com.test:child3:1.0-SNAPSHOT
com.test:child4:1.0-SNAPSHOT
This case was overly simplistic. The plugin does more than that. It follows dependencies between projects to calculate projects to build. It can be used in complex build configurations and integrated in your build and release lifecycle.
Try it out, tell us what you think.
Known Issues
--resume-frombuilds are not supported yet.- Changed projects console dump is not ordered.
- JGit currently does not support git worktree's (see https://git.eclipse.org/r/#/q/topic:worktree),
useNativeGitoption can be used to work in worktrees.
Requirements
- Maven version 3+.
