418 lines
15 KiB
Markdown
418 lines
15 KiB
Markdown
# Execute GitVersion Task (gitversion/execute) Usage Examples
|
|
|
|
Find out how to use the **gitversion/execute** task using the examples below.
|
|
|
|
> The examples use the latest _0.x_ version of the GitVersion Execute task. It is recommended to use the latest released version in your own pipelines.
|
|
|
|
Note that if the pipeline is setup to use a shallow git fetch mode the GitVersion Execute task will fail. It is required to use fetchDepth of 0 like so:
|
|
|
|
```yaml
|
|
- checkout: self
|
|
fetchDepth: 0
|
|
```
|
|
|
|
## Inputs
|
|
|
|
The Execute GitVersion task accepts the following inputs:
|
|
|
|
```yaml
|
|
targetPath:
|
|
description: Optionally supply the path to the working directory.
|
|
required: false
|
|
default: ''
|
|
useConfigFile:
|
|
description: Whether to use a custom configuration file.
|
|
required: false
|
|
default: false
|
|
configFilePath:
|
|
description: Optional path to config file (defaults to GitVersion.yml).
|
|
required: false
|
|
default: ''
|
|
updateAssemblyInfo:
|
|
description: Whether to update versions in the AssemblyInfo files.
|
|
required: false
|
|
default: false
|
|
updateAssemblyInfoFilename:
|
|
description: Update versions in specified file.
|
|
required: false
|
|
default: ''
|
|
additionalArguments:
|
|
description: Additional arguments to send to GitVersion.
|
|
required: false
|
|
default: ''
|
|
```
|
|
|
|
## Outputs
|
|
|
|
The Execute GitVersion task creates the following job-scoped variables and multi-job output variables:
|
|
|
|
- major
|
|
- minor
|
|
- patch
|
|
- preReleaseTag
|
|
- preReleaseTagWithDash
|
|
- preReleaseLabel
|
|
- preReleaseNumber
|
|
- weightedPreReleaseNumber
|
|
- buildMetaData
|
|
- buildMetaDataPadded (removed in 6.0.0)
|
|
- fullBuildMetaData
|
|
- majorMinorPatch
|
|
- semVer
|
|
- legacySemVer (removed in 6.0.0)
|
|
- legacySemVerPadded (removed in 6.0.0)
|
|
- assemblySemVer
|
|
- assemblySemFileVer
|
|
- fullSemVer
|
|
- informationalVersion
|
|
- branchName
|
|
- escapedBranchName (since 5.2.0)
|
|
- sha
|
|
- shortSha
|
|
- nuGetVersionV2 (removed in 6.0.0)
|
|
- nuGetVersion (removed in 6.0.0)
|
|
- nuGetPreReleaseTagV2 (removed in 6.0.0)
|
|
- nuGetPreReleaseTag (removed in 6.0.0)
|
|
- versionSourceSha
|
|
- commitsSinceVersionSource
|
|
- commitsSinceVersionSourcePadded (since 5.2.0, removed in 6.0.0)
|
|
- uncommittedChanges (since 5.5.0)
|
|
- commitDate
|
|
|
|
The outputs can be accessed using the syntax `$(<id>.<outputName>)` or `$(<id>.GitVersion_<OutputName>)`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job. See example [5](#example-5).
|
|
|
|
The action also creates environment variables of the form `$(<outputName>)` or `$(GitVersion_<OutputName>)` for use by other steps in the same job. See example [6](#example-6).
|
|
|
|
The multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples [7](#example-7) to [10](#example-10).
|
|
|
|
**GitVersion also automatically updates the pre-defined Build variable `Build.BuildNumber`.**
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Example 1
|
|
|
|
Calculate the version for the build.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Determine Version
|
|
```
|
|
|
|
### Example 2
|
|
|
|
Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Determine Version
|
|
inputs:
|
|
useConfigFile: true
|
|
```
|
|
|
|
Example contents of **GitVersion.yml**:
|
|
|
|
```yaml
|
|
mode: Mainline
|
|
branches:
|
|
master:
|
|
regex: ^latest$
|
|
pull-request:
|
|
tag: pr
|
|
```
|
|
|
|
### Example 3
|
|
|
|
Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Determine Version
|
|
inputs:
|
|
useConfigFile: true
|
|
configFilePath: 'VersionConfig.yml'
|
|
```
|
|
|
|
### Example 4
|
|
|
|
Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Display GitVersion config
|
|
inputs:
|
|
additionalArguments: '/showConfig'
|
|
```
|
|
|
|
### Example 5
|
|
|
|
Calculate the version for the build and display all the calculated variables in the next step.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
name: version # id to later be referenced
|
|
displayName: Determine Version
|
|
|
|
- displayName: Display GitVersion outputs (step output)
|
|
script: |
|
|
echo "Major: $(version.major)"
|
|
echo "Minor: $(version.minor)"
|
|
echo "Patch: $(version.patch)"
|
|
echo "PreReleaseTag: $(version.preReleaseTag)"
|
|
echo "PreReleaseTagWithDash: $(version.preReleaseTagWithDash)"
|
|
echo "PreReleaseLabel: $(version.preReleaseLabel)"
|
|
echo "PreReleaseNumber: $(version.preReleaseNumber)"
|
|
echo "WeightedPreReleaseNumber: $(version.weightedPreReleaseNumber)"
|
|
echo "BuildMetaData: $(version.buildMetaData)"
|
|
echo "BuildMetaDataPadded: $(version.buildMetaDataPadded)"
|
|
echo "FullBuildMetaData: $(version.fullBuildMetaData)"
|
|
echo "MajorMinorPatch: $(version.majorMinorPatch)"
|
|
echo "SemVer: $(version.semVer)"
|
|
echo "LegacySemVer: $(version.legacySemVer)"
|
|
echo "LegacySemVerPadded: $(version.legacySemVerPadded)"
|
|
echo "AssemblySemVer: $(version.assemblySemVer)"
|
|
echo "AssemblySemFileVer: $(version.assemblySemFileVer)"
|
|
echo "FullSemVer: $(version.fullSemVer)"
|
|
echo "InformationalVersion: $(version.informationalVersion)"
|
|
echo "BranchName: $(version.branchName)"
|
|
echo "EscapedBranchName: $(version.escapedBranchName)"
|
|
echo "Sha: $(version.sha)"
|
|
echo "ShortSha: $(version.shortSha)"
|
|
echo "NuGetVersionV2: $(version.nuGetVersionV2)"
|
|
echo "NuGetVersion: $(version.nuGetVersion)"
|
|
echo "NuGetPreReleaseTagV2: $(version.nuGetPreReleaseTagV2)"
|
|
echo "NuGetPreReleaseTag: $(version.nuGetPreReleaseTag)"
|
|
echo "VersionSourceSha: $(version.versionSourceSha)"
|
|
echo "CommitsSinceVersionSource: $(version.commitsSinceVersionSource)"
|
|
echo "CommitsSinceVersionSourcePadded: $(version.commitsSinceVersionSourcePadded)"
|
|
echo "UncommittedChanges: $(version.uncommittedChanges)"
|
|
echo "CommitDate: $(version.commitDate)"
|
|
|
|
- displayName: Display GitVersion outputs (step output with prefix)
|
|
script: |
|
|
echo "Major: $(version.GitVersion_Major)"
|
|
echo "Minor: $(version.GitVersion_Minor)"
|
|
echo "Patch: $(version.GitVersion_Patch)"
|
|
echo "PreReleaseTag: $(version.GitVersion_PreReleaseTag)"
|
|
echo "PreReleaseTagWithDash: $(version.GitVersion_PreReleaseTagWithDash)"
|
|
echo "PreReleaseLabel: $(version.GitVersion_PreReleaseLabel)"
|
|
echo "PreReleaseNumber: $(version.GitVersion_PreReleaseNumber)"
|
|
echo "WeightedPreReleaseNumber: $(version.GitVersion_WeightedPreReleaseNumber)"
|
|
echo "BuildMetaData: $(version.GitVersion_BuildMetaData)"
|
|
echo "BuildMetaDataPadded: $(version.GitVersion_BuildMetaDataPadded)"
|
|
echo "FullBuildMetaData: $(version.GitVersion_FullBuildMetaData)"
|
|
echo "MajorMinorPatch: $(version.GitVersion_MajorMinorPatch)"
|
|
echo "SemVer: $(version.GitVersion_SemVer)"
|
|
echo "LegacySemVer: $(version.GitVersion_LegacySemVer)"
|
|
echo "LegacySemVerPadded: $(version.GitVersion_LegacySemVerPadded)"
|
|
echo "AssemblySemVer: $(version.GitVersion_AssemblySemVer)"
|
|
echo "AssemblySemFileVer: $(version.GitVersion_AssemblySemFileVer)"
|
|
echo "FullSemVer: $(version.GitVersion_FullSemVer)"
|
|
echo "InformationalVersion: $(version.GitVersion_InformationalVersion)"
|
|
echo "BranchName: $(version.GitVersion_BranchName)"
|
|
echo "EscapedBranchName: $(version.GitVersion_EscapedBranchName)"
|
|
echo "Sha: $(version.GitVersion_Sha)"
|
|
echo "ShortSha: $(version.GitVersion_ShortSha)"
|
|
echo "NuGetVersionV2: $(version.GitVersion_NuGetVersionV2)"
|
|
echo "NuGetVersion: $(version.GitVersion_NuGetVersion)"
|
|
echo "NuGetPreReleaseTagV2: $(version.GitVersion_NuGetPreReleaseTagV2)"
|
|
echo "NuGetPreReleaseTag: $(version.GitVersion_NuGetPreReleaseTag)"
|
|
echo "VersionSourceSha: $(version.GitVersion_VersionSourceSha)"
|
|
echo "CommitsSinceVersionSource: $(version.GitVersion_CommitsSinceVersionSource)"
|
|
echo "CommitsSinceVersionSourcePadded: $(version.GitVersion_CommitsSinceVersionSourcePadded)"
|
|
echo "UncommittedChanges: $(version.GitVersion_UncommittedChanges)"
|
|
echo "CommitDate: $(version.GitVersion_CommitDate)"
|
|
```
|
|
|
|
### Example 6
|
|
|
|
Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Determine Version
|
|
|
|
- displayName: Display GitVersion variables (without prefix)
|
|
script: |
|
|
echo "Major: $(major)"
|
|
echo "Minor: $(minor)"
|
|
echo "Patch: $(patch)"
|
|
echo "PreReleaseTag: $(preReleaseTag)"
|
|
echo "PreReleaseTagWithDash: $(preReleaseTagWithDash)"
|
|
echo "PreReleaseLabel: $(preReleaseLabel)"
|
|
echo "PreReleaseNumber: $(preReleaseNumber)"
|
|
echo "WeightedPreReleaseNumber: $(weightedPreReleaseNumber)"
|
|
echo "BuildMetaData: $(buildMetaData)"
|
|
echo "BuildMetaDataPadded: $(buildMetaDataPadded)"
|
|
echo "FullBuildMetaData: $(fullBuildMetaData)"
|
|
echo "MajorMinorPatch: $(majorMinorPatch)"
|
|
echo "SemVer: $(semVer)"
|
|
echo "LegacySemVer: $(legacySemVer)"
|
|
echo "LegacySemVerPadded: $(legacySemVerPadded)"
|
|
echo "AssemblySemVer: $(assemblySemVer)"
|
|
echo "AssemblySemFileVer: $(assemblySemFileVer)"
|
|
echo "FullSemVer: $(fullSemVer)"
|
|
echo "InformationalVersion: $(informationalVersion)"
|
|
echo "BranchName: $(branchName)"
|
|
echo "EscapedBranchName: $(escapedBranchName)"
|
|
echo "Sha: $(sha)"
|
|
echo "ShortSha: $(shortSha)"
|
|
echo "NuGetVersionV2: $(nuGetVersionV2)"
|
|
echo "NuGetVersion: $(nuGetVersion)"
|
|
echo "NuGetPreReleaseTagV2: $(nuGetPreReleaseTagV2)"
|
|
echo "NuGetPreReleaseTag: $(nuGetPreReleaseTag)"
|
|
echo "VersionSourceSha: $(versionSourceSha)"
|
|
echo "CommitsSinceVersionSource: $(commitsSinceVersionSource)"
|
|
echo "CommitsSinceVersionSourcePadded: $(commitsSinceVersionSourcePadded)"
|
|
echo "UncommittedChanges: $(uncommittedChanges)"
|
|
echo "CommitDate: $(commitDate)"
|
|
|
|
- displayName: Display GitVersion variables (with prefix)
|
|
script: |
|
|
echo "Major: $(GitVersion_Major)"
|
|
echo "Minor: $(GitVersion_Minor)"
|
|
echo "Patch: $(GitVersion_Patch)"
|
|
echo "PreReleaseTag: $(GitVersion_PreReleaseTag)"
|
|
echo "PreReleaseTagWithDash: $(GitVersion_PreReleaseTagWithDash)"
|
|
echo "PreReleaseLabel: $(GitVersion_PreReleaseLabel)"
|
|
echo "PreReleaseNumber: $(GitVersion_PreReleaseNumber)"
|
|
echo "WeightedPreReleaseNumber: $(GitVersion_WeightedPreReleaseNumber)"
|
|
echo "BuildMetaData: $(GitVersion_BuildMetaData)"
|
|
echo "BuildMetaDataPadded: $(GitVersion_BuildMetaDataPadded)"
|
|
echo "FullBuildMetaData: $(GitVersion_FullBuildMetaData)"
|
|
echo "MajorMinorPatch: $(GitVersion_MajorMinorPatch)"
|
|
echo "SemVer: $(GitVersion_SemVer)"
|
|
echo "LegacySemVer: $(GitVersion_LegacySemVer)"
|
|
echo "LegacySemVerPadded: $(GitVersion_LegacySemVerPadded)"
|
|
echo "AssemblySemVer: $(GitVersion_AssemblySemVer)"
|
|
echo "AssemblySemFileVer: $(GitVersion_AssemblySemFileVer)"
|
|
echo "FullSemVer: $(GitVersion_FullSemVer)"
|
|
echo "InformationalVersion: $(GitVersion_InformationalVersion)"
|
|
echo "BranchName: $(GitVersion_BranchName)"
|
|
echo "EscapedBranchName: $(GitVersion_EscapedBranchName)"
|
|
echo "Sha: $(GitVersion_Sha)"
|
|
echo "ShortSha: $(GitVersion_ShortSha)"
|
|
echo "NuGetVersionV2: $(GitVersion_NuGetVersionV2)"
|
|
echo "NuGetVersion: $(GitVersion_NuGetVersion)"
|
|
echo "NuGetPreReleaseTagV2: $(GitVersion_NuGetPreReleaseTagV2)"
|
|
echo "NuGetPreReleaseTag: $(GitVersion_NuGetPreReleaseTag)"
|
|
echo "VersionSourceSha: $(GitVersion_VersionSourceSha)"
|
|
echo "CommitsSinceVersionSource: $(GitVersion_CommitsSinceVersionSource)"
|
|
echo "CommitsSinceVersionSourcePadded: $(GitVersion_CommitsSinceVersionSourcePadded)"
|
|
echo "UncommittedChanges: $(GitVersion_UncommittedChanges)"
|
|
echo "CommitDate: $(GitVersion_CommitDate)"
|
|
|
|
- task: DotNetCoreCLI@2
|
|
displayName: Pack Example
|
|
inputs:
|
|
command: pack
|
|
packagesToPack: src/Example/LibExample.csproj
|
|
versioningScheme: byEnvVar
|
|
versionEnvVar: GitVersion_SemVer # alternative syntax GITVERSION_SEMVER (the former gets converted into the latter internally)
|
|
```
|
|
|
|
### Example 7
|
|
|
|
Calculate the version for the build and use the `GitVersion_BranchName` variable in a condition for starting another job.
|
|
|
|
```yaml
|
|
jobs:
|
|
- job: CalculateVersion
|
|
displayName: Calculate version using GitVersion
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Use GitVersion
|
|
name: Version # the step MUST be named to access its output variables in another job.
|
|
|
|
- job: CreateReleaseNotes
|
|
condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion_BranchName'], 'main'))
|
|
dependsOn: CalculateVersion
|
|
```
|
|
|
|
### Example 8
|
|
|
|
Calculate the version for the build and map the `GitVersion_SemVer` variable into a variable in another job.
|
|
|
|
```yaml
|
|
jobs:
|
|
- job: CalculateVersion
|
|
displayName: Calculate version using GitVersion
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Use GitVersion
|
|
name: Version # the step MUST be named to access its output variables in another job.
|
|
|
|
- job: BuildAndPack
|
|
variables:
|
|
Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion_MajorMinorPatch'] ]
|
|
```
|
|
|
|
### Example 9
|
|
|
|
Calculate the version for the build and use the `GitVersion.Major` output variable in a condition for starting another stage.
|
|
|
|
```yaml
|
|
stages:
|
|
- stage: S1
|
|
jobs:
|
|
- job: CalculateVersion
|
|
displayName: Calculate version number using GitVersion
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Use GitVersion
|
|
name: Version # the step MUST be named to access its output variables in another stage.
|
|
|
|
- stage: S2
|
|
condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion_Major'], 0))
|
|
dependsOn: S1
|
|
```
|
|
|
|
### Example 10
|
|
|
|
Calculate the version for the build and map the `GitVersion.AssemblySemVer` variable into a variable in another job for a different stage.
|
|
|
|
```yaml
|
|
stages:
|
|
- stage: S1
|
|
jobs:
|
|
- job: CalculateVersion
|
|
displayName: Calculate version number using GitVersion
|
|
steps:
|
|
# gitversion/setup@0 task omitted for brevity.
|
|
|
|
- task: gitversion/execute@0
|
|
displayName: Use GitVersion
|
|
name: Version # the step MUST be named to access its output variables in another stage.
|
|
- stage: S2
|
|
dependsOn: S1
|
|
jobs:
|
|
- job: UpdateAssemblyVersions
|
|
variables:
|
|
Ver.AssemblyVer: $[ stageDependencies.S1.CalculateVersion.outputs['Version.GitVersion_AssemblySemVer'] ] # Note the 'stageDependencies.<jobName>' syntax.
|
|
```
|