GitTools/actions
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve GitVersion examples

Browse Source 
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
2020-11-22 22:00:53 +00:00
committed by Artur
parent a448a9f0a2
commit a33003e772
4 changed files with 409 additions and 393 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
docs/examples/azure/gitversion/execute/usage-examples.md
View File

@@ -2,6 +2,8 @@
Find out how to use the **gitversion/execute** task using the examples below. 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 ## Inputs
The Execute GitVersion task accepts the following 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.UncommittedChanges (since 5.5.0)
- GitVersion.CommitDate - 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`.** **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 ## Examples
- Example 1: Calculate the version for the build. ### Example 1
```yaml Calculate the version for the build.
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Determine Version 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 Calculate the version for the build using a config file with the default name **GitVersion.yml**.
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Determine Version steps:
inputs: # gitversion/setup@0 task omitted for brevity.
useConfigFile: true
```
Example contents of **GitVersion.yml**: - task: gitversion/execute@0
displayName: Determine Version
inputs:
useConfigFile: true
```
```yaml Example contents of **GitVersion.yml**:
mode: Mainline
branches:
master:
regex: ^latest$
pull-request:
tag: pr
```
--- ```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 Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Determine Version steps:
inputs: # gitversion/setup@0 task omitted for brevity.
useConfigFile: true
configFilePath: 'VersionConfig.yml'
```
--- - 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 Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Display GitVersion config steps:
inputs: # gitversion/setup@0 task omitted for brevity.
additionalArguments: '/showConfig'
```
--- - 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 Calculate the version for the build and display all the calculated variables in the next step.
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Determine Version steps:
# gitversion/setup@0 task omitted for brevity.
- script: | - task: gitversion/execute@0
echo Major: $(GitVersion.Major) displayName: Determine Version
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)
```
--- - 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 Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version.
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Determine Version steps:
# gitversion/setup@0 task omitted for brevity.
- task: DotNetCoreCLI@2 - task: gitversion/execute@0
displayName: Pack Example displayName: Determine Version
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: 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 Calculate the version for the build and use the `GitVersion.BranchName` variable in a condition for starting another job.
job: CalculateVersion
displayName: Calculate version using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Use GitVersion job: CalculateVersion
name: Version # the step MUST be named to access its output variables in another job. displayName: Calculate version using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
job: CreateReleaseNotes - task: gitversion/execute@0
condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion.BranchName'], 'main') displayName: Use GitVersion
dependsOn: CalculateVersion 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 Calculate the version for the build and map the `GitVersion.SemVer` variable into a variable in another job.
job: CalculateVersion
displayName: Calculate version using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Use GitVersion job: CalculateVersion
name: Version # the step MUST be named to access its output variables in another job. displayName: Calculate version using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
job: BuildAndPack - task: gitversion/execute@0
variables: displayName: Use GitVersion
Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion.MajorMinorPatch'] ] 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 Calculate the version for the build and use the `GitVersion.Major` output variable in a condition for starting another stage.
stages:
- stage: S1
jobs:
- job: CalculateVersion
displayName: Calculate version number using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Use GitVersion stages:
name: Version # the step MUST be named to access its output variables in another stage. - stage: S1
jobs:
- job: CalculateVersion
displayName: Calculate version number using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
- stage: S2 - task: gitversion/execute@0
condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion.Major'], 0)) displayName: Use GitVersion
dependsOn: S1 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 Calculate the version for the build and map the `GitVersion.AssemblySemVer` variable into a variable in another job for a different stage.
stages:
- stage: S1
jobs:
- job: CalculateVersion
displayName: Calculate version number using GitVersion
steps:
# gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 ```yaml
displayName: Use GitVersion stages:
name: Version # the step MUST be named to access its output variables in another stage. - stage: S1
- stage: S2 jobs:
dependsOn: S1 - job: CalculateVersion
jobs: displayName: Calculate version number using GitVersion
- job: UpdateAssemblyVersions steps:
variables: # gitversion/setup@0 task omitted for brevity.
Ver.AssemblyVer: $[ stageDependencies.S1.CalculateVersion.outputs['Version.GitVersion.AssemblySemVer'] ] # Note the 'stageDependencies.<jobName>' syntax.
``` - 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.
```

58
docs/examples/azure/gitversion/setup/usage-examples.md
View File

@@ -2,6 +2,8 @@
Find out how to use the **gitversion/setup** task using the examples below. 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 ## Inputs
The Setup GitVersion task accepts the following inputs: The Setup GitVersion task accepts the following inputs:
@@ -21,37 +23,39 @@ includePrerelease:
## Usage examples ## Usage examples
- Example 1: Install the latest GitVersion 5 version. ### Example 1
```yaml Install the latest GitVersion 5 version.
steps:
- task: gitversion/setup@0
displayName: Install GitVersion
inputs:
versionSpec: '5.x'
```
--- ```yaml
steps:
- task: gitversion/setup@0
displayName: Install GitVersion
inputs:
versionSpec: '5.x'
```
- Example 2: Install GitVersion 5.5.0. ### Example 2
```yaml Install GitVersion 5.5.0.
steps:
- task: gitversion/setup@0
displayName: Install GitVersion
inputs:
versionSpec: '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 Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
steps:
- task: gitversion/setup@0 ```yaml
displayName: Install GitVersion steps:
inputs: - task: gitversion/setup@0
versionSpec: '6.x' displayName: Install GitVersion
includePrerelease: true inputs:
``` versionSpec: '6.x'
includePrerelease: true
```

344
docs/examples/github/gitversion/execute/usage-examples.md
View File

@@ -12,6 +12,8 @@ steps:
fetch-depth: 0 fetch-depth: 0
``` ```
This step is omitted from the examples for brevity.
> The examples use version _0.9.6_ of the GitVersion Execute action. It is recommended to use the latest released version in your own workflows. > The examples use version _0.9.6_ of the GitVersion Execute action. It is recommended to use the latest released version in your own workflows.
## Inputs ## Inputs
@@ -82,196 +84,200 @@ The Execute GitVersion action creates the following outputs:
- uncommittedChanges (since 5.5.0) - uncommittedChanges (since 5.5.0)
- commitDate - commitDate
The outputs can be accessed using the syntax `${{ steps.<id>.outputs.<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. The outputs can be accessed using the syntax `${{ steps.<id>.outputs.<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 `GITVERSION_<OUTPUTNAME>` for use by other steps in the same job. See example 6. The action also creates environment variables of the form `GITVERSION_<OUTPUTNAME>` for use by other steps in the same job. See example [6](#example-6).
The outputs can be accessed across jobs by mapping them to job outputs and referencing the job outputs using the `needs` context in dependent jobs. See examples 7 and 8. The outputs can be accessed across jobs by mapping them to job outputs and referencing the job outputs using the `needs` context in dependent jobs. See examples [7](#example-7) and [8](#example-8).
--- ---
## Examples ## Examples
- Example 1: Calculate the version for the build. ### Example 1
```yaml Calculate the version for the build.
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.9.6
```
### Example 2
Calculate the version for the build using a config file with the default name **GitVersion.yml**.
```yaml
steps:
- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.9.6
with:
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@v0.9.6 action omitted for brevity.
- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.9.6
with:
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@v0.9.6 action omitted for brevity.
- name: Display GitVersion config
uses: gittools/actions/gitversion/execute@v0.9.6
with:
useConfigFile: true
additionalArguments: '/showConfig'
```
### Example 5
Calculate the version for the build and display all the calculated variables in the next step.
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version
id: gitversion
uses: gittools/actions/gitversion/execute@v0.9.6
- name: Display GitVersion outputs
run: |
echo "Major: ${{ steps.gitversion.outputs.major }}"
echo "Minor: ${{ steps.gitversion.outputs.minor }}"
echo "Patch: ${{ steps.gitversion.outputs.patch }}"
echo "PreReleaseTag: ${{ steps.gitversion.outputs.preReleaseTag }}"
echo "PreReleaseTagWithDash: ${{ steps.gitversion.outputs.preReleaseTagWithDash }}"
echo "PreReleaseLabel: ${{ steps.gitversion.outputs.preReleaseLabel }}"
echo "PreReleaseNumber: ${{ steps.gitversion.outputs.preReleaseNumber }}"
echo "WeightedPreReleaseNumber: ${{ steps.gitversion.outputs.weightedPreReleaseNumber }}"
echo "BuildMetaData: ${{ steps.gitversion.outputs.buildMetaData }}"
echo "BuildMetaDataPadded: ${{ steps.gitversion.outputs.buildMetaDataPadded }}"
echo "FullBuildMetaData: ${{ steps.gitversion.outputs.fullBuildMetaData }}"
echo "MajorMinorPatch: ${{ steps.gitversion.outputs.majorMinorPatch }}"
echo "SemVer: ${{ steps.gitversion.outputs.semVer }}"
echo "LegacySemVer: ${{ steps.gitversion.outputs.legacySemVer }}"
echo "LegacySemVerPadded: ${{ steps.gitversion.outputs.legacySemVerPadded }}"
echo "AssemblySemVer: ${{ steps.gitversion.outputs.assemblySemVer }}"
echo "AssemblySemFileVer: ${{ steps.gitversion.outputs.assemblySemFileVer }}"
echo "FullSemVer: ${{ steps.gitversion.outputs.fullSemVer }}"
echo "InformationalVersion: ${{ steps.gitversion.outputs.informationalVersion }}"
echo "BranchName: ${{ steps.gitversion.outputs.branchName }}"
echo "EscapedBranchName: ${{ steps.gitversion.outputs.escapedBranchName }}"
echo "Sha: ${{ steps.gitversion.outputs.sha }}"
echo "ShortSha: ${{ steps.gitversion.outputs.shortSha }}"
echo "NuGetVersionV2: ${{ steps.gitversion.outputs.nuGetVersionV2 }}"
echo "NuGetVersion: ${{ steps.gitversion.outputs.nuGetVersion }}"
echo "NuGetPreReleaseTagV2: ${{ steps.gitversion.outputs.nuGetPreReleaseTagV2 }}"
echo "NuGetPreReleaseTag: ${{ steps.gitversion.outputs.nuGetPreReleaseTag }}"
echo "VersionSourceSha: ${{ steps.gitversion.outputs.versionSourceSha }}"
echo "CommitsSinceVersionSource: ${{ steps.gitversion.outputs.commitsSinceVersionSource }}"
echo "CommitsSinceVersionSourcePadded: ${{ steps.gitversion.outputs.commitsSinceVersionSourcePadded }}"
echo "UncommittedChanges: ${{ steps.gitversion.outputs.uncommittedChanges }}"
echo "CommitDate: ${{ steps.gitversion.outputs.commitDate }}"
```
### Example 6
Calculate the version for the build and display the value of the `GITVERSION_SEMVER` environment variable.
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.9.6
- name: Display SemVer
run: |
echo "SemVer: $GITVERSION_SEMVER"
```
### Example 7
Calculate the version for the build and use the `branchName` output in a condition for starting another job.
```yaml
jobs:
calculate-version:
name: Calculate Version
runs-on: ubuntu-latest
outputs:
branchName: ${{ steps.gitversion.outputs.branchName }} # To use an output in another job, you have to map it to a job output.
steps: steps:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/execute step omitted for brevity
- name: Determine Version - name: Determine Version
id: gitversion
uses: gittools/actions/gitversion/execute@v0.9.6 uses: gittools/actions/gitversion/execute@v0.9.6
```
--- create-release-notes:
name: Create Release Notes
- Example 2: Calculate the version for the build using a config file with the default name **GitVersion.yml**. runs-on: ubuntu-latest
needs: calculate-version
```yaml if: contains(needs.calculate-version.outputs.branchName, 'main') # Output variable accessed via `needs` context.
steps: steps:
- name: Determine Version - run: |
uses: gittools/actions/gitversion/execute@v0.9.6 # Output variables can also be accessed in steps, using an expression.
with: echo "Creating release notes for ${{ needs.calculate-version.outputs.branchName }} branch."
useConfigFile: true ```
```
Example contents of **yml**: ### Example 8
```yaml Calculate the version for the build and map the `semVer` output into an environment variable in another job.
mode: Mainline
branches:
master:
regex: ^latest$
pull-request:
tag: pr
```
--- ```yaml
jobs:
- Example 3: Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder. calculate-version:
name: Calculate Version
```yaml runs-on: ubuntu-latest
outputs:
semVer: ${{ steps.gitversion.outputs.semVer }}
steps: steps:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/execute step omitted for brevity
- name: Determine Version - name: Determine Version
id: gitversion
uses: gittools/actions/gitversion/execute@v0.9.6 uses: gittools/actions/gitversion/execute@v0.9.6
with:
useConfigFile: true
configFilePath: VersionConfig.yml
```
--- display-semver:
name: Display Semantic Version
- Example 4: Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument). runs-on: ubuntu-latest
needs: calculate-version
```yaml env:
SEMVER: ${{ needs.calculate-version.outputs.semVer }}
steps: steps:
# gitversion/setup@v0.9.6 action omitted for brevity. - name: Display version
- name: Display GitVersion config
uses: gittools/actions/gitversion/execute@v0.9.6
with:
useConfigFile: true
additionalArguments: '/showConfig'
```
---
- Example 5: Calculate the version for the build and display all the calculated variables in the next step.
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version
id: gitversion
uses: gittools/actions/gitversion/execute@v0.9.6
- name: Display GitVersion outputs
run: | run: |
echo "Major: ${{ steps.gitversion.outputs.major }}" echo SemVer: $SEMVER
echo "Minor: ${{ steps.gitversion.outputs.minor }}" ```
echo "Patch: ${{ steps.gitversion.outputs.patch }}"
echo "PreReleaseTag: ${{ steps.gitversion.outputs.preReleaseTag }}"
echo "PreReleaseTagWithDash: ${{ steps.gitversion.outputs.preReleaseTagWithDash }}"
echo "PreReleaseLabel: ${{ steps.gitversion.outputs.preReleaseLabel }}"
echo "PreReleaseNumber: ${{ steps.gitversion.outputs.preReleaseNumber }}"
echo "WeightedPreReleaseNumber: ${{ steps.gitversion.outputs.weightedPreReleaseNumber }}"
echo "BuildMetaData: ${{ steps.gitversion.outputs.buildMetaData }}"
echo "BuildMetaDataPadded: ${{ steps.gitversion.outputs.buildMetaDataPadded }}"
echo "FullBuildMetaData: ${{ steps.gitversion.outputs.fullBuildMetaData }}"
echo "MajorMinorPatch: ${{ steps.gitversion.outputs.majorMinorPatch }}"
echo "SemVer: ${{ steps.gitversion.outputs.semVer }}"
echo "LegacySemVer: ${{ steps.gitversion.outputs.legacySemVer }}"
echo "LegacySemVerPadded: ${{ steps.gitversion.outputs.legacySemVerPadded }}"
echo "AssemblySemVer: ${{ steps.gitversion.outputs.assemblySemVer }}"
echo "AssemblySemFileVer: ${{ steps.gitversion.outputs.assemblySemFileVer }}"
echo "FullSemVer: ${{ steps.gitversion.outputs.fullSemVer }}"
echo "InformationalVersion: ${{ steps.gitversion.outputs.informationalVersion }}"
echo "BranchName: ${{ steps.gitversion.outputs.branchName }}"
echo "EscapedBranchName: ${{ steps.gitversion.outputs.escapedBranchName }}"
echo "Sha: ${{ steps.gitversion.outputs.sha }}"
echo "ShortSha: ${{ steps.gitversion.outputs.shortSha }}"
echo "NuGetVersionV2: ${{ steps.gitversion.outputs.nuGetVersionV2 }}"
echo "NuGetVersion: ${{ steps.gitversion.outputs.nuGetVersion }}"
echo "NuGetPreReleaseTagV2: ${{ steps.gitversion.outputs.nuGetPreReleaseTagV2 }}"
echo "NuGetPreReleaseTag: ${{ steps.gitversion.outputs.nuGetPreReleaseTag }}"
echo "VersionSourceSha: ${{ steps.gitversion.outputs.versionSourceSha }}"
echo "CommitsSinceVersionSource: ${{ steps.gitversion.outputs.commitsSinceVersionSource }}"
echo "CommitsSinceVersionSourcePadded: ${{ steps.gitversion.outputs.commitsSinceVersionSourcePadded }}"
echo "UncomittedChanges: ${{ steps.gitversion.outputs.uncomittedChanges }}"
echo "CommitDate: ${{ steps.gitversion.outputs.commitDate }}"
```
- Example 6: Calculate the version for the build and display the value of the `GITVERSION_SEMVER` environment variable.
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version
uses: gittools/actions/gitversion/execute@v0.9.6
- name: Display SemVer
run: |
echo "SemVer: $GITVERSION_SEMVER"
```
---
- Example 7: Calculate the version for the build and use the `branchName` output in a condition for starting another job.
````yaml
jobs:
calculate-version:
name: Calculate Version
runs-on: ubuntu-latest
outputs:
branchName: ${{ steps.gitversion.outputs.branchName }} # To use an output in another job, you have to map it to a job output.
steps:
# gitversion/execute step omitted for brevity
- name: Determine Version
id: gitversion
uses: gittools/actions/gitversion/execute@v0.9.6
create-release-notes:
name: Create Release Notes
runs-on: ubuntu-latest
needs: calculate-version
if: contains(needs.calculate-version.outputs.branchName, 'main') # Output variable accessed via `needs` context.
steps:
- run: |
# Output variables can also be accessed in steps, using an expression.
echo "Creating release notes for ${{ needs.calculate-version.outputs.branchName }} branch."
```
---
- Example 8: Calculate the version for the build and map the `semVer` output into an environment variable in another job.
```yaml
jobs:
calculate-version:
name: Calculate Version
runs-on: ubuntu-latest
outputs:
semVer: ${{ steps.gitversion.outputs.semVer }}
steps:
# gitversion/execute step omitted for brevity
- name: Determine Version
id: gitversion
uses: gittools/actions/gitversion/execute@v0.9.6
display-semver:
name: Display Semantic Version
runs-on: ubuntu-latest
needs: calculate-version
env:
SEMVER: ${{ needs.calculate-version.outputs.semVer }}
steps:
- name: Display version
run: |
echo SemVer: $SEMVER
```

56
docs/examples/github/gitversion/setup/usage-examples.md
View File

@@ -23,37 +23,39 @@ includePrerelease:
## Usage examples ## Usage examples
- Example 1: Install the latest GitVersion 5 version. ### Example 1
```yaml Install the latest GitVersion 5 version.
steps:
- name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6
with:
versionSpec: '5.x'
```
--- ```yaml
steps:
- name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6
with:
versionSpec: '5.x'
```
- Example 2: Install GitVersion 5.5.0. ### Example 2
```yaml Install GitVersion 5.5.0.
steps:
- name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6
with:
versionSpec: '5.5.0'
```
--- ```yaml
steps:
- name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6
with:
versionSpec: '5.5.0'
```
- Example 3: Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**. ### Example 3
```yaml Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
steps:
- name: Install GitVersion ```yaml
uses: gittools/actions/gitversion/setup@v0.9.6 steps:
with: - name: Install GitVersion
versionSpec: '6.x' uses: gittools/actions/gitversion/setup@v0.9.6
includePrerelease: true with:
``` versionSpec: '6.x'
includePrerelease: true
```