Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aleksandr-m/gitflow-maven-plugin
The Git-Flow Maven Plugin supports various Git workflows, including GitFlow and GitHub Flow. This plugin runs Git and Maven commands from the command line.
https://github.com/aleksandr-m/gitflow-maven-plugin
git git-workflows gitflow github-flow java maven maven-plugin
Last synced: 1 day ago
JSON representation
The Git-Flow Maven Plugin supports various Git workflows, including GitFlow and GitHub Flow. This plugin runs Git and Maven commands from the command line.
- Host: GitHub
- URL: https://github.com/aleksandr-m/gitflow-maven-plugin
- Owner: aleksandr-m
- License: apache-2.0
- Created: 2014-04-29T18:35:29.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-06-21T13:02:44.000Z (6 months ago)
- Last Synced: 2024-12-14T02:04:49.128Z (8 days ago)
- Topics: git, git-workflows, gitflow, github-flow, java, maven, maven-plugin
- Language: Java
- Homepage: https://aleksandr-m.github.io/gitflow-maven-plugin/
- Size: 1.67 MB
- Stars: 498
- Watchers: 24
- Forks: 182
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Git-Flow Maven Plugin
[](https://github.com/aleksandr-m/gitflow-maven-plugin/actions)
[](https://maven-badges.herokuapp.com/maven-central/com.amashchenko.maven.plugin/gitflow-maven-plugin/)
[](https://www.apache.org/licenses/LICENSE-2.0.html)
The Maven plugin that supports various Git workflows, including Vincent Driessen's [successful Git branching model](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub Flow](https://guides.github.com/introduction/flow/).
Currently a Java implementation of Git version control system [JGit](https://eclipse.dev/jgit/) doesn't support [`.gitattributes`](https://git-scm.com/book/en/Customizing-Git-Git-Attributes).
This plugin runs Git and Maven commands from the command line ensuring that all Git features work properly.
## Changelog
See what's changed - [CHANGELOG](CHANGELOG.md)
# Installation
The plugin is available from Maven Central.
com.amashchenko.maven.plugin
gitflow-maven-plugin
1.21.0
# Goals Overview
- `gitflow:release-start` - Starts a release branch and updates version(s) to release version.
- `gitflow:release-finish` - Merges a release branch and updates version(s) to next development version.
- `gitflow:release` - Releases project w/o creating a release branch.
- `gitflow:feature-start` - Starts a feature branch and optionally updates version(s).
- `gitflow:feature-finish` - Merges a feature branch.
- `gitflow:hotfix-start` - Starts a hotfix branch and updates version(s) to hotfix version.
- `gitflow:hotfix-finish` - Merges a hotfix branch.
- `gitflow:support-start` - Starts a support branch from the production tag.
- `gitflow:version-update` - Updates version in release or support branch, optionally tagging and pushing it to the remote repository.
- `gitflow:help` - Displays help information.
# Git Workflows
The gitflow-maven-plugin is very versatile. It can be easily configured to use different Git workflows.
## GitHub Flow
The GitHub Flow is a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly.
To configure this plugin to use single branch model, such as GitHub Flow, just set the `developmentBranch` parameter to the same value as the `productionBranch` in your pom.xml file.
master
That's it!
# Maven Wrapper support
The plugin will automatically use Maven Wrapper for internal Maven goals if plugin is started with the wrapper.
# Internal Maven plugins
The `versions-maven-plugin` and `tycho-versions-plugin` are used internally to update versions and properties of the project. To change versions of internal plugins use `versionsMavenPluginVersion` and `tychoVersionsPluginVersion` properties respectively.
### Handling multi-module projects
If your project consists of multiple modules with and without parent-child relationships, you have to supply additional arguments if you want to update all module versions. In case of the `versions-maven-plugin`, there is [`processAllModules`](https://www.mojohaus.org/versions-maven-plugin/set-mojo.html#processAllModules), which can be supplied as follows:
```
mvn gitflow: -DargLine='-DprocessAllModules'
```
# Git Submodules
The plugin looks for the `.gitmodules` file and if it exists the `git submodule update` command will be executed before each Git commit. This is needed to avoid leaving working copy in dirty state which can happen when switching between branches.
To explicitly control whether Git submodules will be updated before commit the `updateGitSubmodules` parameter can be used. Setting it to `true` will enable Git submodules update and `false` will disable it even if `.gitmodules` file exists. The default value is not set, meaning the plugin tries to automatically determine if update is needed.
# Eclipse Plugins build with Tycho
Since version `1.1.0` this plugin supports Eclipse plugin projects which are build with [Tycho](https://eclipse.org/tycho/).
To enable this feature put `true` into `` section of this plugin in your pom.xml file.
### Features of `tychoBuild`
The [`tycho-versions-plugin`](https://eclipse.org/tycho/sitedocs/tycho-release/tycho-versions-plugin/plugin-info.html) Maven plugin will be used to set versions instead of [`versions-maven-plugin`](https://www.mojohaus.org/versions-maven-plugin/).
Feature name will not be appended to project version on `gitflow:feature-start` goal even if the `skipFeatureVersion` is set to `false`.
If version has qualifier then it will not be removed in the release or hotfix goals.
# Signing Your Work
To sign tags and/or commits you need to configure GPG and install personal key. Read more [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work).
Next you need to configure Git to use your personal key.
```
git config --global user.signingkey GPG_key_id
```
Sometimes you need to tell Git where the GPG program is. Use `gpg.program` option for that.
```
git config --global gpg.program "path_to_gpg"
```
### Signing Tags
The `gitflow:release`, `gitflow:release-finish` and `gitflow:hotfix-finish` goals have `gpgSignTag` parameter. Set it to `true` to sign tags with configured personal key. The default value is `false`.
### Signing Commits
All goals have `gpgSignCommit` parameter. Set it to `true` to sign commits with configured personal key. The default value is `false`.
# Support for Reproducible Builds
[Reproducible builds](https://reproducible-builds.org/) are a set of software development practices that create an independently-verifiable path from source to binary code.
To configure your Maven build to support reproducible builds follow [official guide](https://maven.apache.org/guides/mini/guide-reproducible-builds.html).
If your project has `project.build.outputTimestamp` property this plugin will update its value whenever the versions are updated.
This can be disabled by setting the configuration parameter `updateOutputTimestamp` to `false`.
# Plugin Common Parameters
All parameters are optional. The `gitFlowConfig` parameters defaults are the same as in the example below.
Maven and Git executables are assumed to be in the PATH, if executables are not available in the PATH or you want to use different version use `mvnExecutable` and `gitExecutable` parameters.
The `installProject` parameter controls whether the Maven `install` goal will be called during the mojo execution. The default value for this parameter is `false` (i.e. the project will NOT be installed).
Since `1.0.7` version of this plugin the output of the executed commands will NOT be printed into the console. This can be changed by setting `verbose` parameter to `true`.
path_to_maven_executable
path_to_git_executable
false
false
master
develop
feature/
release/
hotfix/
support/
origin
## Customizing commit messages
Since `1.2.1` commit messages can be changed in plugin's configuration section in pom.xml. Commit messages defaults are seen below.
Update versions for feature branch
Update versions for development branch
Update versions for hotfix
Update for next development version
Update to hotfix version
Update versions for release
Update for next development version
Update for next development version
Tag hotfix
Tag release
Tag version update
Update develop to production version to avoid merge conflicts
Update develop version back to pre-merge state
Update release to hotfix version to avoid merge conflicts
Update release version back to pre-merge state
Update feature branch back to feature version
Increment feature version
Update versions for support branch
Update versions
Maven properties can be used in commit messages. For example `updating ${project.artifactId} project for feature branch` will produce message where
`${project.artifactId}` will be substituted for projects ``.
Note that although `${project.version}` can be used, any changes to version introduced by this goal won't be reflected in a commit message for this goal (see Custom properties).
Commit messages can be prefixed by using `commitMessagePrefix` parameter. Leading or trailing whitespaces can be preserved by using `xml:space="preserve"` attribute e.g. `[gitflow] `.
### Custom properties in commit messages
`@{version}` will be replaced with the updated version.
`@{featureName}` will be replaced in `feature-` goals with the name of the current feature.
## Maven arguments
The `argLine` parameter can be used to pass command line arguments to the underlying Maven commands. For example, `-DcreateChecksum` in `mvn gitflow:release-start -DargLine=-DcreateChecksum`
will be passed to all underlying Maven commands.
## Maven CI friendly versions
Maven property can be updated with the new version by setting the `versionProperty` parameter with the property you want to update.
For example, `-DversionProperty=revision` will update the `` property defined in the project pom.xml.
The `skipUpdateVersion` parameter can be used to skip updating `` in the pom.xml. The default value is `false` (i.e. the version will be updated).
To support [CI friendly versioning](https://maven.apache.org/maven-ci-friendly.html) in projects which use `${revision}` set `versionProperty` to `revision` and `skipUpdateVersion` to `true`.
## Additional goal parameters
The `gitflow:release-finish`, `gitflow:release` and `gitflow:hotfix-finish` goals have `skipTag` parameter. This parameter controls whether the release/hotfix will be tagged in Git.
The default value is `false` (i.e. the release/hotfix will be tagged).
The `gitflow:feature-start` goal has `skipFeatureVersion` parameter which controls whether the feature name will be appended to the project version or not.
The default value is `false` (e.g. if the project version is `1.0.0-SNAPSHOT` and feature name is `feature_name` then after the execution it will be `1.0.0-feature_name-SNAPSHOT`).
The `gitflow:feature-start` goal has `featureNamePattern` parameter which allows to enforce naming of the feature branches with a regular expression. Doesn't have effect if it isn't set or left blank.
By default it isn't set.
The `gitflow:feature-finish` goal has `incrementVersionAtFinish` parameter which if set to `true` will increment version number during feature finish. The default is `false`.
All `-finish` goals have `keepBranch` parameter which controls whether created support branch will be kept in Git after the goal finishes.
The default value is `false` (i.e. the supporting branch will be deleted). If the `pushRemote` parameter is set to `true` and `keepBranch` is `false` remote branch will be deleted as well.
All `-finish` goals and `gitflow:release` have `skipTestProject` parameter which controls whether Maven `test` goal will be called before merging branches.
The default value is `false` (i.e. the project will be tested before merging branches).
All `release` goals have `allowSnapshots` parameter which controls whether SNAPSHOT dependencies are allowed. The default value is `false` (i.e. build fails if there SNAPSHOT dependency in project).
The `gitflow:release-start` and `gitflow:release-finish` have `commitDevelopmentVersionAtStart` parameter which controls whether the next development version is set and committed at start or after finish.
By default the value is `false` which means that the next development version is set on the development branch after the release branch has been merged onto the development branch when finishing the release.
This has the benefit of being able to easily cancel the release process simply by deleting the release branch.
If the value is `true` then versioning happens on `gitflow:release-start`. First the project version is set to the release version on the development branch and the release branch is created.
Then the development branch is set to the next development version.
This allows the development branch to continue immediately with a new version and helps avoid any future merge conflicts related to project versioning.
Has effect only when there are separate development and production branches.
The `gitflow:release-start` goal has `sameBranchName` parameter which can be used to use the same name for the release branch. The default value is `false`.
By itself the default `releaseBranchPrefix` is not a valid branch name. You must change it when setting `sameBranchName` to `true`.
Will have no effect if the `branchName` parameter is set.
The `gitflow:release-start` goal has `branchName` parameter which controls how the release branch will be named.
The `gitflow:release-start` goal has `fromCommit` parameter which allows to start the release from the specific commit (SHA).
The `gitflow:release-start` and `gitflow:release-finish` goals have `useSnapshotInRelease` parameter which allows to start the release with SNAPSHOT version and finish it without this value in project version. By default the value is `false`.
For example, if the release version is `1.0.2` and `useSnapshotInRelease` is set to `true` and using `gitflow:release-start` goal then the release version will be `1.0.2-SNAPSHOT` and when finishing the release with `gitflow:release-finish` goal, the release version will be `1.0.2`
The `gitflow:release` and `gitflow:release-finish` goals have `skipReleaseMergeProdBranch` parameter which prevents merging the release branch into the production branch. The default value is `false`.
The `gitflow:release-finish` goal has `skipReleaseMergeDevBranch` parameter which prevents merging the release branch into the development branch. The default value is `false`.
The `gitflow:hotfix-start` and `gitflow:hotfix-finish` goals have `useSnapshotInHotfix` parameter which allows to start the hotfix with SNAPSHOT version and finish it without this value in the version. By default the value is `false`.
For example, if the hotfix version is `1.0.2.1` and `useSnapshotInHotfix` is set to `true` and using `gitflow:hotfix-start` goal then the hotfix version will be `1.0.2.1-SNAPSHOT` and when finishing the release with `gitflow:hotfix-finish` goal, the release version will be `1.0.2.1`
The `gitflow:hotfix-finish` goal supports the parameter `skipMergeDevBranch` which prevents merging the hotfix branch into the development branch.
The `gitflow:hotfix-finish` goal supports the parameter `skipMergeProdBranch` which prevents merging the hotfix branch into the production branch and deletes the hotfix branch leaving only the tagged commit. Useful, along with `skipMergeDevBranch`, to allow hotfixes to very old code that are not applicable to current development.
The `gitflow:release-finish` and `gitflow:hotfix-finish` goals have `noBackMerge` and `noBackMergeHotfix` parameters respectively. They control which branch is merged to development branch. If set to `true` then release or hotfix branch will be merged to development branch. If set to `false` and tag is present (`skipTag` parameter is set to `false`) then tag will be merged. If there is no tag then production branch will be merged to development branch.
The `gitflow:release` goal has `noBackMerge` parameter, which controls which branch is merged to development branch. If set to `true` then merge will be skipped. If set to `false` and tag is present (`skipTag` is set to `false`) then tag will be merged. If there is no tag then production branch will be merged to development branch.
### Versioning
The `gitflow:release-finish` and `gitflow:release` goals have `digitsOnlyDevVersion` parameter which will remove qualifiers from the next development version if set to `true`.
For example, if the release version is `1.0.0-Final` then development version will be `1.0.1-SNAPSHOT`.
The default value is `false` (i.e. qualifiers will be preserved in next development version).
The `gitflow:release-finish` and `gitflow:release` goals have `versionDigitToIncrement` parameter which controls which digit to increment in the next development version. Starts from zero.
For example, if the release version is `1.2.3.4` and `versionDigitToIncrement` is set to `1` then the next development version will be `1.3.0.0-SNAPSHOT`.
If not set or set to not valid value defaults to increment last digit in the version.
The `gitflow:hotfix-start` goal has `hotfixVersionDigitToIncrement` parameter which controls which digit to increment in the hotfix version. Starts from zero.
Versioninig can be controlled by using [Maven version policy](https://maven.apache.org/maven-release/maven-release-api/apidocs/org/apache/maven/shared/release/policy/version/VersionPolicy.html) implementation. Create appropriate implementation and add it as dependency to the project, use `projectVersionPolicyId` parameter to set policy id to use. If policy is set then other parameters controlling the generation of version are ignored (i.e. `digitsOnlyDevVersion`, `versionDigitToIncrement`).
Version update of all modules ignoring groupId and artifactId can be forced by setting `versionsForceUpdate` parameter to `true`. The default value is `false`.
### Remote interaction
At the start of the each goal remote branch(es) will be fetched and compared with the local branch(es). If the local branch doesn't exist it will be checked out from the remote.
Both of these options can be turned off by setting `fetchRemote` parameter to `false`.
At the end of the `-finish` goals development or production and development branches will be pushed to remote. This can be turned off by setting `pushRemote` parameter to `false`.
At the end of the `-start` goals newly created branch (release / feature / hotfix) can be pushed to the remote. This can be achieved by setting `pushRemote` parameter to `true`.
The default remote name is `origin`. It can be customized with `custom_origin` configuration in pom.xml.
Git [push-options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) can be added to push command with the `gitPushOptions` parameter. Multiple options can be added separated with a space e.g. `-DgitPushOptions="merge_request.create merge_request.target=develop merge_request.label='Super feature'"`.
### Rebase, Merge, Fast Forward, Squash
Release branch can be rebased instead of merged by setting `releaseRebase` parameter to `true`. The default value is `false` (i.e. merge will be performed).
Release branch can be merged without `--no-ff` option by setting `releaseMergeNoFF` parameter to `false`. The default value is `true` (i.e. `merge --no-ff` will be performed).
The `releaseMergeNoFF` parameter has no effect when `releaseRebase` parameter is set to `true`.
Release branch can be merged with `--ff-only` option by setting `releaseMergeFFOnly` parameter to `true`. The default value is `false` (i.e. The `--ff-only` option won't be used).
Feature branch can be squashed before merging by setting `featureSquash` parameter to `true`. The default value is `false` (i.e. merge w/o squash will be performed).
### Running custom Maven goals
The `preFeatureFinishGoals` parameter can be used in `gitflow:feature-finish` goal to run defined Maven goals before the finishing and merging a feature.
E.g. `mvn gitflow:feature-finish -DpreFeatureFinishGoals=test` will run `mvn test` goal in the feature branch before merging into the development branch.
The `postFeatureFinishGoals` parameter can be used in `gitflow:feature-finish` goal to run defined Maven goals after merging a feature.
E.g. `mvn gitflow:feature-finish -postFeatureFinishGoals=test` will run `mvn test` goal in the development branch after merging a feature.
The `preReleaseGoals` parameter can be used in `gitflow:release-finish` and `gitflow:release` goals to run defined Maven goals before the release.
E.g. `mvn gitflow:release-finish -DpreReleaseGoals=test` will run `mvn test` goal in the release branch before merging into the production branch.
The `postReleaseGoals` parameter can be used in `gitflow:release-finish` and `gitflow:release` goals to run defined Maven goals after the release.
E.g. `mvn gitflow:release-finish -DpostReleaseGoals=deploy` will run `mvn deploy` goal in the production branch after the release.
The `gitflow:hotfix-finish` goal has `preHotfixGoals` and `postHotfixGoals` parameters which can be used to run defined Maven goals before and after the hotfix respectively.
# Non-interactive Mode
Maven can be run in non-interactive (batch) mode. By using non-interactive mode goals can be run in continuous integration environment.
To put Maven in the batch mode use `-B` or `--batch-mode` option.
## Non-interactive Release
Releases could be performed without prompting for the release version during `gitflow:release-start` or `gitflow:release` goals by telling Maven to run in non-interactive (batch) mode.
The `releaseVersion` parameter can be used to set the release version in non-interactive mode. If `releaseVersion` parameter is not set then the default release version will be used.
mvn -B gitflow:release-start gitflow:release-finish
To release w/o creating separate release branch use `gitflow:release` goal.
mvn -B gitflow:release
This gives the ability to perform releases in non-interactive mode (e.g. in CI server).
The `gitflow:release-finish` and `gitflow:release` goals have `developmentVersion` parameter which can be used to set the next development version in non-interactive mode.
## Non-interactive Feature
The `gitflow:feature-start` and `gitflow:feature-finish` goals have `featureName` parameter which can be used to set a name of the feature in non-interactive mode.
The `gitflow:feature-finish` goal has `featureBranch` parameter which can be used to set feature branch name in non-interactive mode. It must start with the feature branch prefix. The `featureBranch` will be used instead of `featureName` if both are set.
## Non-interactive Hotfix
The `gitflow:hotfix-start` goal has `fromBranch` parameter which can be used to set starting branch of the hotfix. It can be set to production branch or one of the support branches.
If it is left blank then hotfix will be started from the production branch.
The `gitflow:hotfix-start` and `gitflow:hotfix-finish` goals have `hotfixVersion` parameter which can be used to set version of the hotfix.
If it is left blank in `gitflow:hotfix-start` goal then the default version will be used.
The `gitflow:hotfix-finish` goal has `hotfixBranch` parameter which can be used to set hotfix branch name in non-interactive mode. It must start with the hotfix branch prefix. The `hotfixBranch` will be used instead of `hotfixVersion` if both are set.
## Non-interactive Support
The `gitflow:support-start` goal can be run in non-interactive mode. Use `tagName` parameter to set tag from which supporting branch will be started.
If `tagName` is not set but the goal is running in non-interactive mode then the last tag will be used.
The `gitflow:support-start` goal has `supportBranchName` parameter which can be used to set branch name to use instead of the default.
The `gitflow:support-start` goal has `useSnapshotInSupport` parameter which allows to start the support with SNAPSHOT version.