Improve GitVersion examples
Improved the GitVersion examples by using headings for the examples (with links) and fixing a couple of typos.
This commit is contained in:
Chris Davis
Artur
@@ -2,6 +2,8 @@
|
||||
|
||||
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.
|
||||
|
||||
## Inputs
|
||||
|
||||
The Execute GitVersion task accepts the following inputs:
|
||||
@@ -70,9 +72,9 @@ The Execute GitVersion task creates the following job-scoped variables and multi
|
||||
- GitVersion.UncommittedChanges (since 5.5.0)
|
||||
- GitVersion.CommitDate
|
||||
|
||||
The job-scoped variables can be accessed using the macro syntax `$(GitVersion.<variableName>)` in subsequent steps in the same job. Azure Pipelines also creates environment variables of the form `GITVERSION_<VARIABLENAME>`. See examples 5 and 6.
|
||||
The job-scoped variables can be accessed using the macro syntax `$(GitVersion.<variableName>)` in subsequent steps in the same job. Azure Pipelines also creates environment variables of the form `GITVERSION_<VARIABLENAME>`. See examples [5](#example-5) and [6](#example-6).
|
||||
|
||||
The multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples 7 to 10.
|
||||
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`.**
|
||||
|
||||
@@ -80,216 +82,218 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
||||
|
||||
## Examples
|
||||
|
||||
- Example 1: Calculate the version for the build.
|
||||
### Example 1
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
```
|
||||
```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**.
|
||||
### Example 2
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
inputs:
|
||||
useConfigFile: true
|
||||
```
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
|
||||
Example contents of **GitVersion.yml**:
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
inputs:
|
||||
useConfigFile: true
|
||||
```
|
||||
|
||||
```yaml
|
||||
mode: Mainline
|
||||
branches:
|
||||
master:
|
||||
regex: ^latest$
|
||||
pull-request:
|
||||
tag: pr
|
||||
```
|
||||
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.
|
||||
### Example 3
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
inputs:
|
||||
useConfigFile: true
|
||||
configFilePath: 'VersionConfig.yml'
|
||||
```
|
||||
```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).
|
||||
### Example 4
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Display GitVersion config
|
||||
inputs:
|
||||
additionalArguments: '/showConfig'
|
||||
```
|
||||
```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.
|
||||
### Example 5
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build and display all the calculated variables in the next step.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
|
||||
- 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 UncomittedChanges: $(GitVersion.UncomittedChanges)
|
||||
echo CommitDate: $(GitVersion.CommitDate)
|
||||
```
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
|
||||
---
|
||||
- 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)
|
||||
```
|
||||
|
||||
- Example 6: Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version.
|
||||
### Example 6
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
|
||||
- task: DotNetCoreCLI@2
|
||||
displayName: Pack Example
|
||||
inputs:
|
||||
command: pack
|
||||
packagesToPack: src/Example/LibExample.csproj
|
||||
versioningScheme: byEnvVar
|
||||
versionEnvVar: GitVersion.NuGetVersion # alternative syntax GITVERSION_NUGETVERSION (the former gets converted into the latter internally)
|
||||
```
|
||||
- task: gitversion/execute@0
|
||||
displayName: Determine Version
|
||||
|
||||
---
|
||||
- task: DotNetCoreCLI@2
|
||||
displayName: Pack Example
|
||||
inputs:
|
||||
command: pack
|
||||
packagesToPack: src/Example/LibExample.csproj
|
||||
versioningScheme: byEnvVar
|
||||
versionEnvVar: GitVersion.NuGetVersion # alternative syntax GITVERSION_NUGETVERSION (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.
|
||||
### Example 7
|
||||
|
||||
````yaml
|
||||
job: CalculateVersion
|
||||
displayName: Calculate version using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build and use the `GitVersion.BranchName` variable in a condition for starting another job.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Use GitVersion
|
||||
name: Version # the step MUST be named to access its output variables in another job.
|
||||
```yaml
|
||||
job: CalculateVersion
|
||||
displayName: Calculate version using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
|
||||
job: CreateReleaseNotes
|
||||
condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion.BranchName'], 'main')
|
||||
dependsOn: CalculateVersion
|
||||
```
|
||||
- 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.
|
||||
### Example 8
|
||||
|
||||
```yaml
|
||||
job: CalculateVersion
|
||||
displayName: Calculate version using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build and map the `GitVersion.SemVer` variable into a variable in another job.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Use GitVersion
|
||||
name: Version # the step MUST be named to access its output variables in another job.
|
||||
```yaml
|
||||
job: CalculateVersion
|
||||
displayName: Calculate version using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
|
||||
job: BuildAndPack
|
||||
variables:
|
||||
Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion.MajorMinorPatch'] ]
|
||||
```
|
||||
- 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.
|
||||
### Example 9
|
||||
|
||||
````yaml
|
||||
stages:
|
||||
- stage: S1
|
||||
jobs:
|
||||
- job: CalculateVersion
|
||||
displayName: Calculate version number using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build and use the `GitVersion.Major` output variable in a condition for starting another stage.
|
||||
|
||||
- task: gitversion/execute@0
|
||||
displayName: Use GitVersion
|
||||
name: Version # the step MUST be named to access its output variables in another stage.
|
||||
```yaml
|
||||
stages:
|
||||
- stage: S1
|
||||
jobs:
|
||||
- job: CalculateVersion
|
||||
displayName: Calculate version number using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
|
||||
- stage: S2
|
||||
condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion.Major'], 0))
|
||||
dependsOn: S1
|
||||
```
|
||||
- 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.
|
||||
### Example 10
|
||||
|
||||
```yaml
|
||||
stages:
|
||||
- stage: S1
|
||||
jobs:
|
||||
- job: CalculateVersion
|
||||
displayName: Calculate version number using GitVersion
|
||||
steps:
|
||||
# gitversion/setup@0 task omitted for brevity.
|
||||
Calculate the version for the build and map the `GitVersion.AssemblySemVer` variable into a variable in another job for a different stage.
|
||||
|
||||
- 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.
|
||||
```
|
||||
```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.
|
||||
```
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
Find out how to use the **gitversion/setup** task using the examples below.
|
||||
|
||||
> The examples use the latest _0.x_ version of the GitVersion Setup task. It is recommended to use the latest released version in your own pipelines.
|
||||
|
||||
## Inputs
|
||||
|
||||
The Setup GitVersion task accepts the following inputs:
|
||||
@@ -21,37 +23,39 @@ includePrerelease:
|
||||
|
||||
## Usage examples
|
||||
|
||||
- Example 1: Install the latest GitVersion 5 version.
|
||||
### Example 1
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- task: gitversion/setup@0
|
||||
displayName: Install GitVersion
|
||||
inputs:
|
||||
versionSpec: '5.x'
|
||||
```
|
||||
Install the latest GitVersion 5 version.
|
||||
|
||||
---
|
||||
```yaml
|
||||
steps:
|
||||
- task: gitversion/setup@0
|
||||
displayName: Install GitVersion
|
||||
inputs:
|
||||
versionSpec: '5.x'
|
||||
```
|
||||
|
||||
- Example 2: Install GitVersion 5.5.0.
|
||||
### Example 2
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- task: gitversion/setup@0
|
||||
displayName: Install GitVersion
|
||||
inputs:
|
||||
versionSpec: '5.5.0'
|
||||
```
|
||||
Install GitVersion 5.5.0.
|
||||
|
||||
---
|
||||
```yaml
|
||||
steps:
|
||||
- task: gitversion/setup@0
|
||||
displayName: Install GitVersion
|
||||
inputs:
|
||||
versionSpec: '5.5.0'
|
||||
```
|
||||
|
||||
- Example 3: Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
|
||||
### Example 3
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- task: gitversion/setup@0
|
||||
displayName: Install GitVersion
|
||||
inputs:
|
||||
versionSpec: '6.x'
|
||||
includePrerelease: true
|
||||
```
|
||||
Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- task: gitversion/setup@0
|
||||
displayName: Install GitVersion
|
||||
inputs:
|
||||
versionSpec: '6.x'
|
||||
includePrerelease: true
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user