https://github.com/pretsadev/scm-version-maven-extension
Maven 4 extension to manage project version from scm
https://github.com/pretsadev/scm-version-maven-extension
git java maven maven-4 project project-version revision scm scm-version version
Last synced: 4 months ago
JSON representation
Maven 4 extension to manage project version from scm
- Host: GitHub
- URL: https://github.com/pretsadev/scm-version-maven-extension
- Owner: pretsadev
- License: apache-2.0
- Created: 2025-05-03T16:19:39.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-09T17:40:24.000Z (10 months ago)
- Last Synced: 2025-08-09T18:26:15.923Z (10 months ago)
- Topics: git, java, maven, maven-4, project, project-version, revision, scm, scm-version, version
- Language: Java
- Homepage:
- Size: 40 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SCM Version Maven Extension
A maven 4 extension to manage the project version from SCM (GIT) in a simple way
[](https://central.sonatype.com/artifact/dev.pretsa/scm-version-maven-extension)
[](https://github.com/pretsadev/scm-version-maven-extension/actions/workflows/snapshot.yml)
[](https://sonarcloud.io/summary/new_code?id=pretsadev_scm-version-maven-extension)
[](https://sonarcloud.io/summary/new_code?id=pretsadev_scm-version-maven-extension)
[](https://sonarcloud.io/summary/new_code?id=pretsadev_scm-version-maven-extension)
[](https://sonarcloud.io/summary/new_code?id=pretsadev_scm-version-maven-extension)
[](https://sonarcloud.io/summary/new_code?id=pretsadev_scm-version-maven-extension)
# What is it for?
- Tracking the project version from SCM (GIT) instead of explicitly being written in POMs.
- `scm-version-maven-extension` does only one thing, compute the version and set it to `scm.version` property.
- `scm-version-maven-extension` is intended to be simple if it does not meet your requirements please check these awesome projects
- [Maveniverse Nisse](https://github.com/maveniverse/nisse)
- [jgitver-maven-plugin](https://github.com/jgitver/jgitver-maven-plugin)
- [maven-git-versioning-extension](https://github.com/qoomon/maven-git-versioning-extension)
- [ci-friendly-flatten-maven-plugin](https://github.com/outbrain-inc/ci-friendly-flatten-maven-plugin)
> [!IMPORTANT]
> `scm-version-maven-extension` **only** resolves and sets the version during maven execution, it does not create new scm tags locally or remotely
> [!TIP]
> [JReleaser](https://jreleaser.org) is an excellent tool to create scm tags and manage releases
# Setup
> [!IMPORTANT]
> This extension only works with Maven 4
```mermaid
sequenceDiagram
autonumber
actor User
User->>.mvn/extensions.xml: Add `scm-version-maven-extension`
User->>pom.xml: Set version as `scm.version` property
User->>+Maven: Use maven as usual
Maven-->>+scm-version-maven-extension: Loads extension
scm-version-maven-extension-->>-Maven: Compute version from Git and populate `scm.version` property
Maven->>-User: Version is present
```
1. `scm-version-maven-extension` is a core extension, to be used it must be registered by adding it into `.mvn/extensions.xml` file
```xml
dev.pretsa
scm-version-maven-extension
VERSION
```
2. Project version must be set to `scm.version` on POM
```xml
4.1.0
com.example
my-app
${scm.version}
```
3. Use maven as usual, `scm-version-maven-extension` will resolve `scm.version` property to the desired version on each run
```
[INFO] scm-version-maven-extension loaded
[INFO] scm.version property computed to [1.2.4-SNAPSHOT] as the [NEXT PATCH SNAPSHOT]
```
4. Debug level logging can be enabled to get more information by passing `-Dmaven.logger.log.dev.pretsa=debug` to maven
```
[INFO] scm-version-maven-extension loaded
[DEBUG] Working directory is /project/path
[DEBUG] No user defined property for version type, value set to NEXT
[DEBUG] No user defined property for next version component, value set to PATCH
[DEBUG] No user defined property for version qualifier, value set to SNAPSHOT
[INFO] scm.version property computed to [1.2.4-SNAPSHOT] as the [NEXT PATCH SNAPSHOT]
```
# Configurations
To keep it simple `scm-version-maven-extension` assumes that
- The project version is in [Semantic Version](https://semver.org/) style (MAJOR.MINOR.PATCH) .e.g. `1.2.3`
- The project version has only two variants
- RELEASE which has no suffix e.g. `1.2.3`
- SNAPSHOT which has `-SNAPSHOT` suffix e.g. `1.2.3-SNAPSHOT`
- `scm-version-maven-extension` works with both annotated and lightweight Git tags
## `scm-version-maven-extension` has three main options that can be combined to get the desired behavior
### 1. Version type: This tells `scm-version-maven-extension` what version to compute
> [!NOTE]
> Defaults to `NEXT` if no option is supplied
| Version type | Activate with | Description |
|--------------|---------------|-----------------------|
| CURRENT | scm.current | The *current* version |
| NEXT | scm.next | The *next* version |
### 2. Next version component: When the version type is NEXT, this tell `scm-version-maven-extension` what version component to increment
> [!NOTE]
> Defaults to `PATCH` if no option is supplied
| Version type | Activate with | Description |
|--------------|---------------|---------------------------------------------|
| PATCH | scm.patch | The patch component e.g. `1.2.3` -> `1.2.4` |
| MINOR | scm.minor | The minor component e.g. `1.2.3` -> `1.3.0` |
| MAJOR | scm.major | The major component e.g. `1.2.3` -> `2.0.0` |
### 3. Version qualifier (variant): This tells `scm-version-maven-extension` what variant to compute
> [!NOTE]
> Defaults to `SNAPSHOT` if no option is supplied
| Version type | Activate with | Description |
|--------------|---------------|--------------------------------------------------------------------------|
| RELEASE | scm.release | Will compute the version without any suffix e.g. `1.2.3` |
| SNAPSHOT | scm.snapshot | Will compute the version adding `-SNAPSHOT` suffix e.g. `1.2.3-SNAPSHOT` |
## Shorthand options
> [!TIP]
> Shorthand options are available for easier usage
| Shorthand option | Equivalent options |
|-------------------------|-------------------------------------|
| scm.next.patch.release | scm.next + scm.patch + scm.release |
| scm.next.minor.release | scm.next + scm.minor + scm.release |
| scm.next.major.release | scm.next + scm.major + scm.release |
| scm.next.patch.snapshot | scm.next + scm.patch + scm.snapshot |
| scm.next.minor.snapshot | scm.next + scm.minor + scm.snapshot |
| scm.next.major.snapshot | scm.next + scm.major + scm.snapshot |
## Example
With that in mind, having a Git repository with the illustrated structure.
```mermaid
gitGraph
commit id: "C1"
commit id: "C2" tag: "1.2.3"
commit id: "C3"
commit id: "C4"
```
- Current release version will compute the version to `1.2.3`
```
mvn verify -Dscm.current -Dscm.release
```
- Current snapshot version will compute the version to `1.2.3-SNAPSHOT`
```
mvn verify -Dscm.current -Dscm.snapshot
```
- Next patch snapshot version will compute the version to `1.2.4-SNAPSHOT`
```
mvn verify -Dscm.next -Dscm.patch -Dscm.snapshot
```
- Next patch snapshot version (shorthand) will compute the version to `1.2.4-SNAPSHOT`
```
mvn verify -Dscm.next.patch.snapshot
```
- Next patch release version will compute the version to `1.2.4`
```
mvn verify -Dscm.next.patch.release
```
- Next patch release version (shorthand) will compute the version to `1.2.4`
```
mvn verify -Dscm.next.patch.release
```
- Next minor release version will compute the version to `1.3.0`
```
mvn verify -Dscm.next -Dscm.minor -Dscm.release
```
- Next minor release version (shorthand) will compute the version to `1.3.0`
```
mvn verify -Dscm.next.minor.release
```
# Common warnings
> [!NOTE]
> When `scm-version-maven-extension` is not able to load the current project version from scm, a default version of `0.0.0` is assumed and a warning is logged.
- Project path is not a valid git repository
```
[WARNING] Error loading tag at /project/path: One of setGitDir or setWorkTree must be called.
```
- Project repository does not have any commits yet
```
[WARNING] Error loading tag at /project/path: Ref HEAD cannot be resolved
```
- Project git repository does not contain any tags matching a semantic version pattern
```
[WARNING] Error loading tag at /project/path: No git tag matching supported glob [*[0-9]*.[0-9]*.[0-9]*]
```