Support for Dotenv output format

[Bi0T1N]

Description

This PR implements the functionality to export the GitVersion variables in the Dotenv format that can be consumed by your environment.

Related Issue

Closes #4174

Motivation and Context

Exporting the variables in the Dotenv format provides a simple mechanism to use the GitVersion variables in your shell environment. Additonallty some CI systems like GitHub or GitLab allow to pass around and expanding the jobs environment with artifacts in the Dotenv format.

It can be discussed how the output should look like e.g. wrap all values in '<value>', write nothing for empty lines or use '' (that's what I've decided for). The parsing rules for nodejs projects are here while the ones for GitLab CI can be found here.

How Has This Been Tested?

With the provided unit tests as well as with a Python script and a library for handling Dotenv files (see Examples section below).

Examples:

Running the following commands

git init --initial-branch=main
touch text.txt
git add test.txt 
git commit -m "test"
gitversion /output dotenv > gitversion.env

results in a gitversion.env file with the following content

GitVersion_AssemblySemFileVer=0.0.1.0
GitVersion_AssemblySemVer=0.0.1.0
GitVersion_BranchName=main
GitVersion_BuildMetaData=''
GitVersion_CommitDate=2025-02-08
GitVersion_CommitsSinceVersionSource=1
GitVersion_EscapedBranchName=main
GitVersion_FullBuildMetaData=Branch.main.Sha.2501b1440f9823abca9f9100f3776e42a3d730c3
GitVersion_FullSemVer=0.0.1-1
GitVersion_InformationalVersion=0.0.1-1+Branch.main.Sha.2501b1440f9823abca9f9100f3776e42a3d730c3
GitVersion_Major=0
GitVersion_MajorMinorPatch=0.0.1
GitVersion_Minor=0
GitVersion_Patch=1
GitVersion_PreReleaseLabel=''
GitVersion_PreReleaseLabelWithDash=''
GitVersion_PreReleaseNumber=1
GitVersion_PreReleaseTag=1
GitVersion_PreReleaseTagWithDash=-1
GitVersion_SemVer=0.0.1-1
GitVersion_Sha=2501b1440f9823abca9f9100f3776e42a3d730c3
GitVersion_ShortSha=2501b14
GitVersion_UncommittedChanges=1519
GitVersion_VersionSourceSha=''
GitVersion_WeightedPreReleaseNumber=55001

Loading that file in Python (pip install python-dotenv) with the following script

import dotenv
import os

dotenv_file = dotenv.find_dotenv('gitversion.env')
dotenv.load_dotenv(dotenv_file)

print("-- output loaded values as example --")
print(os.environ["GitVersion_MajorMinorPatch"])  # 0.0.1
print(os.environ['GitVersion_VersionSourceSha'])  # empty

print("-- manipulate a loaded value --")
os.environ["GitVersion_MajorMinorPatch"] = ""
print(os.environ['GitVersion_MajorMinorPatch'])  # empty

print("-- write changes to env file --")
dotenv.set_key("python_gitversion.env", "GitVersion_Major", os.environ["GitVersion_Major"])
dotenv.set_key("python_gitversion.env", "GitVersion_FullSemVer", os.environ["GitVersion_FullSemVer"])
dotenv.set_key("python_gitversion.env", "GitVersion_MajorMinorPatch", os.environ["GitVersion_MajorMinorPatch"])
dotenv.set_key("python_gitversion.env", "GitVersion_VersionSourceSha", os.environ["GitVersion_VersionSourceSha"])

writes

-- output loaded values as example --
0.0.1

-- manipulate a loaded value --

-- write changes to env file --

to the console (and thus proves it can load/understand the generated Dotenv format from GitVersion) and results in a python_gitversion.env file with the content

GitVersion_MajorMinorPatch=''
GitVersion_VersionSourceSha=''
GitVersion_Major='0'
GitVersion_FullSemVer='0.0.1-1'

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[arturcic]

@asbjornu we probably should rebase this branch onto main instead of merge main into this branch

[asbjornu]

@asbjornu we probably should rebase this branch onto main instead of merge main into this branch

Indeed. I wish that was possible in the GitHub UI!

[Bi0T1N]

I rebased my changes on top of main and thus also removed the merge ;-)

[Bi0T1N]

I assume the Windows tests fail because of the \n at the end of output.ShouldContain("GitVersion_" + variableName + "=" + expectedValue + "\n");.
Can someone with access to a Windows machine confirm this please? The fix would probably be Environment.NewLine.

[arturcic]

@Bi0T1N I will take this one for a spin before merging

[arturcic]

@Bi0T1N please rebase this one on main (no merge)

[Bi0T1N]

I decided to wrap all values into single quotes thus it should be more future proof as it might not break
on values that contain whitespaces, etc.
Output looks like that now:

GitVersion_AssemblySemFileVer='0.0.1.0'
GitVersion_AssemblySemVer='0.0.1.0'
GitVersion_BranchName='main'
GitVersion_BuildMetaData=''
GitVersion_CommitDate='2025-03-07'
GitVersion_CommitsSinceVersionSource='1'
GitVersion_EscapedBranchName='main'
GitVersion_FullBuildMetaData='Branch.main.Sha.8d1cb464bbb0ee504774b6f6ef61d2c0dc419af8'
GitVersion_FullSemVer='0.0.1-1'
GitVersion_InformationalVersion='0.0.1-1+Branch.main.Sha.8d1cb464bbb0ee504774b6f6ef61d2c0dc419af8'
GitVersion_Major='0'
GitVersion_MajorMinorPatch='0.0.1'
GitVersion_Minor='0'
GitVersion_Patch='1'
GitVersion_PreReleaseLabel=''
GitVersion_PreReleaseLabelWithDash=''
GitVersion_PreReleaseNumber='1'
GitVersion_PreReleaseTag='1'
GitVersion_PreReleaseTagWithDash='-1'
GitVersion_SemVer='0.0.1-1'
GitVersion_Sha='8d1cb464bbb0ee504774b6f6ef61d2c0dc419af8'
GitVersion_ShortSha='8d1cb46'
GitVersion_UncommittedChanges='0'
GitVersion_VersionSourceSha=''
GitVersion_WeightedPreReleaseNumber='55001'

The python_gitversion.env file that is generated by the script from above still contains the same content:

GitVersion_Major='0'
GitVersion_FullSemVer='0.0.1-1'
GitVersion_MajorMinorPatch=''
GitVersion_VersionSourceSha=''

[arturcic]

Next week I have a bit of time, will review the PR

[arturcic]

@mergify rebase

[mergify]

rebase

✅ Nothing to do for rebase action

[arturcic]

LGTM!, Great job

[mergify]

Thank you @Bi0T1N for your contribution!