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,47 +82,49 @@ 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:
```yaml
steps:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
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:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
displayName: Determine Version displayName: Determine Version
inputs: inputs:
useConfigFile: true useConfigFile: true
``` ```
Example contents of **GitVersion.yml**: Example contents of **GitVersion.yml**:
```yaml ```yaml
mode: Mainline mode: Mainline
branches: branches:
master: master:
regex: ^latest$ regex: ^latest$
pull-request: pull-request:
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:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
@@ -128,28 +132,28 @@ The multi-job output variables can be accessed across jobs and stages, in both c
inputs: inputs:
useConfigFile: true useConfigFile: true
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:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
displayName: Display GitVersion config displayName: Display GitVersion config
inputs: inputs:
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:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
@@ -186,16 +190,16 @@ 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:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
@@ -208,52 +212,52 @@ The multi-job output variables can be accessed across jobs and stages, in both c
packagesToPack: src/Example/LibExample.csproj packagesToPack: src/Example/LibExample.csproj
versioningScheme: byEnvVar versioningScheme: byEnvVar
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:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
displayName: Use GitVersion displayName: Use GitVersion
name: Version # the step MUST be named to access its output variables in another job. name: Version # the step MUST be named to access its output variables in another job.
job: CreateReleaseNotes job: CreateReleaseNotes
condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion.BranchName'], 'main') condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion.BranchName'], 'main')
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
displayName: Calculate version using GitVersion displayName: Calculate version using GitVersion
steps: steps:
# gitversion/setup@0 task omitted for brevity. # gitversion/setup@0 task omitted for brevity.
- task: gitversion/execute@0 - task: gitversion/execute@0
displayName: Use GitVersion displayName: Use GitVersion
name: Version # the step MUST be named to access its output variables in another job. name: Version # the step MUST be named to access its output variables in another job.
job: BuildAndPack job: BuildAndPack
variables: variables:
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:
- job: CalculateVersion - job: CalculateVersion
@@ -268,14 +272,14 @@ The multi-job output variables can be accessed across jobs and stages, in both c
- stage: S2 - stage: S2
condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion.Major'], 0)) condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion.Major'], 0))
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:
- stage: S1 - stage: S1
jobs: jobs:
- job: CalculateVersion - job: CalculateVersion
@@ -292,4 +296,4 @@ The multi-job output variables can be accessed across jobs and stages, in both c
- job: UpdateAssemblyVersions - job: UpdateAssemblyVersions
variables: variables:
Ver.AssemblyVer: $[ stageDependencies.S1.CalculateVersion.outputs['Version.GitVersion.AssemblySemVer'] ] # Note the 'stageDependencies.<jobName>' syntax. Ver.AssemblyVer: $[ stageDependencies.S1.CalculateVersion.outputs['Version.GitVersion.AssemblySemVer'] ] # Note the 'stageDependencies.<jobName>' syntax.
``` ```

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:
```yaml
steps:
- task: gitversion/setup@0 - task: gitversion/setup@0
displayName: Install GitVersion displayName: Install GitVersion
inputs: inputs:
versionSpec: '5.x' versionSpec: '5.x'
``` ```
--- ### Example 2
- Example 2: Install GitVersion 5.5.0. Install GitVersion 5.5.0.
```yaml ```yaml
steps: steps:
- task: gitversion/setup@0 - task: gitversion/setup@0
displayName: Install GitVersion displayName: Install GitVersion
inputs: inputs:
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:
- task: gitversion/setup@0 - task: gitversion/setup@0
displayName: Install GitVersion displayName: Install GitVersion
inputs: inputs:
versionSpec: '6.x' versionSpec: '6.x'
includePrerelease: true includePrerelease: true
``` ```

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,55 +84,57 @@ 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.
steps:
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version - name: Determine Version
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:
- name: Determine Version - name: Determine Version
uses: gittools/actions/gitversion/execute@v0.9.6 uses: gittools/actions/gitversion/execute@v0.9.6
with: with:
useConfigFile: true useConfigFile: true
``` ```
Example contents of **yml**: Example contents of **GitVersion.yml**:
```yaml ```yaml
mode: Mainline mode: Mainline
branches: branches:
master: master:
regex: ^latest$ regex: ^latest$
pull-request: pull-request:
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:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version - name: Determine Version
@@ -138,14 +142,14 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
with: with:
useConfigFile: true useConfigFile: true
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:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/setup@v0.9.6 action omitted for brevity.
- name: Display GitVersion config - name: Display GitVersion config
@@ -153,14 +157,14 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
with: with:
useConfigFile: true useConfigFile: true
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:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version - name: Determine Version
@@ -199,14 +203,16 @@ 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
```yaml Calculate the version for the build and display the value of the `GITVERSION_SEMVER` environment variable.
steps:
```yaml
steps:
# gitversion/setup@v0.9.6 action omitted for brevity. # gitversion/setup@v0.9.6 action omitted for brevity.
- name: Determine Version - name: Determine Version
@@ -215,14 +221,14 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
- name: Display SemVer - name: Display SemVer
run: | run: |
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
runs-on: ubuntu-latest runs-on: ubuntu-latest
@@ -244,14 +250,14 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
- run: | - run: |
# Output variables can also be accessed in steps, using an expression. # Output variables can also be accessed in steps, using an expression.
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:
calculate-version: calculate-version:
name: Calculate Version name: Calculate Version
runs-on: ubuntu-latest runs-on: ubuntu-latest
@@ -274,4 +280,4 @@ The outputs can be accessed across jobs by mapping them to job outputs and refer
- name: Display version - name: Display version
run: | run: |
echo SemVer: $SEMVER echo SemVer: $SEMVER
``` ```

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:
```yaml
steps:
- name: Install GitVersion - name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6 uses: gittools/actions/gitversion/setup@v0.9.6
with: with:
versionSpec: '5.x' versionSpec: '5.x'
``` ```
--- ### Example 2
- Example 2: Install GitVersion 5.5.0. Install GitVersion 5.5.0.
```yaml ```yaml
steps: steps:
- name: Install GitVersion - name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6 uses: gittools/actions/gitversion/setup@v0.9.6
with: with:
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:
- name: Install GitVersion - name: Install GitVersion
uses: gittools/actions/gitversion/setup@v0.9.6 uses: gittools/actions/gitversion/setup@v0.9.6
with: with:
versionSpec: '6.x' versionSpec: '6.x'
includePrerelease: true includePrerelease: true
``` ```