Support for fallback if not in a git repo

[FeldrinH]

What happened?

Currently applying the plugin throws an exception if the project is not inside a git repository (i.e. .git folder is missing).

What did you want to happen?

It would be nice if it was possible to define/enable some kind of fallback version (for example "UNKNOWN") if the git repo can't be found.
gitVersion() would then return this fallback version.
versionDetails() could either return null if the git repo is missing or include a boolean field indicating if the repo was found and empty/default values for other fields.

Alternatively just pushing the exception into gitVersion() and versionDetails() instead of throwing it as soon as the plugin is applied would make it much cleaner for people to manually implement fallback version support using a try-catch block.

This would be useful in cases where you for whatever reason have the code without the git repo and want to run a build and don't care about the version.

One possible use case for this as pointed out in #327 is running unit tests in the CI where code might be copied in without the git repo itself.

Also in general the current behavior forces you to be constantly paranoid about copying the code and the git repo together no matter what you actually want to do with the code.

[miurahr]

I'd like to propose a support of .git-archival.properties file.

When you put a .git-archival.properties in your project root, that contents like

node=$Format:%H$
date=$Format:%cI$
describe=$Format:%(describe:tags=true,match=v[0-9]*)$

and you can configure .gitattributes

.git-archival.properties  export-subst

A project may have tags v1.1.1 style release tags.

When users, who is outside of the project, download source archive from GitHub Download zip feature,
THe users will find a .git-archival.propertries file like

node=a6243fa2bed7eeb93673258f76973cc328135776
date=2023-11-07T13:49:37+09:00
describe=v0.14.1-3-ga6243fa

You can configure your build.gradle like

def dotgit = project.file(".git")
if (dotgit.exists()) {
    apply plugin: 'com.palantir.git-version'
    // calculate version string from git tag, hash and commit distance
    // It treat as release tag when current HEAD has a tag,
    // and repository is clean, no modification,and no untracked files,
    if (versionDetails().isCleanTag) {
        // drop first 'v' from version tag
        version = gitVersion().substring(1)
    } else {
        version = versionDetails().lastTag.substring(1) + '-' + versionDetails().commitDistance + '-' + versionDetails().gitHash + '-SNAPSHOT'
    }
} else {
    def gitArchival = project.file(".git-archival.properties")
    def prop = new Properties()
    prop.load(new FileInputStream(gitArchival))
    def versionDescribe = prop.getProperty("describe")
    def matcher = versionDescribe =~ /^v\d+\.\d+\.\d+$/
    version = matcher.find() ? versionDescribe.substring(1) : versionDescribe.substring(1) + "-SNAPSHOT"
}

You will get version variable even when it is not a git work directory.

I hope gradle-git-version plugin handles .git-archival.properties automatically and put these tips on document.

The solution is inspired by setuptools_scm python versioning plugin that support .git_archival.txt file.
https://setuptools-scm.readthedocs.io/en/latest/usage/#git-archives