From a33003e7726e82bb6b8221a1a791d21c0d77fa17 Mon Sep 17 00:00:00 2001 From: Chris Davis <74455480+chris-codeflow@users.noreply.github.com> Date: Sun, 22 Nov 2020 22:00:53 +0000 Subject: [PATCH] Improve GitVersion examples Improved the GitVersion examples by using headings for the examples (with links) and fixing a couple of typos. --- .../gitversion/execute/usage-examples.md | 344 +++++++++--------- .../azure/gitversion/setup/usage-examples.md | 58 +-- .../gitversion/execute/usage-examples.md | 344 +++++++++--------- .../github/gitversion/setup/usage-examples.md | 56 +-- 4 files changed, 409 insertions(+), 393 deletions(-) diff --git a/docs/examples/azure/gitversion/execute/usage-examples.md b/docs/examples/azure/gitversion/execute/usage-examples.md index 0e87a87..34b6b26 100644 --- a/docs/examples/azure/gitversion/execute/usage-examples.md +++ b/docs/examples/azure/gitversion/execute/usage-examples.md @@ -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.)` in subsequent steps in the same job. Azure Pipelines also creates environment variables of the form `GITVERSION_`. See examples 5 and 6. +The job-scoped variables can be accessed using the macro syntax `$(GitVersion.)` in subsequent steps in the same job. Azure Pipelines also creates environment variables of the form `GITVERSION_`. 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.' 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.' syntax. +``` diff --git a/docs/examples/azure/gitversion/setup/usage-examples.md b/docs/examples/azure/gitversion/setup/usage-examples.md index de29698..758106d 100644 --- a/docs/examples/azure/gitversion/setup/usage-examples.md +++ b/docs/examples/azure/gitversion/setup/usage-examples.md @@ -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 +``` diff --git a/docs/examples/github/gitversion/execute/usage-examples.md b/docs/examples/github/gitversion/execute/usage-examples.md index 3a4a907..ed873ed 100644 --- a/docs/examples/github/gitversion/execute/usage-examples.md +++ b/docs/examples/github/gitversion/execute/usage-examples.md @@ -12,6 +12,8 @@ steps: 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. ## Inputs @@ -82,196 +84,200 @@ The Execute GitVersion action creates the following outputs: - uncommittedChanges (since 5.5.0) - commitDate -The outputs can be accessed using the syntax `${{ steps..outputs. }}`, where `` 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..outputs. }}`, where `` 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_` for use by other steps in the same job. See example 6. +The action also creates environment variables of the form `GITVERSION_` 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 -- 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: - # gitversion/setup@v0.9.6 action omitted for brevity. + # gitversion/execute step omitted for brevity - name: Determine Version + id: gitversion 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 + 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: - - name: Determine Version - uses: gittools/actions/gitversion/execute@v0.9.6 - with: - useConfigFile: true - ``` + - run: | + # Output variables can also be accessed in steps, using an expression. + echo "Creating release notes for ${{ needs.calculate-version.outputs.branchName }} branch." +``` - Example contents of **yml**: +### Example 8 - ```yaml - mode: Mainline - branches: - master: - regex: ^latest$ - pull-request: - tag: pr - ``` +Calculate the version for the build and map the `semVer` output into an environment variable in another job. ---- - -- Example 3: Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder. - - ```yaml +```yaml +jobs: + calculate-version: + name: Calculate Version + runs-on: ubuntu-latest + outputs: + semVer: ${{ steps.gitversion.outputs.semVer }} steps: - # gitversion/setup@v0.9.6 action omitted for brevity. + # gitversion/execute step omitted for brevity - name: Determine Version + id: gitversion 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 + display-semver: + name: Display Semantic Version + runs-on: ubuntu-latest + needs: calculate-version + env: + SEMVER: ${{ needs.calculate-version.outputs.semVer }} 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 + - name: Display version 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 "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 - ``` + echo SemVer: $SEMVER +``` diff --git a/docs/examples/github/gitversion/setup/usage-examples.md b/docs/examples/github/gitversion/setup/usage-examples.md index 5451893..2f6c288 100644 --- a/docs/examples/github/gitversion/setup/usage-examples.md +++ b/docs/examples/github/gitversion/setup/usage-examples.md @@ -23,37 +23,39 @@ includePrerelease: ## Usage examples -- Example 1: Install the latest GitVersion 5 version. +### Example 1 - ```yaml - steps: - - name: Install GitVersion - uses: gittools/actions/gitversion/setup@v0.9.6 - with: - versionSpec: '5.x' - ``` +Install the latest GitVersion 5 version. ---- +```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 - steps: - - name: Install GitVersion - uses: gittools/actions/gitversion/setup@v0.9.6 - with: - versionSpec: '5.5.0' - ``` +Install GitVersion 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 - steps: - - name: Install GitVersion - uses: gittools/actions/gitversion/setup@v0.9.6 - with: - versionSpec: '6.x' - includePrerelease: true - ``` +Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**. + +```yaml +steps: + - name: Install GitVersion + uses: gittools/actions/gitversion/setup@v0.9.6 + with: + versionSpec: '6.x' + includePrerelease: true +```