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:
@@ -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,7 +82,9 @@ 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
|
||||||
|
|
||||||
|
Calculate the version for the build.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -90,9 +94,9 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
displayName: Determine Version
|
displayName: Determine Version
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 2
|
||||||
|
|
||||||
- Example 2: Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -115,9 +119,9 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
tag: pr
|
tag: pr
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 3
|
||||||
|
|
||||||
- Example 3: Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
|
Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -130,9 +134,9 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
configFilePath: 'VersionConfig.yml'
|
configFilePath: 'VersionConfig.yml'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 4
|
||||||
|
|
||||||
- Example 4: Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -144,9 +148,9 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
additionalArguments: '/showConfig'
|
additionalArguments: '/showConfig'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 5
|
||||||
|
|
||||||
- Example 5: Calculate the version for the build and display all the calculated variables in the next step.
|
Calculate the version for the build and display all the calculated variables in the next step.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -186,13 +190,13 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
echo VersionSourceSha: $(GitVersion.VersionSourceSha)
|
echo VersionSourceSha: $(GitVersion.VersionSourceSha)
|
||||||
echo CommitsSinceVersionSource: $(GitVersion.CommitsSinceVersionSource)
|
echo CommitsSinceVersionSource: $(GitVersion.CommitsSinceVersionSource)
|
||||||
echo CommitsSinceVersionSourcePadded: $(GitVersion.CommitsSinceVersionSourcePadded)
|
echo CommitsSinceVersionSourcePadded: $(GitVersion.CommitsSinceVersionSourcePadded)
|
||||||
echo UncomittedChanges: $(GitVersion.UncomittedChanges)
|
echo UncommittedChanges: $(GitVersion.UncommittedChanges)
|
||||||
echo CommitDate: $(GitVersion.CommitDate)
|
echo CommitDate: $(GitVersion.CommitDate)
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 6
|
||||||
|
|
||||||
- Example 6: Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version.
|
Calculate the version for the build and use the `GitVersion.NuGetVersion` variable to set the NuGet package version.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -210,11 +214,11 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
versionEnvVar: GitVersion.NuGetVersion # alternative syntax GITVERSION_NUGETVERSION (the former gets converted into the latter internally)
|
versionEnvVar: GitVersion.NuGetVersion # alternative syntax GITVERSION_NUGETVERSION (the former gets converted into the latter internally)
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 7
|
||||||
|
|
||||||
- Example 7: Calculate the version for the build and use the `GitVersion.BranchName` variable in a condition for starting another job.
|
Calculate the version for the build and use the `GitVersion.BranchName` variable in a condition for starting another job.
|
||||||
|
|
||||||
````yaml
|
```yaml
|
||||||
job: CalculateVersion
|
job: CalculateVersion
|
||||||
displayName: Calculate version using GitVersion
|
displayName: Calculate version using GitVersion
|
||||||
steps:
|
steps:
|
||||||
@@ -229,9 +233,9 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
dependsOn: CalculateVersion
|
dependsOn: CalculateVersion
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 8
|
||||||
|
|
||||||
- Example 8: Calculate the version for the build and map the `GitVersion.SemVer` variable into a variable in another job.
|
Calculate the version for the build and map the `GitVersion.SemVer` variable into a variable in another job.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
job: CalculateVersion
|
job: CalculateVersion
|
||||||
@@ -248,11 +252,11 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion.MajorMinorPatch'] ]
|
Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion.MajorMinorPatch'] ]
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 9
|
||||||
|
|
||||||
- Example 9: Calculate the version for the build and use the `GitVersion.Major` output variable in a condition for starting another stage.
|
Calculate the version for the build and use the `GitVersion.Major` output variable in a condition for starting another stage.
|
||||||
|
|
||||||
````yaml
|
```yaml
|
||||||
stages:
|
stages:
|
||||||
- stage: S1
|
- stage: S1
|
||||||
jobs:
|
jobs:
|
||||||
@@ -270,9 +274,9 @@ The multi-job output variables can be accessed across jobs and stages, in both c
|
|||||||
dependsOn: S1
|
dependsOn: S1
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 10
|
||||||
|
|
||||||
- Example 10: Calculate the version for the build and map the `GitVersion.AssemblySemVer` variable into a variable in another job for a different stage.
|
Calculate the version for the build and map the `GitVersion.AssemblySemVer` variable into a variable in another job for a different stage.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
stages:
|
stages:
|
||||||
|
|||||||
@@ -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,7 +23,9 @@ includePrerelease:
|
|||||||
|
|
||||||
## Usage examples
|
## Usage examples
|
||||||
|
|
||||||
- Example 1: Install the latest GitVersion 5 version.
|
### Example 1
|
||||||
|
|
||||||
|
Install the latest GitVersion 5 version.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -31,9 +35,9 @@ includePrerelease:
|
|||||||
versionSpec: '5.x'
|
versionSpec: '5.x'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 2
|
||||||
|
|
||||||
- Example 2: Install GitVersion 5.5.0.
|
Install GitVersion 5.5.0.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -43,9 +47,9 @@ includePrerelease:
|
|||||||
versionSpec: '5.5.0'
|
versionSpec: '5.5.0'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 3
|
||||||
|
|
||||||
- Example 3: Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
|
Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
|
|||||||
@@ -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,17 +84,19 @@ 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
|
||||||
|
|
||||||
|
Calculate the version for the build.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -102,9 +106,9 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 2
|
||||||
|
|
||||||
- Example 2: Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -114,7 +118,7 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
useConfigFile: true
|
useConfigFile: true
|
||||||
```
|
```
|
||||||
|
|
||||||
Example contents of **yml**:
|
Example contents of **GitVersion.yml**:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
mode: Mainline
|
mode: Mainline
|
||||||
@@ -125,9 +129,9 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
tag: pr
|
tag: pr
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 3
|
||||||
|
|
||||||
- Example 3: Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
|
Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -140,9 +144,9 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
configFilePath: VersionConfig.yml
|
configFilePath: VersionConfig.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 4
|
||||||
|
|
||||||
- Example 4: Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -155,9 +159,9 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
additionalArguments: '/showConfig'
|
additionalArguments: '/showConfig'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 5
|
||||||
|
|
||||||
- Example 5: Calculate the version for the build and display all the calculated variables in the next step.
|
Calculate the version for the build and display all the calculated variables in the next step.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -199,11 +203,13 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
echo "VersionSourceSha: ${{ steps.gitversion.outputs.versionSourceSha }}"
|
echo "VersionSourceSha: ${{ steps.gitversion.outputs.versionSourceSha }}"
|
||||||
echo "CommitsSinceVersionSource: ${{ steps.gitversion.outputs.commitsSinceVersionSource }}"
|
echo "CommitsSinceVersionSource: ${{ steps.gitversion.outputs.commitsSinceVersionSource }}"
|
||||||
echo "CommitsSinceVersionSourcePadded: ${{ steps.gitversion.outputs.commitsSinceVersionSourcePadded }}"
|
echo "CommitsSinceVersionSourcePadded: ${{ steps.gitversion.outputs.commitsSinceVersionSourcePadded }}"
|
||||||
echo "UncomittedChanges: ${{ steps.gitversion.outputs.uncomittedChanges }}"
|
echo "UncommittedChanges: ${{ steps.gitversion.outputs.uncommittedChanges }}"
|
||||||
echo "CommitDate: ${{ steps.gitversion.outputs.commitDate }}"
|
echo "CommitDate: ${{ steps.gitversion.outputs.commitDate }}"
|
||||||
```
|
```
|
||||||
|
|
||||||
- Example 6: Calculate the version for the build and display the value of the `GITVERSION_SEMVER` environment variable.
|
### Example 6
|
||||||
|
|
||||||
|
Calculate the version for the build and display the value of the `GITVERSION_SEMVER` environment variable.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -217,11 +223,11 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
echo "SemVer: $GITVERSION_SEMVER"
|
echo "SemVer: $GITVERSION_SEMVER"
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 7
|
||||||
|
|
||||||
- Example 7: Calculate the version for the build and use the `branchName` output in a condition for starting another job.
|
Calculate the version for the build and use the `branchName` output in a condition for starting another job.
|
||||||
|
|
||||||
````yaml
|
```yaml
|
||||||
jobs:
|
jobs:
|
||||||
calculate-version:
|
calculate-version:
|
||||||
name: Calculate Version
|
name: Calculate Version
|
||||||
@@ -246,9 +252,9 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
|
|||||||
echo "Creating release notes for ${{ needs.calculate-version.outputs.branchName }} branch."
|
echo "Creating release notes for ${{ needs.calculate-version.outputs.branchName }} branch."
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 8
|
||||||
|
|
||||||
- Example 8: Calculate the version for the build and map the `semVer` output into an environment variable in another job.
|
Calculate the version for the build and map the `semVer` output into an environment variable in another job.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
jobs:
|
jobs:
|
||||||
|
|||||||
@@ -23,7 +23,9 @@ includePrerelease:
|
|||||||
|
|
||||||
## Usage examples
|
## Usage examples
|
||||||
|
|
||||||
- Example 1: Install the latest GitVersion 5 version.
|
### Example 1
|
||||||
|
|
||||||
|
Install the latest GitVersion 5 version.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -33,9 +35,9 @@ includePrerelease:
|
|||||||
versionSpec: '5.x'
|
versionSpec: '5.x'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 2
|
||||||
|
|
||||||
- Example 2: Install GitVersion 5.5.0.
|
Install GitVersion 5.5.0.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
@@ -45,9 +47,9 @@ includePrerelease:
|
|||||||
versionSpec: '5.5.0'
|
versionSpec: '5.5.0'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Example 3
|
||||||
|
|
||||||
- Example 3: Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
|
Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
steps:
|
steps:
|
||||||
|
|||||||
Reference in New Issue
Block a user