-
Notifications
You must be signed in to change notification settings - Fork 300
/
GitCommitIdMojo.java
1529 lines (1423 loc) · 61.1 KB
/
GitCommitIdMojo.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* This file is part of git-commit-id-maven-plugin
* Originally invented by Konrad 'ktoso' Malawski <[email protected]>
*
* git-commit-id-maven-plugin is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* git-commit-id-maven-plugin is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with git-commit-id-maven-plugin. If not, see <http://www.gnu.org/licenses/>.
*/
package pl.project13.maven.git;
import com.google.common.annotations.VisibleForTesting;
import java.io.File;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.text.SimpleDateFormat;
import java.time.Instant;
import java.util.Collections;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Properties;
import java.util.function.Supplier;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import org.apache.maven.execution.MavenSession;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecution;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.PluginParameterExpressionEvaluator;
import org.apache.maven.plugins.annotations.Component;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.project.MavenProject;
import org.apache.maven.settings.Settings;
import org.joda.time.DateTime;
import org.sonatype.plexus.build.incremental.BuildContext;
import pl.project13.core.CommitIdGenerationMode;
import pl.project13.core.CommitIdPropertiesOutputFormat;
import pl.project13.core.GitCommitIdExecutionException;
import pl.project13.core.GitCommitIdPlugin;
import pl.project13.core.PropertiesFileGenerator;
import pl.project13.core.git.GitDescribeConfig;
import pl.project13.core.log.LogInterface;
import pl.project13.core.util.BuildFileChangeListener;
/**
* Puts git build-time information into property files or maven's properties.
*
* @since 1.0
*/
@Mojo(name = "revision", defaultPhase = LifecyclePhase.INITIALIZE, threadSafe = true)
public class GitCommitIdMojo extends AbstractMojo {
private static final String CONTEXT_KEY = GitCommitIdMojo.class.getName() + ".properties";
// ===============================================================================================
// Parameter injected by maven itself can't be configured in the pom.xml!
/**
* This parameter can't be configured in the {@code pom.xml} it represents the Maven Project that
* will be injected by maven itself.
*/
@Parameter(defaultValue = "${project}", readonly = true, required = true)
MavenProject project;
/**
* This parameter can't be configured in the {@code pom.xml} it represents the list of projects in
* the reactor that will be injected by maven itself.
*/
@Parameter(defaultValue = "${reactorProjects}", readonly = true, required = true)
List<MavenProject> reactorProjects;
/**
* This parameter can't be configured in the {@code pom.xml} it represents the Mojo Execution that
* will be injected by maven itself.
*/
@Parameter(defaultValue = "${mojoExecution}", readonly = true, required = true)
MojoExecution mojoExecution;
/**
* This parameter can't be configured in the {@code pom.xml} it represents the Maven Session
* Object that will be injected by maven itself.
*/
@Parameter(defaultValue = "${session}", readonly = true, required = true)
MavenSession session;
/**
* This parameter can't be configured in the {@code pom.xml} it represents the Maven settings that
* will be injected by maven itself.
*/
@Parameter(defaultValue = "${settings}", readonly = true, required = true)
Settings settings;
// ===============================================================================================
// Parameters that can be configured in the pom.xml
/**
* Configuration to tell the git-commit-id-maven-plugin if the plugin should inject the git
* properties into all reactor projects not just the current one.
*
* <p>The property is set to {@code false} by default to prevent the overriding of properties that
* may be unrelated to the project. If you need to expose your git properties to another maven
* module (e.g. maven-antrun-plugin) you need to set it to {@code true}.
*
* <p>Inject git properties into all reactor projects, not just the current one may slow down the
* build and you don't always need this feature.
*
* <p>For details about why you might want to skip this, read this issue: <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/pull/65">pull #65</a>
*
* <p>Example:
*
* <pre>{@code
* <injectAllReactorProjects>false</injectAllReactorProjects>
* }</pre>
*
* @since 2.1.4
*/
@Parameter(defaultValue = "false")
boolean injectAllReactorProjects;
/**
* Configuration to tell the git-commit-id-maven-plugin to print some more verbose information
* during the build (e.g. a summary of all collected properties when it's done).
*
* <p>By default this option is disabled (set to {@code false})
*
* <p>Note, If enabled (set to {@code true}) the plugin may print information you deem sensible,
* so be extra cautious when you share those.
*
* <p>Example:
*
* <pre>{@code
* <verbose>false</verbose>
* }</pre>
*/
@Parameter(defaultValue = "false")
boolean verbose;
/**
* Configuration to tell the git-commit-id-maven-plugin to <b>not</b> run in a pom packaged
* project (e.g. {@code <packaging>pom</packaging>}).
*
* <p>By default 'pom' packaged projects will be skipped (to {@code true})
*
* <p>You may want to set this to {@code false}, if the plugin should also run inside a pom
* packaged project. Most projects won't need to override this property. For an use-case for this
* kind of behaviour see:
*
* <p><a href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/21">Issue 21</a>
*
* <p>Note: The plugin might not execute at all, if you also set {@code
* <runOnlyOnce>true</runOnlyOnce>}
*
* <p>Example:
*
* <pre>{@code
* <skipPoms>true</skipPoms>
* }</pre>
*/
@Parameter(defaultValue = "true")
boolean skipPoms;
/**
* Configuration to tell the git-commit-id-maven-plugin to generate a {@code 'git.properties'}
* file. By default the plugin will not <b>not</b> generate such a file (set to {@code false}),
* and only adds properties to maven project properties.
*
* <p>Set this to {@code 'true'} if you want an easy way to expose your git information into your
* final artifact (jar, war, ...), which will generate a properties file (with filled out values)
* that can be configured to end up in the final artifact. Refer to the configuration of {@link
* #generateGitPropertiesFilename}` that helps you setup that final path.
*
* <p>Such generated property file, can normally be read using during runtime.
*
* <pre>
* new Properties().load(...)
* </pre>
*
* <p>Note: When writing the {@code git.properties} file the value *git.build.time* will only be
* updated when things in the commit information have changed. If you only change a bit of your
* code and rebuild/rerun you will see an older timestamp that you may have expected. Essentially
* the functional meaning becomes **The latest build time when the git information was written to
* the git.properties file**. The reason why this was done can be found in [issue
* 151](https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/151).
*
* <p>Example:
*
* <pre>{@code
* <generateGitPropertiesFile>true</generateGitPropertiesFile>
* }</pre>
*/
@Parameter(defaultValue = "false")
boolean generateGitPropertiesFile;
/**
* Configuration to tell the git-commit-id-maven-plugin about the location where you want to
* generate a {@code 'git.properties'} file.
*
* <p>By default the file would be generated under {@code
* ${project.build.outputDirectory}/git.properties}, but you would need to set {@link
* #generateGitPropertiesFile} to {@code true} first to "activate" the generation of this file.
* You can also choose the format of the generated properties by specifying it under {@link
* #format}.
*
* <p>The path can be relative to {@code ${project.basedir}} (e.g. {@code
* target/classes/git.properties}) or can be a full path (e.g. {@code
* ${project.build.outputDirectory}/git.properties}).
*
* <p>Note: If you plan to set the generateGitPropertiesFilename-Path to a location where usually
* the source-files comes from (e.g. {@code src/main/resources}) and experience that your IDE
* (e.g. eclipse) invokes "Maven Project Builder" once every second, the chances that you are
* using an IDE where the src-folder is a watched folder for files that are <b>only</b> edited by
* humans is pretty high. <br>
* For further information refer to the manual for your specific IDE and check the workflow of
* "incremental project builders". <br>
* In order to fix this problem we recommend to set the generateGitPropertiesFilename-Path to a
* target folder (e.g. {@code ${project.build.outputDirectory}}) since this is the place where all
* derived/generated resources should go. <br>
* With plugin version 3.0.0 we introduced a smarter way to counter that issue, but that might not
* be supported by your IDE. See: <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/pull/385">pull 385</a> for
* further information
*
* <p>Example:
*
* <pre>{@code
* <generateGitPropertiesFilename>
* ${project.build.outputDirectory}/git.properties
* </generateGitPropertiesFilename>
* }</pre>
*/
@Parameter(defaultValue = "${project.build.outputDirectory}/git.properties")
String generateGitPropertiesFilename;
/**
* Controls whether special characters in the properties within the {@link
* #generateGitPropertiesFilename} should be unicode escaped. By default properties are escaped
* (e.g. \\u6E2C\\u8A66\\u4E2D\\u6587). If you write commit messages in chinese and want to
* extract the message without any additional conversion from the generated properties you may
* want to set this to {@code false}.
*
* <p>See <a href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/590">issue
* 590</a> for further details.
*
* <p>Example:
*
* <pre>{@code
* <generateGitPropertiesFileWithEscapedUnicode>
* true
* </generateGitPropertiesFileWithEscapedUnicode>
* }</pre>
*
* @since 6.0.0
*/
@Parameter(defaultValue = "true")
boolean generateGitPropertiesFileWithEscapedUnicode;
/**
* Configuration to tell the git-commit-id-maven-plugin about the root directory of the git
* repository we want to check. By default uses {@code ${project.basedir}/.git} will most probably
* be ok for single module projects, in other cases please use `../` to get higher up in the dir
* tree (e.g. {@code ${project.basedir}/../.git}).
*
* <p>Example:
*
* <pre>{@code
* <dotGitDirectory>
* ${project.basedir}/.git
* </dotGitDirectory>
* }</pre>
*/
@Parameter(defaultValue = "${project.basedir}/.git")
File dotGitDirectory;
/**
* Configuration for the {@code 'git-describe'} command. You can modify the dirty marker, abbrev
* length and other options here. The following `gitDescribe` configuration below is optional and
* can be leveraged as a really powerful versioning helper. If you are not familiar with <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin#git-describe---short-intro-to-an-awesome-command">git-describe</a>
* it is highly recommended to go through this part of the documentation.
*
* <p>More advanced users can most likely skip the explanations in this section, as it just
* explains the same options that git provides. As a side note this plugin tries to be 1-to-1
* compatible with git's plain output, even though the describe functionality has been
* reimplemented manually using JGit (you don't have to have a git executable to use the plugin).
*
* <p>For further information refer to <a href="https://git-scm.com/docs/git-describe">this</a>.
*
* <p>Example:
*
* <pre>{@code
* <gitDescribe>
* <!--
* Default (optional):
* false
*
* Explanation:
* When you don't want to use `git-describe` information in your build,
* you can set this to `true` to avoid to calculate it.
* -->
* <skip>false</skip>
*
* <!--
* Default (optional):
* true
*
* Explanation:
* In some cases no tag can be found `near` this commit
* (e.g. usually when performing a shallow clone).
* If this is set to `true` and no tag was found, this property will
* fallback to the commit's id instead
* (when `true` this property will not become empty).
* Set this to `true` when you *always* want to return something meaningful in the
* describe property.
* -->
* <always>true</always>
*
* <!--
* Default (optional):
* 7
*
* Explanation:
* In the describe output, the object id of the hash is always
* abbreviated to N letters (by default 7).
*
* The typical describe output you'll see therefore is: `v2.1.0-1-gf5cd254`,
* where `-1-` means the number of commits away from the mentioned tag and
* the `-gf5cd254` part means the first 7 chars of the current commit's id `f5cd254`.
* Setting *abbrev* to `0` has the effect of hiding the "distance from tag" and
* "object id" parts of the output, so you end up with just the "nearest tag"
* (that is, instead `tag-12-gaaaaaaa` with `abbrev = 0` you'd get `tag`).
*
* **Please note that the `g` prefix is included to notify you that it's a commit id,
* it is NOT part of the commit's object id** - *this is default git behaviour,
* so we're doing the same*.
*
* You can set this to any value between 0 and 40 (inclusive).
* `0` carries the special meaning
* (checkout the [git describe documentation](docs/git-describe.md) for the
* special case abbrev = 0).
* Maximum value is `40`, because of max SHA-1 length.
* -->
* <abbrev>7</abbrev>
*
* <!--
* Default (optional):
* -dirty
*
* Explanation:
* When you run describe on a repository that's in "dirty state" (has uncommitted
* changes), the describe output will contain an additional suffix, such as "-devel"
* in this example: `v3.5-3-g2222222-devel`. This configuration allows you to alter
* that additional suffix and gets appended to describe, while the repo is in
* "dirty state". You can configure that suffix to be anything you want, "-DEV" being
* a nice example. The "-" sign should be included in the configuration parameter,
* as it will not be added automatically.
* If in doubt run `git describe --dirty=-my_thing`
* to see how the end result will look like.
* -->
* <dirty>-dirty</dirty>
*
* <!--
* Default (optional):
* * (include all tags)
*
* Explanation:
* Git describe may contain information to tag names. Set this configuration to only
* consider tags matching the given pattern.
* This can be used to avoid leaking private tags from the repository.
* -->
* <match>*</match>
*
* <!--
* Default (optional):
* false
*
* Explanation:
* When you run git-describe it only looks only for *annotated tags* by default.
* If you wish to consider *lightweight tags* in your describe as well you would need
* to switch this to `true`.
*
* The difference between *annotated tags* and *lightweight tags* is outlined in more
* depth <a href="https://github.com/git-commit-id/git-commit-id-maven-plugin/#git-describe-and-a-small-gotcha-with-tags">here</a>
* -->
* <tags>false</tags>
*
* <!--
* Default (optional):
* false
*
* Explanation:
* git-describe, by default, returns the tag name, if the current commit is tagged.
* Set this option to `true` to force it to format the output using
* the typical describe format
* ("$tag_name-$commits_from_tag-g$commit_id-maybe_dirty"), even if "on" a tag.
*
* An example would be: `tagname-0-gc0ffebabe` - notice that the distance from
* the tag is 0 here, if you don't use **forceLongFormat** mode,
* the describe for such commit would look like this: `tagname`.
* -->
* <forceLongFormat>false</forceLongFormat>
* </gitDescribe>
* }
*
* </pre>
*
* @since 2.1.0
*/
@Parameter GitDescribeConfig gitDescribe;
/**
* Minimum length of {@code 'git.commit.id.abbrev'} property. Value must be from 2 to 40
* (inclusive), other values will result in an exception.
*
* <p>Defaults to `7`
*
* <p>An abbreviated commit is a shorter version of commit id. However, it is guaranteed to be
* unique. To keep this contract, the plugin may decide to print an abbreviated version that is
* longer than the value specified here.
*
* <p><b>Example:</b> You have a very big repository, yet you set this value to 2. It's very
* probable that you'll end up getting a 4 or 7 char long abbrev version of the commit id. If your
* repository, on the other hand, has just 4 commits, you'll probably get a 2 char long
* abbreviation.
*
* <p>Example:
*
* <pre>{@code
* <abbrevLength>7</abbrevLength>
* }</pre>
*
* @since 2.0.4
*/
@Parameter(defaultValue = "7")
int abbrevLength;
/**
* Denotes the format to save properties of the properties file that can be configured with {@link
* #generateGitPropertiesFilename}.
*
* <p>Valid options are encoded in {@link CommitIdPropertiesOutputFormat} and currently would
* allow "properties" (default) and "json". Future option like yml, toml, ... might be supported
* at some point.
*
* <p>Note: If you set this to "json", you might also should checkout the documentation about
* {@link #commitIdGenerationMode} and may want to set {@code
* <commitIdGenerationMode>full</commitIdGenerationMode>}.
*
* <p>Example:
*
* <pre>{@code
* <format>properties</format>
* }</pre>
*/
@Parameter(defaultValue = "properties")
String format;
/**
* Not settable by any configuration in the {@code pom.xml}. For internal use only (represents the
* {@link #format} the user has set as enum.
*/
private CommitIdPropertiesOutputFormat commitIdPropertiesOutputFormat;
/**
* Configuration to tell the git-commit-id-maven-plugin about the property that will be used as
* the "namespace" prefix for all exposed/generated properties. An example the plugin may generate
* the property `${configured-prefix}.commit.id`. Such behaviour can be used to generate
* properties for multiple git repositories (see <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/137#issuecomment-418144756">issue
* 173</a> for a full example).
*
* <p>By default is set to {@code 'git'} that for example would allow you to access {@code
* ${git.branch}}
*
* <p>Example:
*
* <pre>{@code
* <prefix>git</prefix>
* }</pre>
*/
@Parameter(defaultValue = "git")
String prefix;
/**
* This date format will be used to format the time of any exposed/generated property that
* represents dates or times exported by this plugin (e.g. {@code git.commit.time}, {@code
* git.build.time}). It should be a valid {@link SimpleDateFormat} string.
*
* <p>The current dateFormat will be formatted as ISO 8601
* {@code yyyy-MM-dd'T'HH:mm:ssXXX} and therefore can be used as input to maven's
* <a href="https://maven.apache.org/guides/mini/guide-reproducible-builds.html">
* reproducible build</a> feature.
*
* Please note that in previous versions
* (2.2.2 - 7.0.1) the default format was set to {@code yyyy-MM-dd'T'HH:mm:ssZ}
* which produces a {@code RFC 822 time zone}. While such format gives reliable
* options in parsing the date, it does not comply with the requirements of
* the reproducible build feature.
* (2.2.0 - 2.2.2) the default dateFormat was set to: {@code
* dd.MM.yyyy '@' HH:mm:ss z}.
*
* <p>Example:
*
* <pre>{@code
* <dateFormat>yyyy-MM-dd'T'HH:mm:ssXXX</dateFormat>
* }</pre>
*
* @since 2.2.0
*/
@Parameter(defaultValue = "yyyy-MM-dd'T'HH:mm:ssXXX")
String dateFormat;
/**
* The timezone used in the {@link #dateFormat} of dates exported by this plugin (e.g. {@code
* git.commit.time}, {@code git.build.time}). It should be a valid Timezone string such as {@code
* 'America/Los_Angeles'}, {@code 'GMT+10'} or {@code 'PST'}.
*
* <p>As a general warning try to avoid three-letter time zone IDs because the same abbreviation
* are often used for multiple time zones. Please review <a
* href="https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html">
* https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html</a> for more information on
* this issue.
*
* <p>The default value we'll use the timezone use the timezone that's shipped with java ({@code
* java.util.TimeZone.getDefault().getID()}). <b>Note</b>: If you plan to set the java's timezone
* by using {@code MAVEN_OPTS=-Duser.timezone=UTC mvn clean package}, {@code mvn clean package
* -Duser.timezone=UTC}, or any other configuration keep in mind that this option will override
* those settings and will not take other configurations into account!
*
* <p>Example:
*
* <pre>{@code
* <dateFormatTimeZone>${user.timezone}</dateFormatTimeZone>
* }</pre>
*
* @since 2.2.0
*/
@Parameter String dateFormatTimeZone;
/**
* Specify whether the plugin should fail when a {@code '.git'} directory cannot be found. When
* set to {@code false} and no {@code .git} directory is found the plugin will skip execution.
*
* <p>Defaults to {@code true}, so a missing {@code '.git'} directory is treated as error and
* should cause a failure in your build.
*
* <p>Example:
*
* <pre>{@code
* <failOnNoGitDirectory>true</failOnNoGitDirectory>
* }</pre>
*
* @since 2.0.4
*/
@Parameter(defaultValue = "true")
boolean failOnNoGitDirectory;
/**
* Set this to {@code false} to continue the build even if unable to get enough data for a
* complete run. This may be useful during CI builds if the CI server does weird things to the
* repository.
*
* <p>Setting this value to {@code false} causes the plugin to gracefully tell you "I did my best"
* and abort its execution if unable to obtain git meta data - yet the build will continue to run
* without failing.
*
* <p>By default the plugin will fail the build (set to {@code true}) if unable to obtain enough
* data for a complete run.
*
* <p>See <a href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/63">issue
* #63</a> for a rationale behind this flag.
*
* <p>Example:
*
* <pre>{@code
* <failOnUnableToExtractRepoInfo>true</failOnUnableToExtractRepoInfo>
* }</pre>
*
* @since 2.1.5
*/
@Parameter(defaultValue = "true")
boolean failOnUnableToExtractRepoInfo;
/**
* This plugin ships with custom {@code jgit} implementation that is being used to obtain all
* relevant information. If set to {@code true} the plugin will use native git executable instead
* of the custom {@code jgit} implementation to fetch information about the repository. Of course
* if set to {@code true} will require a git executable to be installed in system.
*
* <p>Although setting this to {@code true} (use the native git executable) should usually give
* your build some performance boost, it may randomly break if you upgrade your git version and it
* decides to print information in a different format suddenly.
*
* <p>By default the plugin will use {@code jgit} implementation as a source of information about
* the repository. As rule of thumb, keep using the default {@code jgit} implementation (set to
* {@code false}) until you notice performance problems within your build (usually when you have
* *hundreds* of maven modules).
*
* <p>With plugin version *3.0.2* you can also control it using the commandline option {@code
* -Dmaven.gitcommitid.nativegit=true}. See {@link #useNativeGitViaCommandLine}
*
* <p>Example:
*
* <pre>{@code
* <useNativeGit>true</useNativeGit>
* }</pre>
*
* @since 2.1.9
*/
@Parameter(defaultValue = "false")
boolean useNativeGit;
/**
* Option to be used in command-line to override the value of {@link #useNativeGit} specified in
* the pom.xml, or its default value if it's not set explicitly.
*
* <p>NOTE / WARNING: Do *NOT* set this property inside the configuration of your plugin. Please
* read <a href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/315">issue
* 315</a> to find out why.
*
* <p>Example:
*
* <pre>{@code
* mvn clean package -Dmaven.gitcommitid.nativegit=true
* }</pre>
*
* @since 3.0.2
*/
@Parameter(property = "maven.gitcommitid.nativegit", defaultValue = "false")
boolean useNativeGitViaCommandLine;
/**
* When set to {@code true} the plugin execution will completely skip. This is useful for e.g.
* profile activated plugin invocations or to use properties to enable / disable pom features.
*
* <p>By default the execution is not skipped (set to {@code false})
*
* <p>With version *2.2.3* you can also skip the plugin by using the commandline option {@code
* -Dmaven.gitcommitid.skip=true}. See {@link #skipViaCommandLine}
*
* <p>Example:
*
* <pre>{@code
* <skip>false</skip>
* }</pre>
*
* @since 2.1.8
*/
@Parameter(defaultValue = "false")
boolean skip;
/**
* Option to be used in command-line to override the value of {@link #skip} specified in the
* pom.xml, or its default value if it's not set explicitly. Set this to {@code true} to skip
* plugin execution via commandline.
*
* <p>NOTE / WARNING: Do *NOT* set this property inside the configuration of your plugin. Please
* read <a href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/315">issue
* 315</a> to find out why.
*
* <p>Example:
*
* <pre>{@code
* mvn clean package -Dmaven.gitcommitid.skip=true
* }</pre>
*
* @since 2.2.4
*/
@Parameter(property = "maven.gitcommitid.skip", defaultValue = "false")
private boolean skipViaCommandLine;
/**
* Use with caution!
*
* <p>Set this to {@code true} to only run once in a multi-module build. This means that the
* plugins effects will only execute once for the first project in the execution graph. If {@code
* skipPoms} is set to {@code true} (default) the plugin will run for the first non pom project in
* the execution graph (as listed in the reactor build order). This probably won't "do the right
* thing" if your project has more than one git repository.
*
* <p>Defaults to {@code false}, so the plugin may get executed multiple times in a reactor build!
*
* <p>Important: If you're using {@link #generateGitPropertiesFile}, setting {@code runOnlyOnce}
* will make the plugin only generate the file in the project build directory which is the first
* one based on the execution graph (!).
*
* <p>Important: Please note that the git-commit-id-maven-plugin also has an option to skip pom
* project ({@code <packaging>pom</packaging>}). If you plan to use the {@code runOnlyOnce} option
* alongside with an aggregator pom you may want to set {@code <skipPoms>false</skipPoms>}. Refer
* to {@link #skipPoms} for more information
*
* <p>For multi-module build you might also want to set {@link #injectAllReactorProjects} to make
* the {@code git.*} maven properties available in all modules.
*
* <p>Note: Prior to version 4.0.0 the plugin was simply using the execute once applied for the
* parent project (which might have skipped execution if the parent project was a pom project).
*
* <p>Example:
*
* <pre>{@code
* <runOnlyOnce>true</runOnlyOnce>
* }</pre>
*
* @since 2.1.12
*/
@Parameter(defaultValue = "false")
boolean runOnlyOnce;
/**
* Can be used to exclude certain properties from being emitted (e.g. filter out properties that
* you *don't* want to expose). May be useful when you want to hide {@code git.build.user.email}
* (maybe because you don't want to expose your eMail?), or the email of the committer?
*
* <p>Each value may be globbing, that is, you can write {@code git.commit.user.*} to exclude both
* the {@code name}, as well as {@code email} properties from being emitted.
*
* <p>Please note that the strings here are Java regexes ({@code .*} is globbing, not plain {@code
* *}). If you have a very long list of exclusions you may want to use {@link
* #includeOnlyProperties}.
*
* <p>This feature was implemented in response to <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/91">issue 91</a>, so
* if you're curious about the use-case, check that issue.
*
* <p>Prior to version 3.0.0 the plugin used the 'naive' approach to ask for all properties and
* then apply filtering. However, with the growing numbers of properties each property eat more
* and more of execution time that will be filtered out afterwards. With 3.0.0 this behaviour was
* readjusted to a 'selective running' approach whereby the plugin will not even try to get the
* property when excluded. Such behaviour can result in an overall reduced execution time of the
* plugin (see <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/408">issue 408</a> for
* details).
*
* <p>Defaults to the empty list (= no properties are excluded).
*
* <p>Example:
*
* <pre>{@code
* <excludeProperties>
* <excludeProperty>git.user.*</excludeProperty>
* </excludeProperties>
* }</pre>
*
* @since 2.1.9
*/
@Parameter List<String> excludeProperties;
/**
* Can be used to include only certain properties into the emission (e.g. include only properties
* that you <b>want</b> to expose). This feature was implemented to avoid big exclude properties
* tag when we only want very few specific properties.
*
* <p>The inclusion rules, will be overruled by the {@link #excludeProperties} rules (e.g. you can
* write an inclusion rule that applies for multiple properties and then exclude a subset of
* them). You can therefor can be a bit broader in the inclusion rules and exclude more sensitive
* ones in the {@link #excludeProperties} rules.
*
* <p>Each value may be globbing, that is, you can write {@code git.commit.user.*} to exclude both
* the {@code name}, as well as {@code email} properties from being emitted.
*
* <p>Please note that the strings here are Java regexes ({@code .*} is globbing, not plain {@code
* *}). If you have a short list of exclusions you may want to use {@link #excludeProperties}.
*
* <p>Prior to version 3.0.0 the plugin used the 'naive' approach to ask for all properties and
* then apply filtering. However, with the growing numbers of properties each property eat more
* and more of execution time that will be filtered out afterwards. With 3.0.0 this behaviour was
* readjusted to a 'selective running' approach whereby the plugin will not even try to get the
* property when excluded. Such behaviour can result in an overall reduced execution time of the
* plugin (see <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/408">issue 408</a> for
* details).
*
* <p>Defaults to the empty list (= no properties are excluded).
*
* <p>Example:
*
* <pre>{@code
* <includeOnlyProperties>
* <includeOnlyProperty>^git.commit.id.full$</includeOnlyProperty>
* </includeOnlyProperties>
* }</pre>
*
* @since 2.1.14
*/
@Parameter List<String> includeOnlyProperties;
/**
* The option can be used to tell the plugin how it should generate the {@code 'git.commit.id'}
* property. Due to some naming issues when exporting the properties as an json-object (<a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/122">issue 122</a>) we
* needed to make it possible to export all properties as a valid json-object.
*
* <p>Due to the fact that this is one of the major properties the plugin is exporting we just
* don't want to change the exporting mechanism and somehow throw the backwards compatibility
* away. We rather provide a convenient switch where you can choose if you would like the
* properties as they always had been, or if you rather need to support full json-object
* compatibility.
*
* <p>In the case you need to fully support json-object we unfortunately need to change the {@code
* 'git.commit.id'} property from {@code 'git.commit.id'} to {@code 'git.commit.id.full'} in the
* exporting mechanism to allow the generation of a fully valid json object.
*
* <p>Currently, the switch allows two different options:
*
* <ol>
* <li>By default this property is set to {@code 'flat'} and will generate the formerly known
* property {@code 'git.commit.id'} as it was in the previous versions of the plugin.
* Keeping it to {@code 'flat'} by default preserve backwards compatibility and does not
* require further adjustments by the end user.
* <li>If you set this switch to {@code 'full'} the plugin will export the formerly known
* property {@code 'git.commit.id'} as {@code 'git.commit.id.full'} and therefore will
* generate a fully valid json object in the exporting mechanism.
* </ol>
*
* <p><b>Note:</b> If you set the value to something that's not equal to {@code 'flat'} or {@code
* 'full'} (ignoring the case) the plugin will output a warning and will fallback to the default
* {@code 'flat'} mode.
*
* <p>Example:
*
* <pre>{@code
* <commitIdGenerationMode>flat</commitIdGenerationMode>
* }</pre>
*
* @since 2.2.0
*/
@Parameter(defaultValue = "flat")
String commitIdGenerationMode;
/**
* Not settable by any configuration in the {@code pom.xml}. For internal use only (represents the
* {@link #commitIdGenerationMode} the user has set as enum.
*/
private CommitIdGenerationMode commitIdGenerationModeEnum;
/**
* Can be used to replace certain characters or strings using regular expressions within the
* exposed properties. Replacements can be performed using regular expressions and on a
* configuration level it can be defined whether the replacement should affect all properties or
* just a single one.
*
* <p>Please note that the replacement will only be applied to properties that are being generated
* by the plugin. If you want to replace properties that are being generated by other plugins you
* may want to use the maven-replacer-plugin or any other alternative.
*
* <p>Replacements can be configured with a {@code replacementProperty}. A {@code
* replacementProperty} can have a {@code property}` and a {@code regex}-tag. If the {@code
* replacementProperty} configuration has a {@code property}-tag the replacement will only be
* performed on that specific property (e.g. {@code <property>git.branch</property>} will only be
* performed on {@code git.branch}).
*
* <p>In case this specific element is not defined or left empty the replacement will be performed
* <b>on all generated properties</b>.
*
* <p>The optional {@code regex}-tag can either be {@code true} to perform a replacement with
* regular expressions or {@code false} to perform a replacement with java's
* string.replace-function.
*
* <p>By default the replacement will be performed with regular expressions ({@code true}).
* Furthermore each {@code replacementProperty} need to be configured with a {@code token} and a
* {@code value}. The {@code token} can be seen as the needle and the {@code value} as the text to
* be written over any found tokens. If using regular expressions the value can reference grouped
* regex matches by using $1, $2, etc.
*
* <p>Since 2.2.4 the plugin allows to define a even more sophisticated ruleset and allows to set
* an {@code propertyOutputSuffix} within each {@code replacementProperty}. If this option is
* empty the original property will be overwritten (default behaviour in 2.2.3). However when this
* configuration is set to {@code something} and a user wants to modify the {@code git.branch}
* property the plugin will keep {@code git.branch} as the original one (w/o modifications) but
* also will be creating a new {@code git.branch.something} property with the requested
* replacement.
*
* <p>Furthermore with 2.2.4 the plugin allows to perform certain types of string manipulation
* either before or after the evaluation of the replacement. With this feature a user can
* currently easily manipulate the case (e.g. lower case VS upper case) of the input/output
* property. This behaviour can be achieved by defining a list of {@code transformationRules} for
* the property where those rules should take effect. Each {@code transformationRule} consist of
* two required fields {@code apply} and {@code action}. The {@code apply}-tag controls when the
* rule should be applied and can be set to {@code BEFORE} to have the rule being applied before
* or it can be set to {@code AFTER} to have the rule being applied after the replacement. The
* {@code action}-tag determines the string conversion rule that should be applied. Currently
* supported is {@code LOWER_CASE} and {@code UPPER_CASE}. Potential candidates in the feature are
* {@code CAPITALIZATION} and {@code INVERT_CASE} (open a ticket if you need them...).
*
* <p>Since 4.0.1 the plugin allows to define a {@code forceValueEvaluation}-switch which forces
* the plugin to evaluate the given value on <b>every</b> project.
*
* <p>This might come handy if <b>every</b> project needs a unique value and a user wants to
* project specific variables like {@code ${project.artifactId}}. Be advised that this essentially
* means that the plugin <b>must</b> run for every child-project of a reactor build and thus might
* cause some overhead (the git properties should be cached). For a use-case refer to <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/457">issue 457</a>
*
* <p>Defaults to the empty list / not set (= no properties are being replaced by default)
*
* <p>Example:
*
* <pre>{@code
* <replacementProperties>
* <!--
* example:
* apply replacement only to the specific property git.branch and replace '/' with '-'
* see also https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/138
* -->
* <replacementProperty>
* <property>git.branch</property>
* <propertyOutputSuffix>something</propertyOutputSuffix>
* <token>^([^\/]*)\/([^\/]*)$</token>
* <value>$1-$2</value>
* <regex>true</regex>
* <forceValueEvaluation>false</forceValueEvaluation>
* <transformationRules>
* <transformationRule>
* <apply>BEFORE</apply>
* <action>UPPER_CASE</action>
* </transformationRule>
* <transformationRule>
* <apply>AFTER</apply>
* <action>LOWER_CASE</action>
* </transformationRule>
* </transformationRules>
* </replacementProperty>
* </replacementProperties>
* }</pre>
*
* @since 2.2.3
*/
@Parameter List<ReplacementProperty> replacementProperties;
/**
* Allow to tell the plugin what commit should be used as reference to generate the properties
* from.
*
* <p>In general this property can be set to something generic like {@code HEAD^1} or point to a
* branch or tag-name. To support any kind or use-case this configuration can also be set to an
* entire commit-hash or it's abbreviated version.
*
* <p>A use-case for this feature can be found in <a
* href="https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/338">here</a>.
*
* <p>Please note that for security purposes not all references might be allowed as configuration.
* If you have a specific use-case that is currently not white listed feel free to file an issue.
*
* <p>By default this property is simply set to {@code HEAD} which should reference to the latest
* commit in your repository.
*
* <p>Example:
*
* <pre>{@code
* <evaluateOnCommit>HEAD</evaluateOnCommit>
* }</pre>
*
* @since 2.2.4
*/
@Parameter(defaultValue = "HEAD")
String evaluateOnCommit;
/**
* Allow to specify a timeout (in milliseconds) for fetching information with the native Git
* executable. This option might come in handy in cases where fetching information about the
* repository with the native Git executable does not terminate.
*
* <p>Note: This option will only be taken into consideration when using the native git executable
* ({@link #useNativeGit} is set to {@code true}).
*
* <p>By default this timeout is set to 30000 (30 seconds).
*
* <p>Example:
*
* <pre>{@code
* <nativeGitTimeoutInMs>30000</nativeGitTimeoutInMs>
* }</pre>
*
* @since 3.0.0
*/
@Parameter(defaultValue = "30000")
long nativeGitTimeoutInMs;
/**
* When set to {@code true} this plugin will try to use the branch name from build environment.
* Set to {@code false} to use JGit/GIT to get current branch name which can be useful when using
* the JGitflow maven plugin. See
* https://github.com/git-commit-id/git-commit-id-maven-plugin/issues/24#issuecomment-203285398
*
* <p>Note: If not using "Check out to specific local branch' and setting this to false may result
* in getting detached head state and therefore a commit id as branch name.
*
* <p>By default this is set to {@code true}.