feat(jgit): Add configurable timestamp formats with named patterns (#76)

gnodet · cstamas · web-flow · commit 74cd9adf721e · 2025-05-29T16:21:56.000+02:00
This reverts commit 12bd034. feat(jgit): add configurable timestamp formats with named patterns - Add support for configurable date formats via nisse.source.jgit.dateFormat - Support named patterns: git (default), iso8601, iso8601-offset, custom - Add nisse.source.jgit.dateFormat.pattern for custom patterns - ISO-8601 format automatically converts to UTC (e.g., 2025-05-22T11:23:54Z) - Robust error handling with fallback to default format - Backward compatible - existing behavior unchanged - Add comprehensive test coverage for all format options - Add complete Git configuration documentation Closes: timestamp format configuration request * Dump dateValue * Fix UT --------- Co-authored-by: Tamas Cservenak <tamas@cservenak.net>
diff --git a/GIT_CONFIGURATION.md b/GIT_CONFIGURATION.md
@@ -0,0 +1,165 @@
+# Git Configuration (JGit Source)
+
+The JGit property source provides Git repository information and supports dynamic version generation based on Git tags and commits. This document covers all configuration options and features.
+
+## Overview
+
+The JGit source (`jgit`) extracts information from the Git repository and provides the following properties:
+
+- `commit`: The SHA-1 hash of the latest commit
+- `date`: The commit date (configurable format)
+- `author`: The commit author information
+- `committer`: The commit committer information
+- `dynamicVersion`: Dynamically generated version based on Git tags (optional)
+
+## Basic Properties
+
+### Always Available Properties
+
+| Property | Description | Example |
+|----------|-------------|---------|
+| `commit` | Latest commit SHA-1 hash | `a1b2c3d4e5f6789012345678901234567890abcd` |
+| `date` | Commit timestamp | `Mon May 27 18:20:45 2024 +0200` (default format) |
+| `author` | Commit author | `John Doe <john.doe@example.com>` |
+| `committer` | Commit committer | `John Doe <john.doe@example.com>` |
+
+## Configuration Properties
+
+### Date Format Configuration
+
+#### `nisse.source.jgit.dateFormat`
+
+Controls the timestamp format for the `date` property.
+
+**Supported values:**
+
+- **`git`** (default): Traditional Git format
+  - Pattern: `EEE MMM dd HH:mm:ss yyyy Z`
+  - Example: `Mon May 27 18:20:45 2024 +0200`
+
+- **`iso8601`**: ISO-8601 format in UTC
+  - Pattern: `yyyy-MM-dd'T'HH:mm:ss'Z'`
+  - Example: `2024-05-27T16:20:45Z`
+  - Note: Automatically converts to UTC timezone
+
+- **`iso8601-offset`**: ISO-8601 format with timezone offset
+  - Pattern: `yyyy-MM-dd'T'HH:mm:ssXXX`
+  - Example: `2024-05-27T18:20:45+02:00`
+
+- **`custom`**: Use custom pattern specified by `nisse.source.jgit.dateFormat.pattern`
+
+#### `nisse.source.jgit.dateFormat.pattern`
+
+Custom date format pattern when `dateFormat` is set to `custom`. Uses Java `DateTimeFormatter` syntax.
+
+**Examples:**
+- `yyyy/MM/dd HH:mm` → `2024/05/27 18:20`
+- `dd-MM-yyyy` → `27-05-2024`
+- `HH:mm:ss` → `18:20:45`
+
+### Dynamic Version Configuration
+
+#### `nisse.source.jgit.dynamicVersion`
+
+**Default:** `false`
+
+Set to `true` to enable dynamic version generation. When enabled, adds the `dynamicVersion` property.
+
+**Dynamic version logic:**
+1. Searches Git history for semantic version tags (e.g., `v1.2.3`, `1.2.3`)
+2. If current commit has a version tag, uses that version
+3. If current commit doesn't have a tag, increments patch version and adds build number
+4. Falls back to `0.0.1-{commitCount}` if no version tags found
+
+#### `nisse.source.jgit.appendSnapshot`
+
+**Default:** `true`
+
+Controls whether to append `-SNAPSHOT` qualifier to dynamic versions when the current commit is not tagged.
+
+**Examples:**
+- `true`: `1.2.4-5-SNAPSHOT` (5 commits since v1.2.3 tag)
+- `false`: `1.2.4-5` (no SNAPSHOT qualifier)
+
+#### `nisse.source.jgit.useVersion`
+
+Override dynamic version resolution with a specific version string.
+
+**Example:** `nisse.source.jgit.useVersion=2.0.0-BETA`
+
+## Version Tag Pattern
+
+The JGit source recognizes semantic version tags matching the pattern:
+- `refs/tags/v?((\\d+\\.\\d+\\.\\d+)(.*))`
+- Supports optional `v` prefix: `v1.2.3` or `1.2.3`
+- Supports additional qualifiers: `1.2.3-alpha`, `v2.0.0-RC1`
+
+## Usage Examples
+
+### Maven Command Line
+
+```bash
+# Enable dynamic versioning with ISO-8601 timestamps
+mvn compile -Dnisse.source.jgit.dynamicVersion=true -Dnisse.source.jgit.dateFormat=iso8601
+
+# Use custom date format
+mvn compile -Dnisse.source.jgit.dateFormat=custom -Dnisse.source.jgit.dateFormat.pattern="yyyy/MM/dd HH:mm"
+
+# Override version and disable SNAPSHOT
+mvn compile -Dnisse.source.jgit.useVersion=1.0.0 -Dnisse.source.jgit.appendSnapshot=false
+```
+
+### Maven Properties
+
+```xml
+<properties>
+    <nisse.source.jgit.dynamicVersion>true</nisse.source.jgit.dynamicVersion>
+    <nisse.source.jgit.dateFormat>iso8601</nisse.source.jgit.dateFormat>
+    <nisse.source.jgit.appendSnapshot>false</nisse.source.jgit.appendSnapshot>
+</properties>
+```
+
+### System Properties
+
+```java
+System.setProperty("nisse.source.jgit.dynamicVersion", "true");
+System.setProperty("nisse.source.jgit.dateFormat", "iso8601");
+```
+
+## Error Handling
+
+- **Invalid date format**: Falls back to default `git` format with warning
+- **Invalid custom pattern**: Falls back to default `git` format with warning
+- **No Git repository**: Source is ignored (logged at debug level)
+- **Git errors**: Logged and may cause build failure depending on configuration
+
+## Complete Example
+
+```xml
+<properties>
+    <!-- Enable all JGit features -->
+    <nisse.source.jgit.dynamicVersion>true</nisse.source.jgit.dynamicVersion>
+    <nisse.source.jgit.appendSnapshot>true</nisse.source.jgit.appendSnapshot>
+    <nisse.source.jgit.dateFormat>iso8601</nisse.source.jgit.dateFormat>
+</properties>
+```
+
+This configuration provides:
+- `nisse.jgit.commit`: Latest commit hash
+- `nisse.jgit.date`: ISO-8601 formatted timestamp in UTC
+- `nisse.jgit.author`: Commit author
+- `nisse.jgit.committer`: Commit committer  
+- `nisse.jgit.dynamicVersion`: Semantic version with SNAPSHOT qualifier
+
+## Integration with Maven
+
+The JGit properties can be used in Maven builds:
+
+```xml
+<version>${nisse.jgit.dynamicVersion}</version>
+
+<properties>
+    <build.timestamp>${nisse.jgit.date}</build.timestamp>
+    <build.commit>${nisse.jgit.commit}</build.commit>
+</properties>
+```
diff --git a/sources/jgit-source/src/main/java/eu/maveniverse/maven/nisse/source/jgit/JGitPropertySource.java b/sources/jgit-source/src/main/java/eu/maveniverse/maven/nisse/source/jgit/JGitPropertySource.java
@@ -10,7 +10,6 @@
 import eu.maveniverse.maven.nisse.core.NisseConfiguration;
 import eu.maveniverse.maven.nisse.core.PropertySource;
 import java.time.Instant;
-import java.time.ZoneId;
 import java.time.ZonedDateTime;
 import java.time.format.DateTimeFormatter;
 import java.util.Collections;
@@ -52,8 +51,6 @@ public class JGitPropertySource implements PropertySource {
 
     private static final String JGIT_DATE = "date";
 
-    private static final String JGIT_DATE_ISO_8601 = "dateIso8601";
-
     private static final String JGIT_AUTHOR = "author";
 
     private static final String JGIT_COMMITTER = "committer";
@@ -83,6 +80,22 @@ public class JGitPropertySource implements PropertySource {
      */
     private static final String JGIT_CONF_SYSTEM_PROPERTY_USE_VERSION = "nisse.source.jgit.useVersion";
 
+    /**
+     * Configure the timestamp format for the date property. Supports named patterns:
+     * - "git" (default): EEE MMM dd HH:mm:ss yyyy Z
+     * - "iso8601": yyyy-MM-dd'T'HH:mm:ss'Z' (UTC)
+     * - "iso8601-offset": yyyy-MM-dd'T'HH:mm:ssXXX (with timezone offset)
+     * - "custom": use the pattern specified in nisse.source.jgit.dateFormat.pattern
+     */
+    private static final String JGIT_CONF_SYSTEM_PROPERTY_DATE_FORMAT = "nisse.source.jgit.dateFormat";
+
+    /**
+     * Custom date format pattern when dateFormat is set to "custom".
+     */
+    private static final String JGIT_CONF_SYSTEM_PROPERTY_DATE_FORMAT_PATTERN = "nisse.source.jgit.dateFormat.pattern";
+
+    private static final String DEFAULT_DATE_FORMAT = "git";
+
     /**
      * Pattern for standard semantic versions, with an optional {@code "v"} prefix.
      */
@@ -115,20 +128,7 @@ public Map<String, String> getProperties(NisseConfiguration configuration) {
                 RevCommit lastCommit = getLastCommit(repository);
 
                 result.put(JGIT_COMMIT, lastCommit.getName());
-                Instant commitTime = Instant.ofEpochSecond(lastCommit.getCommitTime());
-                result.put(
-                        JGIT_DATE,
-                        ZonedDateTime.ofInstant(
-                                        commitTime,
-                                        lastCommit
-                                                .getAuthorIdent()
-                                                .getTimeZone()
-                                                .toZoneId())
-                                .format(DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss yyyy Z")));
-                result.put(
-                        JGIT_DATE_ISO_8601,
-                        ZonedDateTime.ofInstant(commitTime, ZoneId.of("UTC"))
-                                .format(DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssX")));
+                result.put(JGIT_DATE, formatCommitDate(configuration, lastCommit));
                 result.put(
                         JGIT_COMMITTER,
                         lastCommit.getCommitterIdent().toExternalString().split(">")[0] + ">");
@@ -154,6 +154,76 @@ private RevCommit getLastCommit(Repository repository) throws NoHeadException, G
         return Git.wrap(repository).log().setMaxCount(1).call().iterator().next();
     }
 
+    /**
+     * Formats the commit date according to the configured format.
+     *
+     * @param configuration the Nisse configuration
+     * @param commit the commit to format the date for
+     * @return the formatted date string
+     */
+    private String formatCommitDate(NisseConfiguration configuration, RevCommit commit) {
+        DateTimeFormatter formatter = resolveDateTimeFormatter(configuration);
+        String dateFormat = configuration
+                .getConfiguration()
+                .getOrDefault(JGIT_CONF_SYSTEM_PROPERTY_DATE_FORMAT, DEFAULT_DATE_FORMAT);
+
+        ZonedDateTime commitDateTime = ZonedDateTime.ofInstant(
+                Instant.ofEpochSecond(commit.getCommitTime()),
+                commit.getAuthorIdent().getTimeZone().toZoneId());
+
+        // For ISO-8601 format, convert to UTC
+        if ("iso8601".equalsIgnoreCase(dateFormat)) {
+            commitDateTime = commitDateTime.withZoneSameInstant(java.time.ZoneOffset.UTC);
+        }
+
+        return commitDateTime.format(formatter);
+    }
+
+    /**
+     * Resolves the DateTimeFormatter based on the configuration.
+     *
+     * @param configuration the Nisse configuration
+     * @return the configured DateTimeFormatter
+     */
+    private DateTimeFormatter resolveDateTimeFormatter(NisseConfiguration configuration) {
+        String dateFormat = configuration
+                .getConfiguration()
+                .getOrDefault(JGIT_CONF_SYSTEM_PROPERTY_DATE_FORMAT, DEFAULT_DATE_FORMAT);
+
+        switch (dateFormat.toLowerCase()) {
+            case "git":
+                return DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss yyyy Z");
+            case "iso8601":
+                return DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss'Z'");
+            case "iso8601-offset":
+                return DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssXXX");
+            case "custom":
+                String customPattern =
+                        configuration.getConfiguration().get(JGIT_CONF_SYSTEM_PROPERTY_DATE_FORMAT_PATTERN);
+                if (customPattern != null && !customPattern.trim().isEmpty()) {
+                    try {
+                        return DateTimeFormatter.ofPattern(customPattern);
+                    } catch (IllegalArgumentException e) {
+                        logger.warn(
+                                "Invalid custom date format pattern '{}', falling back to default 'git' format",
+                                customPattern,
+                                e);
+                        return DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss yyyy Z");
+                    }
+                } else {
+                    logger.warn(
+                            "Custom date format specified but no pattern provided via '{}', falling back to default 'git' format",
+                            JGIT_CONF_SYSTEM_PROPERTY_DATE_FORMAT_PATTERN);
+                    return DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss yyyy Z");
+                }
+            default:
+                logger.warn(
+                        "Unknown date format '{}', falling back to default 'git' format. Supported formats: git, iso8601, iso8601-offset, custom",
+                        dateFormat);
+                return DateTimeFormatter.ofPattern("EEE MMM dd HH:mm:ss yyyy Z");
+        }
+    }
+
     public String resolveDynamicVersion(NisseConfiguration configuration, Repository repository) throws Exception {
         VersionInformation vi;
 
diff --git a/sources/jgit-source/src/test/java/eu/maveniverse/maven/nisse/source/jgit/JGitPropertySourceTest.java b/sources/jgit-source/src/test/java/eu/maveniverse/maven/nisse/source/jgit/JGitPropertySourceTest.java
