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
2020-11-22 22:00:53 +00:00
committed by Artur
parent a448a9f0a2
commit a33003e772
4 changed files with 409 additions and 393 deletions

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,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:

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,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:

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,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:

View File

@@ -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: