GitTools/actions
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
965ad03650bf55fcfae3b008b1f7a47361e77c84
actions/docs/examples/azure/gitversion/execute/usage-examples.md
Chris Davis 965ad03650 Improve reference to config file with default name
2020-11-20 13:28:50 +01:00

9.3 KiB
Raw Blame History

Execute GitVersion Task (gitversion/execute) Usage Examples

Find out how to use the gitversion/execute task using the examples below.

Task inputs

The Execute GitVersion task accepts the following inputs:

targetPath:
  description: Optionally supply the path to the working directory.
  required: false
  default: ''
useConfigFile:
  description: Whether to use a custom configuration file.
  required: false
  default: false
configFilePath:
  description: Optional path to config file (defaults to GitVersion.yml).
  required: false
  default: ''
updateAssemblyInfo:
  description: Whether to update versions in the AssemblyInfo files.
  required: false
  default: false
updateAssemblyInfoFilename:
  description: Update versions in specified file.
  required: false
  default: ''
additionalArguments:
  description: Additional arguments to send to GitVersion.
  required: false
  default: ''

Task outputs

The Execute GitVersion task creates the following job-scoped variables and multi-job output variables:

  • GitVersion.Major
  • GitVersion.Minor
  • GitVersion.Patch
  • GitVersion.PreReleaseTag
  • GitVersion.PreReleaseTagWithDash
  • GitVersion.PreReleaseLabel
  • GitVersion.PreReleaseNumber
  • GitVersion.WeightedPreReleaseNumber
  • GitVersion.BuildMetaData
  • GitVersion.BuildMetaDataPadded
  • GitVersion.FullBuildMetaData
  • GitVersion.MajorMinorPatch
  • GitVersion.SemVer
  • GitVersion.LegacySemVer
  • GitVersion.LegacySemVerPadded
  • GitVersion.AssemblySemVer
  • GitVersion.AssemblySemFileVer
  • GitVersion.FullSemVer
  • GitVersion.InformationalVersion
  • GitVersion.BranchName
  • GitVersion.EscapedBranchName
  • GitVersion.Sha
  • GitVersion.ShortSha
  • GitVersion.NuGetVersionV2
  • GitVersion.NuGetVersion
  • GitVersion.NuGetPreReleaseTagV2
  • GitVersion.NuGetPreReleaseTag
  • GitVersion.VersionSourceSha
  • GitVersion.CommitsSinceVersionSource
  • GitVersion.CommitsSinceVersionSourcePadded
  • GitVersion.UncommittedChanges
  • 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 multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples 7 to 10.

GitVersion also automatically updates the pre-defined Build variable Build.BuildNumber.

Examples

  • Example 1: Calculate the version for the build.

    steps:
  - 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.

    steps:
  - task: gitversion/execute@0
    displayName: Determine Version
    inputs:
      useConfigFile: true

    Example contents of GitVersion.yml:

    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.

    steps:
  - 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).

    steps:
  - 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.

    - 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.

    - 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.

    job: CalculateVersion
displayName: Calculate version using GitVersion
steps:
  - task: gitversion/setup@0
    displayName: Install GitVersion
    inputs:
      versionSpec: '5.x'

   - 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.

    job: CalculateVersion
displayName: Calculate version using GitVersion
steps:
  - task: gitversion/setup@0
    displayName: Install GitVersion
    inputs:
      versionSpec: '5.x'

   - 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'] ]
steps:

  • Example 9: 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:
          - task: gitversion/setup@0
            displayName: Install GitVersion
            inputs:
              versionSpec: '5.x'

          - 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.

    stages:
  - stage: S1
    jobs:
      - job: CalculateVersion
        displayName: Calculate version number using GitVersion
        steps:
          - task: gitversion/setup@0
            displayName: Install GitVersion
            inputs:
              versionSpec: '5.x'

          - 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.
Reference in New Issue View Git Blame Copy Permalink